feat(core): integrate construct annotations into validation report (#37712)

### Reason for this change

Part of the [Validations RFC](aws/aws-cdk-rfcs#899).

This PR furthers the RFC by integrating construct annotations (warnings and errors added via `Annotations.of()` or `Validations.of()`) into the existing policy validation report. Currently, annotations are only surfaced through the CLI's standard metadata display and are not part of the validation report, meaning users who rely on the report for compliance visibility don't see annotation-based issues alongside plugin violations.

### Description of changes

Integrate construct annotations into the existing validation report pipeline by collecting annotation metadata post-synthesis and converting it into a `NamedValidationPluginReport` with source `"Construct Annotations"`. This is **not** the final unified report format discussed in the RFC — it is an integration of annotations as a "plugin" into the existing report framework and structure.

**`core/lib/private/synthesis.ts`:**
- `collectAnnotationReport()` — walks the full construct tree (including across Stage boundaries via `iterateDfsPreorder`) to collect `aws:cdk:warning` and `aws:cdk:error` metadata entries, converting them to `PolicyViolation` format. Violations are grouped by rule name + severity + description so that multiple constructs triggering the same rule appear as one violation with multiple resources.
- `extractRuleName()` — extracts the rule ID from `[ack: <id>]` tags when available; falls back to generic `aws-cdk:warning` / `aws-cdk:error` for untagged annotations (these cannot be acknowledged, so uniqueness is not required). Includes a coupling note documenting the dependency on the `ackTag()` format in `annotations.ts`.
- `findNearestResource()` — maps a construct to its nearest `CfnResource` for logical ID and template path resolution
- `invokeValidationPlugins()` — calls `collectAnnotationReport()` after plugin execution and merges the result into the `reports[]` array

**`core/lib/validation/private/report.ts`:**
- `formatJson` filter changed from `!rep.success` to `!rep.success || rep.violations.length > 0` so that warning-only reports (which are `success: true`) still render their violations. This is intentional — violations should always be visible regardless of the overall success status. This broadens behavior for all validation sources: a plugin returning `success: true` with violations would now appear in the report when it previously didn't.
- Report headers renamed from "Plugin Report" / "Plugin:" to "Validation Report" / "Source:" to accommodate non-plugin validation sources

**⚠️ User-visible output changes:** The report header and summary table labels have changed (`Plugin Report` → `Validation Report`, `Plugin:` → `Source:`, `Plugin` column → `Source`). CI scripts or tools that parse the text report output may need updating.

**`core/test/validation/validation.test.ts`:**
- 10 new tests covering: annotation warnings in report, annotation errors causing failure, acknowledged warnings excluded, partial acknowledgment via `Validations.of().acknowledge()`, annotations alongside plugins, annotations without plugins, orphan constructs (verifying construct path fallback), `Validations.of().addWarning`, `Validations.of().addError`, and `extractRuleName` regex coupling with `addWarningV2` format
- Updated test helpers to match renamed report headers

#### Sample output

Below is the validation report output showing a plugin (CfnGuardValidator) and construct annotations side-by-side:

```
Performing Policy Validations

Validation Report
-----------------

╔═══════════════════════════════╗
║       Validation Report       ║
║   Source: CfnGuardValidator   ║
║   Version: N/A                ║
║   Status: failure             ║
╚═══════════════════════════════╝


(Violations)

S3_BUCKET_VERSIONING_ENABLED (1 occurrences)
Severity: high

  Occurrences:

    - Construct Path: DemoStack/MyBucket/Resource
    - Template Path: <outdir>/DemoStack.template.json
    - Creation Stack:
	└──  DemoStack (DemoStack)
	     │ Construct: constructs.Construct
	     └──  MyBucket (DemoStack/MyBucket)
	          └──  Resource (DemoStack/MyBucket/Resource)
    - Resource ID: MyBucketF68F3FF0
    - Template Locations:
      > Properties/VersioningConfiguration

  Description: S3 Bucket should have versioning enabled
  How to fix: Set the "VersioningConfiguration.Status" property to "Enabled"

╔═══════════════════════════════════╗
║         Validation Report         ║
║   Source: Construct Annotations   ║
║   Version: N/A                    ║
║   Status: failure                 ║
╚═══════════════════════════════════╝


(Violations)

@aws-cdk/aws-s3:bucketNotEncrypted (1 occurrences)
Severity: warning

  Occurrences:

    - Construct Path: DemoStack/MyBucket/Resource
    - Template Path: <outdir>/DemoStack.template.json
    - Creation Stack:
	└──  DemoStack (DemoStack)
	     └──  MyBucket (DemoStack/MyBucket)
	          └──  Resource (DemoStack/MyBucket/Resource)
    - Resource ID: MyBucketF68F3FF0
    - Template Locations:

  Description: This bucket does not have default encryption enabled [ack: @aws-cdk/aws-s3:bucketNotEncrypted]

aws-cdk:error (1 occurrences)
Severity: error

  Occurrences:

    - Construct Path: DemoStack/MyQueue/Resource
    - Template Path: <outdir>/DemoStack.template.json
    - Creation Stack:
	└──  DemoStack (DemoStack)
	     └──  MyQueue (DemoStack/MyQueue)
	          └──  Resource (DemoStack/MyQueue/Resource)
    - Resource ID: MyQueueE6CA6235
    - Template Locations:

  Description: Queue does not have a dead letter queue configured

annotation::TopicNoEncryption (1 occurrences)
Severity: warning

  Occurrences:

    - Construct Path: DemoStack/MyTopic/Resource
    - Template Path: <outdir>/DemoStack.template.json
    - Creation Stack:
	└──  DemoStack (DemoStack)
	     └──  MyTopic (DemoStack/MyTopic)
	          └──  Resource (DemoStack/MyTopic/Resource)
    - Resource ID: MyTopic86869434
    - Template Locations:

  Description: SNS Topic is not encrypted at rest [ack: annotation::TopicNoEncryption]

Policy Validation Report Summary

╔═══════════════════════╤═════════╗
║ Source                │ Status  ║
╟───────────────────────┼─────────╢
║ CfnGuardValidator     │ failure ║
╟───────────────────────┼─────────╢
║ Construct Annotations │ failure ║
╚═══════════════════════╧═════════╝

Validation failed. See the validation report above for details
```

### Describe any new or updated permissions being added

N/A

### Description of how you validated changes

- `tsc --noEmit` passes cleanly
- All 36 validation tests pass (26 existing + 10 new)
- Visual report output verified with a demo app exercising all three annotation paths (`Annotations.of().addWarningV2`, `Annotations.of().addError`, `Validations.of().addWarning`)

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

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

Author: kaizencc

allowed-breaking-changes.txt

@@ -4167,3 +4167,6 @@ removed-mutability:aws-cdk-lib.aws_s3.BucketBase.grants
 
 # Parameter was made optional in override but base class requires it (JSII5008). Method is @deprecated.
 new-argument:aws-cdk-lib.aws_events_targets.LogGroupTargetInput.fromObject
+
+# This interface is new; its not depended on yet
+weakened:aws-cdk-lib.PolicyViolatingResource

packages/aws-cdk-lib/core/lib/private/stack-metadata.ts

@@ -149,7 +149,7 @@ function addValidationPluginInfo(scope: IConstruct, allConstructInfos: Construct
       done = true;
     }
     if (stage) {
-      allConstructInfos.push(...stage.policyValidationBeta1.map(
+      allConstructInfos.push(...stage._validationPlugins.map(
         plugin => {
           return {
             fqn: pluginFqn(plugin),

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

@@ -2,25 +2,30 @@ 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 { iterateDfsPreorder } from './construct-iteration';
+import { generateFeatureFlagReport } from './feature-flag-report';
+import { lit } from './literal-string';
 import { MetadataResource } from './metadata-resource';
 import { prepareApp } from './prepare-app';
 import { TreeMetadata } from './tree-metadata';
+import * as cxschema from '../../../cloud-assembly-schema';
+import * as cxapi from '../../../cx-api';
 import { _convertCloudAssemblyBuilder } from '../../../cx-api/lib/legacy-moved';
 import { Annotations } from '../annotations';
 import { App } from '../app';
 import { _aspectTreeRevisionReader, AspectApplication, AspectPriority, Aspects } from '../aspect';
 import { AssumptionError, UnscopedValidationError } from '../errors';
+import { FeatureFlags } from '../feature-flags';
 import { FileSystem } from '../fs';
 import { Stack } from '../stack';
 import type { ISynthesisSession } from '../stack-synthesizers/types';
 import type { StageSynthesisOptions } from '../stage';
 import { Stage } from '../stage';
 import type { IPolicyValidationPlugin } from '../validation';
-import { generateFeatureFlagReport } from './feature-flag-report';
-import { lit } from './literal-string';
 import { ConstructTree } from '../validation/private/construct-tree';
 import type { NamedValidationPluginReport } from '../validation/private/report';
 import { PolicyValidationReportFormatter } from '../validation/private/report';
+import type { PolicyViolation, PolicyViolatingResource } from '../validation/report';
 
 const POLICY_VALIDATION_FILE_PATH = 'policy-validation-report.json';
 const VALIDATION_REPORT_PRETTY_CONTEXT = '@aws-cdk/core:validationReportPrettyPrint';
@@ -97,6 +102,108 @@ function getAssemblies(root: App, rootAssembly: private_cxapi.CloudAssembly): Ma
   return assemblies;
 }
 
+/**
+ * The plugin name used for annotation-based violations in the validation report.
+ */
+const ANNOTATION_PLUGIN_NAME = 'Construct Annotations';
+
+/**
+ * Collect annotation metadata (warnings and errors) from the construct tree
+ * and convert them into a NamedValidationPluginReport that can be merged
+ * into the same report pipeline as plugin violations.
+ *
+ * Unlike `visit()`, this walks the entire construct tree including across
+ * Stage boundaries. This is intentional: the validation report is a single
+ * global output (not per-stage), and a plugin registered at the App level
+ * sees templates from all stages. Annotations should have the same visibility.
+ */
+function collectAnnotationReport(root: IConstruct, outdir: string): NamedValidationPluginReport | undefined {
+  // Group violations by rule so that multiple constructs triggering the same
+  // rule appear as one violation with multiple violatingResources, matching
+  // how plugins report violations. The key includes description so that
+  // generic aws-cdk:error/aws-cdk:warning annotations with different messages
+  // are kept separate.
+  const violationMap = new Map<string, PolicyViolation & { violatingResources: PolicyViolatingResource[] }>();
+
+  for (const construct of iterateDfsPreorder(root)) {
+    for (const entry of construct.node.metadata) {
+      if (entry.type !== cxschema.ArtifactMetadataEntryType.WARN && entry.type !== cxschema.ArtifactMetadataEntryType.ERROR) {
+        continue;
+      }
+
+      const message = entry.data as string;
+      const severity = entry.type === cxschema.ArtifactMetadataEntryType.ERROR ? 'error' : 'warning';
+      const ruleName = extractRuleName(message, severity);
+
+      // Resolve template path if the construct is inside a Stack
+      let templatePath: string | undefined;
+      try {
+        templatePath = path.join(outdir, Stack.of(construct).templateFile);
+      } catch {
+        // Construct is not inside a Stack (e.g. attached to App or Stage)
+      }
+
+      const violatingResource: PolicyViolatingResource = {
+        constructPath: construct.node.path,
+        templatePath,
+        locations: [],
+      };
+
+      const key = `${ruleName}|${severity}|${message}`;
+      const existing = violationMap.get(key);
+      if (existing) {
+        existing.violatingResources.push(violatingResource);
+      } else {
+        violationMap.set(key, {
+          ruleName,
+          description: message,
+          severity,
+          violatingResources: [violatingResource],
+        });
+      }
+    }
+  }
+
+  const violations = Array.from(violationMap.values());
+  if (violations.length === 0) {
+    return undefined;
+  }
+
+  const hasErrors = violations.some(v => v.severity === 'error');
+  return {
+    pluginName: ANNOTATION_PLUGIN_NAME,
+    success: !hasErrors,
+    violations,
+  };
+}
+
+/**
+ * Extract a rule name from an annotation message.
+ *
+ * Annotations added via `addWarningV2` or `addInfoV2` include an `[ack: <id>]`
+ * tag in the message. When present, the id is used as the rule name — this is
+ * the deterministic, preferred path.
+ *
+ * Annotations added via the older `addWarning`, `addError`, or `addInfo` APIs
+ * do not include an ack tag. In that case, a generic identifier based on the
+ * severity is used (e.g. `aws-cdk:warning`, `aws-cdk:error`). These annotations
+ * cannot be acknowledged, so uniqueness of the rule name is not required. The
+ * full message is available in the violation's `description` field.
+ *
+ * COUPLING NOTE: The `[ack: <id>]` format is produced by the `ackTag()` helper
+ * in `annotations.ts`. There is no structured metadata field for the ack id —
+ * it is embedded in the message string. If the tag format changes, this regex
+ * must be updated to match. See the test 'extractRuleName regex matches
+ * addWarningV2 ack tag format' which verifies this coupling.
+ */
+function extractRuleName(message: string, severity: string): string {
+  const ackMatch = message.match(/\[ack: ([^\]]+)\]/);
+  if (ackMatch) {
+    return ackMatch[1];
+  }
+  return `aws-cdk:${severity}`;
+}
+
 /**
  * Invoke validation plugins for all stages in an App.
  */
@@ -107,7 +214,7 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
   const templatePathsByPlugin: Map<IPolicyValidationPlugin, string[]> = new Map();
   visitAssemblies(root, 'post', construct => {
     if (Stage.isStage(construct)) {
-      for (const plugin of construct.policyValidationBeta1) {
+      for (const plugin of construct._validationPlugins) {
         if (!templatePathsByPlugin.has(plugin)) {
           templatePathsByPlugin.set(plugin, []);
         }
@@ -148,6 +255,16 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
     }
   }
 
+  // Collect annotation-based violations and merge into the report pipeline
+  // when the feature flag is enabled. When disabled, annotations are only
+  // displayed through the CLI's standard metadata output.
+  if (FeatureFlags.of(root).isEnabled(cxapi.ANNOTATIONS_IN_VALIDATION_REPORT)) {
+    const annotationReport = collectAnnotationReport(root, assembly.directory);
+    if (annotationReport) {
+      reports.push(annotationReport);
+    }
+  }
+
   if (reports.length > 0) {
     const tree = new ConstructTree(root);
     const formatter = new PolicyValidationReportFormatter(tree);

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

@@ -7,6 +7,7 @@ import type { PermissionsBoundary } from './permissions-boundary';
 import { synthesize } from './private/synthesis';
 import { type IPropertyInjector, PropertyInjectors } from './prop-injectors';
 import type { IPolicyValidationPlugin, IPolicyValidationPluginBeta1 } from './validation';
+import { _toBeta1Plugin } from './validation';
 import * as public_cxapi from '../../cx-api';
 import { _convertCloudAssembly, _convertCloudAssemblyBuilder } from '../../cx-api';
 import { lit } from './private/literal-string';
@@ -185,7 +186,7 @@ export class Stage extends Construct {
    * @default - no validation plugins are used
    */
   public get policyValidationBeta1(): IPolicyValidationPluginBeta1[] {
-    return [...this._policyValidation];
+    return this._policyValidation.map(_toBeta1Plugin);
   }
 
   private readonly _policyValidation: IPolicyValidationPlugin[] = [];
@@ -229,6 +230,15 @@ export class Stage extends Construct {
     this._policyValidation.push(...plugins);
   }
 
+  /**
+   * Returns the raw validation plugins without Beta1 wrapping.
+   *
+   * @internal
+   */
+  public get _validationPlugins(): IPolicyValidationPlugin[] {
+    return [...this._policyValidation];
+  }
+
   /**
    * The cloud assembly output directory.
    */

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

@@ -120,11 +120,11 @@ export class PolicyValidationReportFormatter {
     json.pluginReports.forEach(plugin => {
       output.push('');
       output.push(table([
-        [`Plugin: ${plugin.summary.pluginName}`],
+        [`Source: ${plugin.summary.pluginName}`],
         [`Version: ${plugin.version ?? 'N/A'}`],
         [`Status: ${plugin.summary.status}`],
       ], {
-        header: { content: 'Plugin Report' },
+        header: { content: 'Validation Report' },
         singleLine: true,
         columns: [{
           paddingLeft: 3,
@@ -155,9 +155,9 @@ export class PolicyValidationReportFormatter {
         for (const construct of constructs) {
           output.push('');
           output.push(`    - Construct Path: ${construct.constructPath ?? 'N/A'}`);
-          output.push(`    - Template Path: ${construct.templatePath}`);
+          output.push(`    - Template Path: ${construct.templatePath ?? 'N/A'}`);
           output.push(`    - Creation Stack:\n\t${this.reportTrace.formatPrettyPrinted(construct.constructPath)}`);
-          output.push(`    - Resource ID: ${construct.resourceLogicalId}`);
+          output.push(`    - Resource ID: ${construct.resourceLogicalId ?? 'N/A'}`);
           if (construct.locations) {
             output.push('    - Template Locations:');
             for (const location of construct.locations) {
@@ -180,7 +180,7 @@ export class PolicyValidationReportFormatter {
     output.push('Policy Validation Report Summary');
     output.push('');
     output.push(table([
-      ['Plugin', 'Status'],
+      ['Source', 'Status'],
       ...reps.map(rep => [rep.pluginName, rep.success ? 'success' : 'failure']),
     ], { }));
 
@@ -191,7 +191,12 @@ export class PolicyValidationReportFormatter {
     return {
       title: 'Validation Report',
       pluginReports: reps
-        .filter(rep => !rep.success)
+        // Include reports that failed OR have violations to render. This is
+        // broader than the original `!rep.success` filter: a source that
+        // returns success=true with violations (e.g. annotation warnings)
+        // will now appear in the report. This is intentional — violations
+        // should always be visible regardless of the overall success status.
+        .filter(rep => !rep.success || rep.violations.length > 0)
         .map(rep => ({
           version: rep.pluginVersion,
           summary: {
@@ -207,16 +212,22 @@ export class PolicyValidationReportFormatter {
             severity: violation.severity,
             violatingResources: violation.violatingResources,
             violatingConstructs: violation.violatingResources.map(resource => {
-              const constructPath = this.tree.getConstructByLogicalId(
-                path.basename(resource.templatePath),
-                resource.resourceLogicalId,
-              )?.node.path;
+              // Use constructPath from the input if provided (e.g. annotations),
+              // otherwise derive it from the logical ID via the construct tree.
+              const constructPath = resource.constructPath ?? (
+                resource.templatePath && resource.resourceLogicalId
+                  ? this.tree.getConstructByLogicalId(
+                    path.basename(resource.templatePath),
+                    resource.resourceLogicalId,
+                  )?.node.path
+                  : undefined
+              );
               return {
                 constructStack: constructPath ? this.reportTrace.formatJson(constructPath) : undefined,
                 constructPath: constructPath,
                 locations: resource.locations,
-                resourceLogicalId: resource.resourceLogicalId,
-                templatePath: resource.templatePath,
+                resourceLogicalId: resource.resourceLogicalId ?? 'N/A',
+                templatePath: resource.templatePath ?? 'N/A',
               };
             }),
           })),

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

@@ -49,8 +49,26 @@ export interface PolicyViolation {
 export interface PolicyViolatingResource {
   /**
    * The logical ID of the resource in the CloudFormation template.
+   *
+   * Required for plugin-sourced violations that operate on CloudFormation
+   * templates. Mutually exclusive with `constructPath`.
+   *
+   * @default - no resource logical ID
    */
-  readonly resourceLogicalId: string;
+  readonly resourceLogicalId?: string;
+
+  /**
+   * The construct path of the violating construct.
+   *
+   * Use this for violations that originate from constructs rather than
+   * CloudFormation resources (e.g. annotations added via `Annotations.of()`
+   * or `Validations.of()`). When provided, the report will use this path
+   * directly instead of deriving it from the resource logical ID.
+   * Mutually exclusive with `resourceLogicalId`.
+   *
+   * @default - construct path is derived from the resource logical ID
+   */
+  readonly constructPath?: string;
 
   /**
    * The locations in the CloudFormation template that pose the violations.
@@ -59,8 +77,10 @@ export interface PolicyViolatingResource {
 
   /**
    * The path to the CloudFormation template that contains this resource
+   *
+   * @default - no template path
    */
-  readonly templatePath: string;
+  readonly templatePath?: string;
 }
 
 /**

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

@@ -1,4 +1,4 @@
-import type { PolicyValidationPluginReport, PolicyValidationPluginReportBeta1 } from './report';
+import type { PolicyValidationPluginReport, PolicyValidationPluginReportBeta1, PolicyViolatingResourceBeta1, PolicyViolationBeta1 } from './report';
 
 /**
  * Represents a validation plugin that will be executed during synthesis
@@ -121,3 +121,42 @@ export interface IPolicyValidationContextBeta1 {
    */
   readonly templatePaths: string[];
 }
+
+/**
+ * Convert an `IPolicyValidationPlugin` to an `IPolicyValidationPluginBeta1`.
+ *
+ * The stable `PolicyViolatingResource` interface has optional `resourceLogicalId`
+ * and `templatePath` fields to support annotation-sourced violations. The Beta1
+ * interface keeps those fields required. This adapter bridges the gap by
+ * providing fallback values for the optional fields.
+ *
+ * @internal
+ */
+export function _toBeta1Plugin(plugin: IPolicyValidationPlugin): IPolicyValidationPluginBeta1 {
+  return {
+    name: plugin.name,
+    version: plugin.version,
+    ruleIds: plugin.ruleIds,
+    validate(context: IPolicyValidationContextBeta1): PolicyValidationPluginReportBeta1 {
+      const report = plugin.validate(context);
+      return {
+        success: report.success,
+        pluginVersion: report.pluginVersion,
+        metadata: report.metadata,
+        violations: report.violations.map((v): PolicyViolationBeta1 => ({
+          ruleName: v.ruleName,
+          description: v.description,
+          fix: v.fix,
+          severity: v.severity,
+          ruleMetadata: v.ruleMetadata,
+          violatingResources: v.violatingResources.map((r): PolicyViolatingResourceBeta1 => ({
+            resourceLogicalId: r.resourceLogicalId ?? '',
+            templatePath: r.templatePath ?? '',
+            locations: r.locations,
+          })),
+        })),
+      };
+    },
+  };
+}
+