feat(core): include suppressed violations in validation-report.json (#38009)

## Summary

- Suppressed violations are now included in `validation-report.json` under a `suppressedViolations` array per plugin report, providing an audit trail.
- Each suppressed violation entry includes the full violation details plus `acknowledgedId`, `reason`, and `acknowledgedAt` (the construct path where `acknowledge()` was called).
- Suppressed violations remain excluded from the active `violations` list, the pretty-printed output, and the success/failure determination.
- `collectAcknowledgedRuleIds` now returns a `Map<string, AcknowledgedRule>` (with reason + construct path) instead of a bare `Set<string>`.

Schema: aws/aws-cdk-cli#1556

## Test plan

- [x] New test: `suppressed violations appear in validation-report.json` — verifies the JSON report contains the suppressed violation with all metadata
- [x] Existing suppression tests continue to pass (active violations removed, fatal violations retained)
- [x] Full validation test suite passes (49/49)

Author: kaizencc

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

@@ -1,19 +1,30 @@
 import type { IConstruct } from 'constructs';
 import { iterateDfsPreorder } from './construct-iteration';
 
+export interface AcknowledgedRule {
+  readonly reason: string;
+  readonly constructPath: string;
+  readonly stackTrace?: string;
+}
+
 /**
  * Collect all acknowledged rule IDs from construct metadata across the tree.
+ * Returns a map from rule ID to acknowledgement details (reason, construct path, and stack trace).
  */
-export function collectAcknowledgedRuleIds(root: IConstruct): Set<string> {
-  const ids = new Set<string>();
+export function collectAcknowledgedRuleIds(root: IConstruct): Map<string, AcknowledgedRule> {
+  const rules = new Map<string, AcknowledgedRule>();
   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);
+        for (const [id, reason] of Object.entries(entry.data as Record<string, string>)) {
+          rules.set(id, {
+            reason,
+            constructPath: construct.node.path,
+            stackTrace: entry.trace?.join('\n'),
+          });
         }
       }
     }
   }
-  return ids;
+  return rules;
 }

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

@@ -24,7 +24,7 @@ import type { StageSynthesisOptions } from '../stage';
 import { Stage } from '../stage';
 import type { IPolicyValidationPlugin } from '../validation';
 import { ConstructTree } from '../validation/private/construct-tree';
-import type { NamedValidationPluginReport } from '../validation/private/report';
+import type { NamedValidationPluginReport, SuppressedViolation } from '../validation/private/report';
 import { PolicyValidationReportFormatter } from '../validation/private/report';
 
 const LEGACY_POLICY_VALIDATION_FILE_PATH = 'policy-validation-report.json';
@@ -174,20 +174,38 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
   // 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) {
+  const acknowledgedRules = collectAcknowledgedRuleIds(root);
+  const suppressedByReport: Map<number, SuppressedViolation[]> = new Map();
+  if (acknowledgedRules.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 active: typeof reports[0]['violations'] = [];
+      const suppressed: SuppressedViolation[] = [];
+      for (const v of reports[i].violations) {
+        if (v.severity === 'fatal') {
+          active.push(v);
+          continue;
+        }
         const ruleId = `${pluginName}::${v.ruleName.replace(/ /g, '-')}`;
-        return !acknowledgedRuleIds.has(ruleId);
-      });
-      if (filtered.length !== reports[i].violations.length) {
+        const ack = acknowledgedRules.get(ruleId);
+        if (ack) {
+          suppressed.push({
+            ...v,
+            acknowledgedId: ruleId,
+            reason: ack.reason,
+            acknowledgedAt: ack.constructPath,
+            acknowledgedStackTrace: ack.stackTrace,
+          });
+        } else {
+          active.push(v);
+        }
+      }
+      if (suppressed.length > 0) {
+        suppressedByReport.set(i, suppressed);
         reports[i] = {
           ...reports[i],
-          violations: filtered,
-          success: filtered.every(v => v.severity !== 'error' && v.severity !== 'fatal'),
+          violations: active,
+          success: active.every(v => v.severity !== 'error' && v.severity !== 'fatal'),
         };
       }
     }
@@ -200,7 +218,7 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
     const writeLegacyReport = getBooleanContext(root, cxapi.VALIDATION_REPORT_JSON_CONTEXT, false);
 
     const reportFile = path.join(assembly.directory, cxapi.VALIDATION_REPORT_FILE);
-    const jsonOutput = formatter.formatJson(reports, assembly.version);
+    const jsonOutput = formatter.formatJson(reports, assembly.version, suppressedByReport);
     fs.writeFileSync(reportFile, JSON.stringify(jsonOutput, undefined, 2));
 
     if (writeLegacyReport) {

packages/aws-cdk-lib/core/lib/validation/private/report.ts

@@ -118,6 +118,7 @@ export interface PluginReportJson {
   readonly conclusion: PolicyValidationReportConclusion;
   readonly metadata?: { readonly [key: string]: string };
   readonly violations: PolicyViolationJson[];
+  readonly suppressedViolations?: SuppressedViolationJson[];
 }
 
 export type PolicyValidationReportConclusion = 'success' | 'failure';
@@ -148,6 +149,24 @@ export interface CloudFormationResourceJson {
   readonly propertyPaths?: string[];
 }
 
+export interface SuppressedViolationJson extends PolicyViolationJson {
+  readonly acknowledgedId: string;
+  readonly reason?: string;
+  readonly acknowledgedAt?: string;
+  readonly acknowledgedStackTrace?: string;
+}
+
+/**
+ * A violation that was suppressed, carrying acknowledgement metadata.
+ * Used internally to pass suppressed violations from synthesis to the formatter.
+ */
+export interface SuppressedViolation extends report.PolicyViolation {
+  readonly acknowledgedId: string;
+  readonly reason?: string;
+  readonly acknowledgedAt?: string;
+  readonly acknowledgedStackTrace?: string;
+}
+
 /**
  * The report emitted by the plugin after evaluation.
  */
@@ -280,65 +299,97 @@ export class PolicyValidationReportFormatter {
     };
   }
 
-  public formatJson(reps: NamedValidationPluginReport[], schemaVersion: string): PolicyValidationReportJson {
+  public formatJson(
+    reps: NamedValidationPluginReport[],
+    schemaVersion: string,
+    suppressedByReport?: Map<number, SuppressedViolation[]>,
+  ): PolicyValidationReportJson {
     return {
       version: schemaVersion,
       title: 'Validation Report',
-      pluginReports: reps
-        .filter(rep => !rep.success || rep.violations.length > 0)
-        .map(rep => ({
-          pluginName: rep.pluginName,
-          pluginVersion: rep.pluginVersion,
-          conclusion: (rep.success ? 'success' : 'failure') as PolicyValidationReportConclusion,
-          metadata: rep.metadata,
-          violations: rep.violations.map(violation => {
-            const severity = normalizeSeverity(violation.severity);
-            return {
-              ruleName: violation.ruleName,
-              description: violation.description,
-              suggestedFix: violation.fix,
-              severity: severity.severity,
-              customSeverity: severity.customSeverity,
-              ruleMetadata: violation.ruleMetadata,
-              violatingConstructs: violation.violatingResources.map(resource => {
-                const constructPath = resource.constructPath ?? (
-                  resource.templatePath && resource.resourceLogicalId
-                    ? this.tree.getConstructByLogicalId(
-                      path.basename(resource.templatePath),
-                      resource.resourceLogicalId,
-                    )?.node.path
-                    : undefined
-                );
-                const construct = constructPath
-                  ? this.tree.getConstructByPath(constructPath)
-                  : undefined;
-                const constructInfo = construct
-                  ? this.tree.constructTraceLevelFromTreeNode(construct)
-                  : undefined;
-
-                const result: ViolatingConstructJson = {
-                  constructPath: constructPath ?? 'N/A',
-                  constructFqn: constructInfo?.construct,
-                  libraryVersion: constructInfo?.libraryVersion,
-                  cloudFormationResource: resource.resourceLogicalId && resource.templatePath
-                    ? {
-                      templatePath: resource.templatePath,
-                      logicalId: resource.resourceLogicalId,
-                      propertyPaths: resource.locations.length > 0 ? resource.locations : undefined,
-                    }
-                    : undefined,
-                  stackTraces: constructPath
-                    ? this.formatStackTraces(constructPath)
-                    : undefined,
-                };
-                return result;
-              }),
-            };
-          }),
-        })),
+      pluginReports: this.buildPluginReports(reps, suppressedByReport),
     };
   }
 
+  private formatViolationJson(violation: report.PolicyViolation): PolicyViolationJson {
+    const severity = normalizeSeverity(violation.severity);
+    return {
+      ruleName: violation.ruleName,
+      description: violation.description,
+      suggestedFix: violation.fix,
+      severity: severity.severity,
+      customSeverity: severity.customSeverity,
+      ruleMetadata: violation.ruleMetadata,
+      violatingConstructs: violation.violatingResources.map(resource => {
+        const constructPath = resource.constructPath ?? (
+          resource.templatePath && resource.resourceLogicalId
+            ? this.tree.getConstructByLogicalId(
+              path.basename(resource.templatePath),
+              resource.resourceLogicalId,
+            )?.node.path
+            : undefined
+        );
+        const construct = constructPath
+          ? this.tree.getConstructByPath(constructPath)
+          : undefined;
+        const constructInfo = construct
+          ? this.tree.constructTraceLevelFromTreeNode(construct)
+          : undefined;
+
+        const result: ViolatingConstructJson = {
+          constructPath: constructPath ?? 'N/A',
+          constructFqn: constructInfo?.construct,
+          libraryVersion: constructInfo?.libraryVersion,
+          cloudFormationResource: resource.resourceLogicalId && resource.templatePath
+            ? {
+              templatePath: resource.templatePath,
+              logicalId: resource.resourceLogicalId,
+              propertyPaths: resource.locations.length > 0 ? resource.locations : undefined,
+            }
+            : undefined,
+          stackTraces: constructPath
+            ? this.formatStackTraces(constructPath)
+            : undefined,
+        };
+        return result;
+      }),
+    };
+  }
+
+  private formatSuppressedViolationJson(sv: SuppressedViolation): SuppressedViolationJson {
+    const base = this.formatViolationJson(sv);
+    return {
+      ...base,
+      acknowledgedId: sv.acknowledgedId,
+      reason: sv.reason || undefined,
+      acknowledgedAt: sv.acknowledgedAt || undefined,
+      acknowledgedStackTrace: sv.acknowledgedStackTrace || undefined,
+    };
+  }
+
+  private buildPluginReports(
+    reps: NamedValidationPluginReport[],
+    suppressedByReport?: Map<number, SuppressedViolation[]>,
+  ): PluginReportJson[] {
+    const results: PluginReportJson[] = [];
+    for (let idx = 0; idx < reps.length; idx++) {
+      const rep = reps[idx];
+      const suppressed = suppressedByReport?.get(idx);
+      if (rep.success && rep.violations.length === 0 && !suppressed) continue;
+      results.push({
+        pluginName: rep.pluginName,
+        pluginVersion: rep.pluginVersion,
+        conclusion: (rep.success ? 'success' : 'failure') as PolicyValidationReportConclusion,
+        metadata: rep.metadata,
+        violations: rep.violations.map(violation => this.formatViolationJson(violation)),
+        suppressedViolations: suppressed
+          ? suppressed.map(sv => this.formatSuppressedViolationJson(sv))
+          : undefined,
+      });
+    }
+    return results;
+  }
+
   private formatStackTraces(constructPath: string): string[] | undefined {
     const trace = this.reportTrace.formatJson(constructPath);
     if (!trace) return undefined;

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

@@ -134,13 +134,11 @@ export class Validations {
   }
 
   private recordAcknowledgment(id: string, reason: string): void {
-    const matches = this.scope.node.metadata.filter(
-      (m: { type: string }) => m.type === Validations.ACKNOWLEDGED_RULES_METADATA_KEY,
+    this.scope.node.addMetadata(
+      Validations.ACKNOWLEDGED_RULES_METADATA_KEY,
+      { [id]: reason },
+      { stackTrace: true },
     );
-    const existing = matches.length > 0 ? matches[matches.length - 1] : undefined;
-    const acknowledged: Record<string, string> = existing?.data ?? {};
-    acknowledged[id] = reason;
-    this.scope.node.addMetadata(Validations.ACKNOWLEDGED_RULES_METADATA_KEY, acknowledged);
   }
 
   private qualifyId(id: string): string {