MI-331: Guard versioning aspect against CDK-managed singletons

.changeset/guard-versioning-aspect-singletons.md

@@ -0,0 +1,5 @@
+---
+"@aligent/cdk-aspects": patch
+---
+
+Skip CDK-managed singleton/framework resources in `LambdaAndStepFunctionVersioningAspect` so it no longer adds aliases/versions to handlers like the `BucketDeployment` custom resource.

packages/cdk-aspects/lib/lambda-sfn-versioning.test.ts

@@ -0,0 +1,42 @@
+import { App, Aspects, Stack } from "aws-cdk-lib";
+import { Template } from "aws-cdk-lib/assertions";
+import { Bucket } from "aws-cdk-lib/aws-s3";
+import { BucketDeployment, Source } from "aws-cdk-lib/aws-s3-deployment";
+import { LambdaAndStepFunctionVersioningAspect } from "./lambda-sfn-versioning";
+
+describe("LambdaAndStepFunctionVersioningAspect", () => {
+  describe("CDK-managed singletons", () => {
+    // BucketDeployment provisions a framework-owned singleton handler Lambda that
+    // the consumer cannot reference. Versioning it creates aliases nobody can use
+    // and that the consumer does not own.
+    const synthWithBucketDeployment = () => {
+      const bundlingApp = new App({
+        context: { "aws:cdk:bundling-stacks": [] },
+      });
+      const bundlingStack = new Stack(bundlingApp, "TestStack");
+      Aspects.of(bundlingStack).add(
+        new LambdaAndStepFunctionVersioningAspect()
+      );
+
+      const bucket = new Bucket(bundlingStack, "DeployBucket");
+      new BucketDeployment(bundlingStack, "DeployAssets", {
+        destinationBucket: bucket,
+        sources: [Source.data("hello.txt", "hello world")],
+      });
+
+      bundlingApp.synth();
+      return bundlingStack;
+    };
+
+    it("should not add an alias to the BucketDeployment handler lambda", () => {
+      const synthStack = synthWithBucketDeployment();
+
+      const template = Template.fromStack(synthStack);
+      const aliases = template.findResources("AWS::Lambda::Alias");
+      const singletonAlias = Object.keys(aliases).find(id =>
+        id.includes("CustomCDKBucketDeployment")
+      );
+      expect(singletonAlias).toBeUndefined();
+    });
+  });
+});

packages/cdk-aspects/lib/lambda-sfn-versioning.ts

@@ -6,6 +6,7 @@ import {
   StateMachine,
 } from "aws-cdk-lib/aws-stepfunctions";
 import { IConstruct } from "constructs";
+import { isCdkManagedSingleton } from "./cdk-managed-singletons";
 
 /**
  * Aspect that automatically adds versioning and aliases to Lambda and Step Functions
@@ -51,6 +52,11 @@ export class LambdaAndStepFunctionVersioningAspect implements IAspect {
    * @param node - The construct to potentially add versioning to
    */
   visit(node: IConstruct): void {
+    // CDK-managed singleton/framework resources (e.g. the BucketDeployment
+    // handler, cr.Provider on-event handler) are consumer-invisible — versioning
+    // them creates aliases the consumer cannot reference and doesn't own.
+    if (isCdkManagedSingleton(node)) return;
+
     if (node instanceof StateMachine) {
       const version = new CfnStateMachineVersion(node, `Version`, {
         stateMachineArn: node.stateMachineArn,