feat(gen2-migration): handling cdk custom resource dependencies

[sanjanaravikumar-az]

Overview

This PR implements comprehensive support for migrating Amplify Gen1 custom resource dependencies to Gen2 during the migration process. Previously, custom resources with AmplifyHelpers.addResourceDependency calls would fail migration with an error message directing users to manual migration documentation.

Why Resource Dependencies Need Special Handling in Gen1 vs Gen2:

Gen1 Dependency Model:

• Uses CloudFormation-based dependency injection via AmplifyHelpers.addResourceDependency()
• Dependencies are resolved at deployment time through CloudFormation stack references
• Resources access other resources through CloudFormation outputs and parameters
• Example: amplifyResources.auth.userPool.userPoolId resolves to CloudFormation stack outputs

Gen2 Dependency Model:

• Uses TypeScript constructor injection with direct object references
• Dependencies are resolved at build time through the backend definition
• Resources receive dependency objects as constructor parameters
• Example: auth.resources.userPool.userPoolId directly accesses the backend auth construct

Key Changes

1. Dependency Extraction (extractResourceDependencies)

• Parses Gen1 custom resource files to identify AmplifyHelpers.addResourceDependency calls
• Extracts category dependencies (auth, storage, api, function) from dependency arrays
• Maps Gen1 categories to Gen2 backend property names

2. AST Transformation (AmplifyHelperTransformer)

• Dependency Tracking: Identifies and removes AmplifyHelpers.addResourceDependency variable statements
• Constructor Transformation: Adds resource dependency parameters to custom resource constructor
• Property Access Mapping: Transforms Gen1 resource references to Gen2 equivalents:
• amplifyResources.auth.userPool.userPoolId → auth.resources.userPool.userPoolId
• amplifyResources.storage.bucket.bucketName → storage.resources.bucket.bucketName
• amplifyResources.function.myFunc.functionArn → functions.myFunc.resources.lambda.functionArn

3. Backend Registration (BackendUpdater)

• Generates TypeScript imports for custom resources
• Creates instantiation statements with proper dependency injection
• Maps Gen1 categories to Gen2 backend properties (function→functions, api→data)

Gen1:

// Custom resource constructor
constructor(scope: Construct, id: string, props: AmplifyResourceProps) {
  super(scope, id, props);
  
  const dependencies = AmplifyHelpers.addResourceDependency(this, props.category, props.resourceName, [
    { category: "auth", resourceName: "userPool" },
    { category: "storage", resourceName: "s3Bucket" }
  ]);
  
  // Access resources through CloudFormation outputs
  const userPoolId = amplifyResources.auth.userPool.userPoolId;
}

Gen2:

// Custom resource constructor with dependency injection. This is in resource.ts.
constructor(scope: Construct, id: string, auth: any, storage: any) {
  super(scope, id);
  
  // Direct access to backend resources
  const userPoolId = auth.resources.userPool.userPoolId;
}

// Backend registration with dependencies. This is in backend.ts.
new myCustomResource(backend.createStack("myCustomResource"), "myCustomResource", backend.auth, backend.storage);

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[dgandhi62]

Left some comments. Mainly clarifying questions

[iankhou]

How were these changes tested? If manually tested, can you include the steps to reproduce manual verification?

[sanjanaravikumar-az]

How were these changes tested? If manually tested, can you include the steps to reproduce manual verificatio

Yes, I manually tested it:

1. Set up an Amplify test app with various resource dependency patterns in cdk-stack.ts using Gen1 syntax (e.g., amplifyResources.auth.userPool.userPoolId)
2. Executed the lock and generate migration commands
3. Compared the generated output line-by-line against expected Gen2 syntax, validated against official Gen2 documentation and codebase examples

All transformations produced the correct Gen2 paths.

[dgandhi62]

There are merge conflicts. There is also one pending change I have about unsupported categories map. Could you ping me once those are solved, I'll approve it