fix(assertions): throw error or warn when synth is called multiple times on mutated construct tree

packages/aws-cdk-lib/core/lib/app.ts

@@ -192,7 +192,7 @@ export class App extends Stage {
     if (autoSynth) {
       // synth() guarantees it will only execute once, so a default of 'true'
       // doesn't bite manual calling of the function.
-      process.once('beforeExit', () => this.synth());
+      process.once('beforeExit', () => this.synth({ warnInsteadOfError: true }));
     }
 
     this._treeMetadata = props.treeMetadata ?? true;

packages/aws-cdk-lib/core/lib/stage.ts

@@ -1,4 +1,5 @@
 import { IConstruct, Construct, Node } from 'constructs';
+import { Annotations } from './annotations';
 import { Environment } from './environment';
 import { PermissionsBoundary } from './permissions-boundary';
 import { synthesize } from './private/synthesis';
@@ -146,6 +147,11 @@ export class Stage extends Construct {
    */
   private assembly?: cxapi.CloudAssembly;
 
+  /**
+   * The cached set of construct paths. Empty if assembly was not yet built.
+   */
+  private constructPathsCache: Set<string>;
+
   /**
    * Validation plugins to run during synthesis. If any plugin reports any violation,
    * synthesis will be interrupted and the report displayed to the user.
@@ -163,6 +169,7 @@ export class Stage extends Construct {
 
     Object.defineProperty(this, STAGE_SYMBOL, { value: true });
 
+    this.constructPathsCache = new Set<string>();
     this.parentStage = Stage.of(this);
 
     this.region = props.env?.region ?? this.parentStage?.region;
@@ -210,13 +217,52 @@ export class Stage extends Construct {
    * calls will return the same assembly.
    */
   public synth(options: StageSynthesisOptions = { }): cxapi.CloudAssembly {
-    if (!this.assembly || options.force) {
+
+    const newConstructPaths = new Set<string>();
+    recurseAndlistAllConstructPaths(this);
+
+    // If the assembly cache is uninitiazed, run synthesize and reset construct paths cache
+    if (this.constructPathsCache.size == 0 || !this.assembly || options.force) {
       this.assembly = synthesize(this, {
         skipValidation: options.skipValidation,
         validateOnSynthesis: options.validateOnSynthesis,
       });
+      recurseAndlistAllConstructPaths(this);
+      this.constructPathsCache = newConstructPaths;
+    }
+
+    // Lists all construct paths
+    function recurseAndlistAllConstructPaths(construct: IConstruct) {
+      newConstructPaths.add(construct.node.path);
+      for (const child of construct.node.children) {
+        if (!Stage.isStage(child)) {
+          recurseAndlistAllConstructPaths(child);
+        }
+      }
+    }
+
+    // If the construct paths set has changed
+    if (!constructPathSetsAreEqual(this.constructPathsCache, newConstructPaths)) {
+      if (options.warnInsteadOfError) {
+        Annotations.of(this).addWarningV2('@aws-cdk/core:synth-warning', 'The construct tree was modified since the last synth call. Re-synthesizing with modifications can lead to inconsistent states. For reliable results, avoid construct mutations between synth calls.');
+      } else {
+        throw new Error('The construct tree was modified after the initial synthesis (synth) call. Avoid modifying the construct tree between synth calls as this can cause unexpected behavior.');
+      }
+    }
+
+    function constructPathSetsAreEqual(set1: Set<string>, set2: Set<string>): boolean {
+      if (set1.size !== set2.size) return false;
+      for (const id of set1) {
+        if (!set2.has(id)) {
+          return false;
+        }
+      }
+      return true;
     }
 
+    // Reset construct paths cache
+    this.constructPathsCache = newConstructPaths;
+
     return this.assembly;
   }
 
@@ -259,4 +305,11 @@ export interface StageSynthesisOptions {
    * @default false
    */
   readonly force?: boolean;
+
+  /**
+   * Whether or not to throw a warning instead of an error if the construct tree has
+   * been mutated since the last synth.
+   * @default false
+   */
+  readonly warnInsteadOfError?: boolean;
 }

packages/aws-cdk-lib/core/test/synthesis.test.ts

@@ -3,6 +3,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { testDeprecated } from '@aws-cdk/cdk-build-tools';
 import { Construct } from 'constructs';
+import { Template } from '../../assertions';
 import * as cxschema from '../../cloud-assembly-schema';
 import * as cxapi from '../../cx-api';
 import * as cdk from '../lib';
@@ -362,6 +363,30 @@ describe('synthesis', () => {
 
   });
 
+  test('calling synth multiple times errors if construct tree is mutated', () => {
+    const app = new cdk.App();
+
+    const stages = [
+      {
+        stage: 'PROD',
+      },
+      {
+        stage: 'BETA',
+      },
+    ];
+
+    // THEN - no error the first time synth is called
+    let stack = new cdk.Stack(app, `${stages[0].stage}-Stack`, {});
+    expect(() => {
+      Template.fromStack(stack);
+    }).not.toThrow();
+
+    // THEN - error is thrown since synth was called with mutated stack name
+    stack = new cdk.Stack(app, `${stages[1].stage}-Stack`, {});
+    expect(() => {
+      Template.fromStack(stack);
+    }).toThrow('The construct tree was modified after the initial synthesis (synth) call.');
+  });
 });
 
 function list(outdir: string) {

packages/aws-cdk-lib/pipelines/test/compliance/synths.test.ts

@@ -186,6 +186,27 @@ test('CodeBuild: environment variables specified in multiple places are correctl
     }),
   });
 
+  new ModernTestGitHubNpmPipeline(pipelineStack, 'Cdk-2', {
+    synth: new cdkp.CodeBuildStep('Synth', {
+      input: cdkp.CodePipelineSource.gitHub('test/test', 'main'),
+      primaryOutputDirectory: '.',
+      env: {
+        SOME_ENV_VAR: 'SomeValue',
+      },
+      installCommands: [
+        'install1',
+        'install2',
+      ],
+      commands: ['synth'],
+      buildEnvironment: {
+        environmentVariables: {
+          INNER_VAR: { value: 'InnerValue' },
+        },
+        privileged: true,
+      },
+    }),
+  });
+
   // THEN
   Template.fromStack(pipelineStack).hasResourceProperties('AWS::CodeBuild::Project', {
     Environment: Match.objectLike({
@@ -217,27 +238,6 @@ test('CodeBuild: environment variables specified in multiple places are correctl
     },
   });
 
-  new ModernTestGitHubNpmPipeline(pipelineStack, 'Cdk-2', {
-    synth: new cdkp.CodeBuildStep('Synth', {
-      input: cdkp.CodePipelineSource.gitHub('test/test', 'main'),
-      primaryOutputDirectory: '.',
-      env: {
-        SOME_ENV_VAR: 'SomeValue',
-      },
-      installCommands: [
-        'install1',
-        'install2',
-      ],
-      commands: ['synth'],
-      buildEnvironment: {
-        environmentVariables: {
-          INNER_VAR: { value: 'InnerValue' },
-        },
-        privileged: true,
-      },
-    }),
-  });
-
   // THEN
   Template.fromStack(pipelineStack).hasResourceProperties('AWS::CodeBuild::Project', {
     Environment: Match.objectLike({