Merge branch 'main' into dependabot/github_actions/actions/github-script-9

Author: mergify[bot]

AGENTS.md

@@ -175,12 +175,36 @@ Tokens can encode strings, numbers, and lists. Any object implementing `IResolva
 - Use `Tokenization.stringifyNumber()` to safely convert a possibly-tokenized number to string
 - Don't use resource attributes (Tokens) in hash calculations for physical names
 
-### Lazy Values
+### Deferred Values (Box API)
+
+L2 constructs that accumulate state after construction (e.g., adding actions, policy statements, security groups) MUST use the **Box API** to defer value resolution — not `Lazy`. Boxes implement `IResolvable` and capture stack traces at mutation call sites (under `CDK_DEBUG`), enabling accurate property attribution in synthesized templates.
+
+- Use `Box.fromArray<T>([])` for accumulator lists, `Box.fromValue<T>(initial)` for single values, `Box.fromMap<K,V>()` for maps, `Box.fromSet<A>()` for sets
+- Pass to L1 props via `Token.asList(box)`, `Token.asString(box)`, `Token.asNumber(box)`, or `Token.asAny(box)` for complex/object values
+- `Box.fromArray` resolves to `undefined` when empty (omitEmpty default) — no manual empty-array check needed. Pass `{ omitEmpty: false }` to resolve to an empty array instead
+- Mutate via `box.push(item)` or `box.set(newValue)` — each captures a stack trace at the call site
+- Use `box.derive(fn)` for single-source transforms or `Box.combine({ name: box, ... }, ({ name, ... }) => ...)` for multi-source derived values
+- Apply `@noBoxStackTraces` decorator on L2 classes that create or mutate Boxes in their constructor (suppresses irrelevant internal traces)
+- NEVER mutate construct tree in Lazy or Box callbacks
+
+`Lazy` is legacy — existing code still uses it but new L2 constructs MUST prefer Boxes. See `packages/aws-cdk-lib/core/adr/box-api.md` for full rationale.
+
+**Before (legacy — do not use in new code):**
+```ts
+alarmActions: Lazy.list({ produce: () => this.alarmActionArns }),
+```
+
+**After (preferred):**
+```ts
+protected readonly _alarmActionArns: IArrayBox<string> = Box.fromArray([]);
+// in constructor:
+alarmActions: Token.asList(this._alarmActionArns),
+// in mutating method:
+this._alarmActionArns.push(newArn); // stack trace captured here
+```
 
-- `Lazy.any()` for arrays: pass `{ omitEmptyArray: true }`
 - Map empty arrays to `undefined` for CFN properties
 - Optional nested CFN objects: `undefined` (not `{}`) when no sub-properties set
-- NEVER mutate construct tree in Lazy callbacks
 
 ### ARN Construction
 

docs/DESIGN_GUIDELINES.md

@@ -2043,26 +2043,82 @@ information that can be obtained from the stack trace.
 
 * Do not use FnSub
 
-### Lazys
+### Deferred Values
 
-Do not use a `Lazy` to perform a mutation on the construct tree. For example:
+#### Box API (preferred for new code)
+
+L2 constructs that accumulate state after construction (e.g., alarm actions, policy
+statements, security group rules) should use the **Box API** instead of `Lazy`.
+Boxes are mutable containers that implement `IResolvable` and capture stack traces
+at mutation call sites, enabling accurate property-to-source-code attribution.
+
+**Before (Lazy — legacy, do not use in new code):**
+
+```ts
+class MyL2 extends Resource {
+  private readonly _actions: string[] = [];
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    new CfnResource(this, 'Resource', {
+      // Stack trace captured HERE (constructor), not useful
+      actions: Lazy.list({ produce: () => this._actions }),
+    });
+  }
+
+  addAction(action: string) {
+    this._actions.push(action); // No stack trace captured
+  }
+}
+```
+
+**After (Box — preferred):**
 
 ```ts
-constructor(scope: Scope, id: string, props: MyConstructProps) {
-  this.lazyProperty = Lazy.any({
-    produce: () => {
-      return props.logging.bind(this, this);
-    },
-  });
+@noBoxStackTraces
+class MyL2 extends Resource {
+  private readonly _actions: IArrayBox<string> = Box.fromArray([]);
+
+  constructor(scope: Construct, id: string) {
+    super(scope, id);
+    new CfnResource(this, 'Resource', {
+      actions: Token.asList(this._actions),
+    });
+  }
+
+  addAction(action: string) {
+    this._actions.push(action); // Stack trace captured HERE — user's code
+  }
 }
 ```
 
-`bind()` methods mutate the construct tree, and should not be called from a callback
-in a `Lazy`.
+Key rules:
+- `Box.fromArray([])` for lists, `Box.fromValue(x)` for scalars, `Box.fromMap()` for maps, `Box.fromSet()` for sets
+- Pass to L1 via `Token.asList(box)`, `Token.asString(box)`, `Token.asNumber(box)`, or `Token.asAny(box)` for complex/object values
+- `Box.fromArray` resolves to `undefined` when empty by default (no manual empty-array → `undefined` mapping needed). Pass `{ omitEmpty: false }` as the second argument to resolve to an empty array instead
+- Apply `@noBoxStackTraces` on classes that create or mutate Boxes in their constructor
+- Use `box.derive(fn)` for single-source transforms, `Box.combine({ a: boxA, b: boxB }, ({ a, b }) => ...)` for multi-source derived values
+
+See `packages/aws-cdk-lib/core/adr/box-api.md` for the full ADR.
 
-* The why:
- - `Lazy`s are called after the construct tree has already been sythesized. Mutating it
- at this point could have not-obvious consequences.
+#### Lazy (legacy)
+
+`Lazy` remains available and is not deprecated, but new L2 constructs should prefer
+Boxes for better debuggability. If you must use `Lazy`:
+
+- Do not use a `Lazy` to perform a mutation on the construct tree
+- `Lazy`s are resolved after the construct tree has been synthesized — mutating it
+  at that point has non-obvious consequences
+- For `Lazy.any()` wrapping arrays, pass `{ omitEmptyArray: true }` to resolve empty arrays to `undefined`
+
+```ts
+// DO NOT do this — bind() mutates the construct tree
+this.lazyProperty = Lazy.any({
+  produce: () => {
+    return props.logging.bind(this, this); // BAD: tree mutation in Lazy
+  },
+});
+```
 
 ## Documentation
 

packages/aws-cdk-lib/aws-events/README.md

@@ -379,4 +379,6 @@ const bus =  new EventBus(this, 'Bus', {
     });
 ```
 
+**Note**: Configuring logging on the event bus is required when using [vended logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html). Vended logs require that the event bus has logging enabled with the appropriate log configuration before logs can be delivered to the destination.
+
 See more [Specifying event bus log level](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-bus-logs.html#eb-event-bus-logs-level)

packages/aws-cdk-lib/core/lib/private/collect-acknowledged-rule-ids.ts

@@ -0,0 +1,19 @@
+import type { IConstruct } from 'constructs';
+import { iterateDfsPreorder } from './construct-iteration';
+
+/**
+ * Collect all acknowledged rule IDs from construct metadata across the tree.
+ */
+export function collectAcknowledgedRuleIds(root: IConstruct): Set<string> {
+  const ids = new Set<string>();
+  for (const construct of iterateDfsPreorder(root)) {
+    for (const entry of construct.node.metadata) {
+      if (entry.type === 'aws:cdk:acknowledged-rules' && entry.data) {
+        for (const id of Object.keys(entry.data as Record<string, string>)) {
+          ids.add(id);
+        }
+      }
+    }
+  }
+  return ids;
+}

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

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as private_cxapi from '@aws-cdk/cloud-assembly-api';
 import type { IConstruct } from 'constructs';
+import { collectAcknowledgedRuleIds } from './collect-acknowledged-rule-ids';
 import { iterateDfsPreorder } from './construct-iteration';
 import { generateFeatureFlagReport } from './feature-flag-report';
 import { lit } from './literal-string';
@@ -265,6 +266,32 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
     }
   }
 
+  // Filter out suppressed violations. Collect all acknowledged rule IDs
+  // from construct metadata across the tree, then remove matching violations
+  // from reports. Fatal violations cannot be suppressed.
+  //
+  // Rule matching: violations are matched as <pluginName>::<ruleName> with
+  // spaces replaced by dashes. Users suppress with:
+  //   Validations.of(x).acknowledge({ id: '<plugin-name>::<rule-id>' })
+  const acknowledgedRuleIds = collectAcknowledgedRuleIds(root);
+  if (acknowledgedRuleIds.size > 0) {
+    for (let i = 0; i < reports.length; i++) {
+      const pluginName = reports[i].pluginName.replace(/ /g, '-');
+      const filtered = reports[i].violations.filter(v => {
+        if (v.severity === 'fatal') return true;
+        const ruleId = `${pluginName}::${v.ruleName.replace(/ /g, '-')}`;
+        return !acknowledgedRuleIds.has(ruleId);
+      });
+      if (filtered.length !== reports[i].violations.length) {
+        reports[i] = {
+          ...reports[i],
+          violations: filtered,
+          success: filtered.every(v => v.severity !== 'error' && v.severity !== 'fatal'),
+        };
+      }
+    }
+  }
+
   if (reports.length > 0) {
     const tree = new ConstructTree(root);
     const formatter = new PolicyValidationReportFormatter(tree);

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

@@ -1049,6 +1049,98 @@ Policy Validation Report Summary
       const output = consoleErrorMock.mock.calls.map((c: any[]) => c[0]).join('\n');
       expect(output).toContain('my-lib:TestId (');
     });
+
+    test('plugin violations can be suppressed via Validations.acknowledge()', () => {
+      const app = new core.App({ context: annotationReportContext });
+      const stack = new core.Stack(app);
+      new core.CfnResource(stack, 'MyBucket', {
+        type: 'AWS::S3::Bucket',
+        properties: {},
+      });
+
+      core.Validations.of(app).addPlugins(
+        new FakePlugin('test-plugin', [{
+          description: 'S3 Bucket should have versioning enabled',
+          ruleName: 'S3_BUCKET_VERSIONING_ENABLED',
+          severity: 'error',
+          violatingResources: [{
+            locations: ['Properties/VersioningConfiguration'],
+            resourceLogicalId: 'MyBucket',
+            templatePath: '/path/to/Default.template.json',
+          }],
+        }]),
+      );
+
+      // Suppress the error-level violation using <pluginName>::<ruleId>
+      core.Validations.of(stack).acknowledge({ id: 'test-plugin::S3_BUCKET_VERSIONING_ENABLED', reason: 'Not needed for this bucket' });
+
+      app.synth();
+
+      const output = consoleErrorMock.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(output).not.toContain('S3_BUCKET_VERSIONING_ENABLED');
+    });
+
+    test('fatal plugin violations cannot be suppressed', () => {
+      const app = new core.App({ context: annotationReportContext });
+      const stack = new core.Stack(app);
+      new core.CfnResource(stack, 'Fake', {
+        type: 'AWS::S3::Bucket',
+        properties: {},
+      });
+
+      core.Validations.of(app).addPlugins(
+        new FakePlugin('test-plugin', [{
+          description: 'Unknown resource type',
+          ruleName: 'E9001',
+          severity: 'fatal',
+          violatingResources: [{
+            locations: [],
+            resourceLogicalId: 'BadResource',
+            templatePath: '/path/to/Default.template.json',
+          }],
+        }]),
+      );
+
+      // Attempt to suppress the fatal violation
+      core.Validations.of(stack).acknowledge({ id: 'test-plugin::E9001', reason: 'Trying to suppress fatal' });
+
+      app.synth();
+
+      const output = consoleErrorMock.mock.calls.map((c: any[]) => c[0]).join('\n');
+      // Fatal violations remain despite acknowledgment
+      expect(output).toContain('E9001');
+      expect(output).toContain('Unknown resource type');
+    });
+
+    test('plugin names with spaces use dashes in suppression IDs', () => {
+      const app = new core.App({ context: annotationReportContext });
+      const stack = new core.Stack(app);
+      new core.CfnResource(stack, 'Fake', {
+        type: 'AWS::S3::Bucket',
+        properties: {},
+      });
+
+      core.Validations.of(app).addPlugins(
+        new FakePlugin('My Plugin', [{
+          description: 'Some violation',
+          ruleName: 'MY RULE',
+          severity: 'error',
+          violatingResources: [{
+            locations: [],
+            resourceLogicalId: 'Fake',
+            templatePath: '/path/to/Default.template.json',
+          }],
+        }]),
+      );
+
+      // Suppress using dashes instead of spaces
+      core.Validations.of(stack).acknowledge({ id: 'My-Plugin::MY-RULE', reason: 'OK' });
+
+      app.synth();
+
+      const output = consoleErrorMock.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(output).not.toContain('MY RULE');
+    });
   });
 
   describe('Validations.of()', () => {