feat: generate stack definitions for refactoring (#477)

otaviomacedo · web-flow · commit e85cc3a94ec5 · 2025-05-09T10:43:57.000Z
Having a list of deployed stacks, and the mappings (either computed or
user provided), we have to generate a list of stack definitions to be
sent to the `createStackRefactor` API.

The function `generateStackDefinitions` is not yet used anywhere, other
than unit tests. Future PRs will use it to make the API call.

---
By submitting this pull request, I confirm that my contribution is made
under the terms of the Apache-2.0 license
diff --git a/packages/@aws-cdk/toolkit-lib/lib/api/refactoring/execution.ts b/packages/@aws-cdk/toolkit-lib/lib/api/refactoring/execution.ts
@@ -0,0 +1,53 @@
+import type { StackDefinition } from '@aws-sdk/client-cloudformation';
+import type { CloudFormationStack, ResourceMapping } from './cloudformation';
+import { ToolkitError } from '../../toolkit/toolkit-error';
+
+/**
+ * Generates a list of stack definitions to be sent to the CloudFormation API
+ * by applying each mapping to the corresponding stack template(s).
+ */
+export function generateStackDefinitions(mappings: ResourceMapping[], deployedStacks: CloudFormationStack[]): StackDefinition[] {
+  const templates = Object.fromEntries(
+    deployedStacks
+      .filter((s) =>
+        mappings.some(
+          (m) =>
+            // We only care about stacks that are part of the mappings
+            m.source.stack.stackName === s.stackName || m.destination.stack.stackName === s.stackName,
+        ),
+      )
+      .map((s) => [s.stackName, JSON.parse(JSON.stringify(s.template))]),
+  );
+
+  mappings.forEach((mapping) => {
+    const sourceStackName = mapping.source.stack.stackName;
+    const sourceLogicalId = mapping.source.logicalResourceId;
+    const sourceTemplate = templates[sourceStackName];
+
+    const destinationStackName = mapping.destination.stack.stackName;
+    const destinationLogicalId = mapping.destination.logicalResourceId;
+    if (templates[destinationStackName] == null) {
+      // The API doesn't allow anything in the template other than the resources
+      // that are part of the mappings. So we need to create an empty template
+      // to start adding resources to.
+      templates[destinationStackName] = { Resources: {} };
+    }
+    const destinationTemplate = templates[destinationStackName];
+
+    // Do the move
+    destinationTemplate.Resources[destinationLogicalId] = sourceTemplate.Resources[sourceLogicalId];
+    delete sourceTemplate.Resources[sourceLogicalId];
+  });
+
+  // CloudFormation doesn't allow empty stacks
+  for (const [stackName, template] of Object.entries(templates)) {
+    if (Object.keys(template.Resources ?? {}).length === 0) {
+      throw new ToolkitError(`Stack ${stackName} has no resources after refactor. You must add a resource to this stack. This resource can be a simple one, like a waitCondition resource type.`);
+    }
+  }
+
+  return Object.entries(templates).map(([stackName, template]) => ({
+    StackName: stackName,
+    TemplateBody: JSON.stringify(template),
+  }));
+}
diff --git a/packages/@aws-cdk/toolkit-lib/test/api/refactoring/refactoring.test.ts b/packages/@aws-cdk/toolkit-lib/test/api/refactoring/refactoring.test.ts
@@ -17,12 +17,10 @@ import {
   resourceMappings,
   resourceMovements,
 } from '../../../lib/api/refactoring';
-import type {
-  ResourceLocation,
-  ResourceMapping,
-  CloudFormationStack,
-} from '../../../lib/api/refactoring/cloudformation';
+import type { CloudFormationStack } from '../../../lib/api/refactoring/cloudformation';
+import { ResourceLocation, ResourceMapping } from '../../../lib/api/refactoring/cloudformation';
 import { computeResourceDigests } from '../../../lib/api/refactoring/digest';
+import { generateStackDefinitions } from '../../../lib/api/refactoring/execution';
 import { mockCloudFormationClient, MockSdkProvider } from '../../_helpers/mock-sdk';
 
 const cloudFormationClient = mockCloudFormationClient;
@@ -1380,6 +1378,316 @@ describe('environment grouping', () => {
   });
 });
 
+describe(generateStackDefinitions, () => {
+  const environment = {
+    name: 'test',
+    account: '333333333333',
+    region: 'us-east-1',
+  };
+
+  test('renames a resource within the same stack', () => {
+    const stack: CloudFormationStack = {
+      environment: environment,
+      stackName: 'Foo',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+          NotInvolved: {
+            Type: 'AWS::X::Y',
+          },
+        },
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack, 'Bucket1'), new ResourceLocation(stack, 'Bucket2')),
+    ];
+
+    const result = generateStackDefinitions(mappings, [stack]);
+    expect(result).toEqual([
+      {
+        StackName: 'Foo',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            // Not involved in the refactor, but still part of the
+            // original template. Should be included.
+            NotInvolved: {
+              Type: 'AWS::X::Y',
+            },
+            Bucket2: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+    ]);
+  });
+
+  test('moves a resource to another stack that has already been deployed', () => {
+    const stack1: CloudFormationStack = {
+      environment,
+      stackName: 'Stack1',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+          A: {
+            Type: 'AWS::A::A',
+          },
+        },
+      },
+    };
+
+    const stack2: CloudFormationStack = {
+      environment,
+      stackName: 'Stack2',
+      template: {
+        Resources: {
+          B: {
+            Type: 'AWS::B::B',
+          },
+        },
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket1'), new ResourceLocation(stack2, 'Bucket2')),
+    ];
+
+    const result = generateStackDefinitions(mappings, [stack1, stack2]);
+    expect(result).toEqual([
+      {
+        StackName: 'Stack1',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            // Wasn't touched by the refactor
+            A: {
+              Type: 'AWS::A::A',
+            },
+
+            // Bucket1 doesn't exist anymore
+          },
+        }),
+      },
+      {
+        StackName: 'Stack2',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            // Wasn't touched by the refactor
+            B: {
+              Type: 'AWS::B::B',
+            },
+
+            // Old Bucket1 is now Bucket2 here
+            Bucket2: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+    ]);
+  });
+
+  test('moves a resource to another stack that has not been deployed', () => {
+    const stack1: CloudFormationStack = {
+      environment,
+      stackName: 'Stack1',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+          A: {
+            Type: 'AWS::A::A',
+          },
+        },
+      },
+    };
+
+    const stack2: CloudFormationStack = {
+      environment,
+      stackName: 'Stack2',
+      template: {
+        Resources: {
+          B: {
+            Type: 'AWS::B::B',
+          },
+        },
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket1'), new ResourceLocation(stack2, 'Bucket2')),
+    ];
+
+    const result = generateStackDefinitions(mappings, [stack1]);
+    expect(result).toEqual([
+      {
+        StackName: 'Stack1',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            // Wasn't touched by the refactor
+            A: {
+              Type: 'AWS::A::A',
+            },
+
+            // Bucket1 doesn't exist anymore
+          },
+        }),
+      },
+      {
+        StackName: 'Stack2',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            // Old Bucket1 is now Bucket2 here
+            Bucket2: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+    ]);
+  });
+
+  test('multiple mappings', () => {
+    const stack1: CloudFormationStack = {
+      environment,
+      stackName: 'Stack1',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+          Bucket2: {
+            Type: 'AWS::S3::Bucket',
+          },
+        },
+      },
+    };
+
+    const stack2: CloudFormationStack = {
+      environment,
+      stackName: 'Stack2',
+      template: {
+        Resources: {
+          Bucket3: {
+            Type: 'AWS::S3::Bucket',
+          },
+        },
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket1'), new ResourceLocation(stack2, 'Bucket4')),
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket2'), new ResourceLocation(stack2, 'Bucket5')),
+      new ResourceMapping(new ResourceLocation(stack2, 'Bucket3'), new ResourceLocation(stack1, 'Bucket6')),
+    ];
+
+    const result = generateStackDefinitions(mappings, [stack1, stack2]);
+    expect(result).toEqual([
+      {
+        StackName: 'Stack1',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            Bucket6: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+      {
+        StackName: 'Stack2',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            Bucket4: {
+              Type: 'AWS::S3::Bucket',
+            },
+            Bucket5: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+    ]);
+  });
+
+  test('deployed stacks that are not in any mapping', () => {
+    const stack1: CloudFormationStack = {
+      environment,
+      stackName: 'Stack1',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+        },
+      },
+    };
+
+    const stack2: CloudFormationStack = {
+      environment,
+      stackName: 'Stack2',
+      template: {
+        Resources: {
+          Bucket2: {
+            Type: 'AWS::S3::Bucket',
+          },
+        },
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket1'), new ResourceLocation(stack1, 'Bucket3')),
+    ];
+
+    const result = generateStackDefinitions(mappings, [stack1, stack2]);
+    expect(result).toEqual([
+      {
+        StackName: 'Stack1',
+        TemplateBody: JSON.stringify({
+          Resources: {
+            Bucket3: {
+              Type: 'AWS::S3::Bucket',
+            },
+          },
+        }),
+      },
+    ]);
+  });
+
+  test('refactor should not create empty templates', () => {
+    const stack1: CloudFormationStack = {
+      environment,
+      stackName: 'Stack1',
+      template: {
+        Resources: {
+          Bucket1: {
+            Type: 'AWS::S3::Bucket',
+          },
+        },
+      },
+    };
+
+    const stack2: CloudFormationStack = {
+      environment,
+      stackName: 'Stack2',
+      template: {
+        Resources: {},
+      },
+    };
+
+    const mappings: ResourceMapping[] = [
+      new ResourceMapping(new ResourceLocation(stack1, 'Bucket1'), new ResourceLocation(stack2, 'Bucket2')),
+    ];
+
+    expect(() => generateStackDefinitions(mappings, [stack1, stack2]))
+      .toThrow(/Stack Stack1 has no resources after refactor/);
+  });
+});
+
 function toCfnMapping(m: ResourceMapping): CfnResourceMapping {
   return {
     Source: toCfnLocation(m.source),
