feat(core): new validation report schema (#37970)

### Reason for this change

The CDK CLI `validate` command (aws/aws-cdk-cli#1515) introduces a new validation report schema in `cloud-assembly-schema`. The framework needs to produce output matching this new schema so the CLI can consume it via `Manifest.loadValidationReport`.

The old report format (`policy-validation-report.json`) must remain available for backwards compatibility with older CLI versions.

### Description of changes

- Adds a new `formatJson` method to `PolicyValidationReportFormatter` that produces the new schema-compliant report format:
  - Top-level `version` field (cloud assembly schema version)
  - Flat `pluginName`/`conclusion` (replaces nested `summary`)
  - Typed `severity` enum (`fatal|error|warning|info|custom`)
  - `violatingConstructs` with `constructFqn`, `libraryVersion`, `cloudFormationResource`, `stackTraces`
  - `suggestedFix` (replaces `fix`)

- New report is written to `validation-report.json` by default
- Old report (`policy-validation-report.json`) is only written when `@aws-cdk/core:validationReportJson` context key is set to `true`
- Renames old format interfaces to `Legacy*`, new ones get the clean names
- Adds constants to `cx-api`: `VALIDATION_REPORT_FILE`, `LEGACY_VALIDATION_REPORT_FILE`, `VALIDATION_REPORT_JSON_CONTEXT`

### Describe any new or updated permissions being added

N/A

### Description of how you validated changes

- All 47 validation unit tests pass
- Added tests for legacy report opt-in and default behavior
- Verified report output passes JSON schema validation matching `validation-report.schema.json` from the CLI PR

### 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

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

@@ -27,7 +27,7 @@ import { ConstructTree } from '../validation/private/construct-tree';
 import type { NamedValidationPluginReport } from '../validation/private/report';
 import { PolicyValidationReportFormatter } from '../validation/private/report';
 
-const POLICY_VALIDATION_FILE_PATH = 'policy-validation-report.json';
+const LEGACY_POLICY_VALIDATION_FILE_PATH = 'policy-validation-report.json';
 
 /**
  * Options for `synthesize()`
@@ -198,9 +198,18 @@ function invokeValidationPlugins(root: IConstruct, outdir: string, assembly: pri
     const tree = new ConstructTree(root);
     const formatter = new PolicyValidationReportFormatter(tree);
     const failOnErrors = root.node.tryGetContext(cxapi.FAIL_SYNTH_ON_VALIDATION_ERRORS_CONTEXT) ?? true;
-    const reportFile = path.join(assembly.directory, POLICY_VALIDATION_FILE_PATH);
-    const jsonOutput = formatter.formatJson(reports);
+    const writeLegacyReport = root.node.tryGetContext(cxapi.VALIDATION_REPORT_JSON_CONTEXT) ?? false;
+
+    const reportFile = path.join(assembly.directory, cxapi.VALIDATION_REPORT_FILE);
+    const jsonOutput = formatter.formatJson(reports, assembly.version);
     fs.writeFileSync(reportFile, JSON.stringify(jsonOutput, undefined, 2));
+
+    if (writeLegacyReport) {
+      const legacyReportFile = path.join(assembly.directory, LEGACY_POLICY_VALIDATION_FILE_PATH);
+      const legacyOutput = formatter.formatLegacyJson(reports);
+      fs.writeFileSync(legacyReportFile, JSON.stringify(legacyOutput, undefined, 2));
+    }
+
     if (failOnErrors) {
       const output = formatter.formatPrettyPrinted(reports);
       // eslint-disable-next-line no-console

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

@@ -37,7 +37,7 @@ export interface ValidationViolatingConstruct extends report.PolicyViolatingReso
 /**
  * JSON representation of the report.
  */
-export interface PolicyValidationReportJson {
+export interface LegacyPolicyValidationReportJson {
   /**
    * Report title.
    */
@@ -47,13 +47,13 @@ export interface PolicyValidationReportJson {
    * Reports for all of the validation plugins registered
    * in the app
    */
-  readonly pluginReports: PluginReportJson[];
+  readonly pluginReports: LegacyPluginReportJson[];
 }
 
 /**
  * A report from a single plugin
  */
-export interface PluginReportJson {
+export interface LegacyPluginReportJson {
   /**
    * List of violations in the report.
    */
@@ -62,7 +62,7 @@ export interface PluginReportJson {
   /**
    * Report summary.
    */
-  readonly summary: PolicyValidationReportSummary;
+  readonly summary: LegacyPolicyValidationReportSummary;
 
   /**
    * Plugin version.
@@ -73,7 +73,7 @@ export interface PluginReportJson {
 /**
  * Summary of the report.
  */
-export interface PolicyValidationReportSummary {
+export interface LegacyPolicyValidationReportSummary {
   /**
    * The final status of the validation (pass/fail)
    */
@@ -103,6 +103,51 @@ export interface NamedValidationPluginReport extends report.PolicyValidationPlug
   readonly pluginName: string;
 }
 
+/**
+ * JSON representation of the validation report, matching cloud-assembly-schema.
+ */
+export interface PolicyValidationReportJson {
+  readonly version: string;
+  readonly title?: string;
+  readonly pluginReports: PluginReportJson[];
+}
+
+export interface PluginReportJson {
+  readonly pluginName: string;
+  readonly pluginVersion?: string;
+  readonly conclusion: PolicyValidationReportConclusion;
+  readonly metadata?: { readonly [key: string]: string };
+  readonly violations: PolicyViolationJson[];
+}
+
+export type PolicyValidationReportConclusion = 'success' | 'failure';
+
+export interface PolicyViolationJson {
+  readonly ruleName: string;
+  readonly description: string;
+  readonly suggestedFix?: string;
+  readonly severity: PolicyViolationSeverity;
+  readonly customSeverity?: string;
+  readonly ruleMetadata?: { readonly [key: string]: string };
+  readonly violatingConstructs: ViolatingConstructJson[];
+}
+
+export type PolicyViolationSeverity = 'fatal' | 'error' | 'warning' | 'info' | 'custom';
+
+export interface ViolatingConstructJson {
+  readonly constructPath: string;
+  readonly constructFqn?: string;
+  readonly libraryVersion?: string;
+  readonly cloudFormationResource?: CloudFormationResourceJson;
+  readonly stackTraces?: string[];
+}
+
+export interface CloudFormationResourceJson {
+  readonly templatePath: string;
+  readonly logicalId: string;
+  readonly propertyPaths?: string[];
+}
+
 /**
  * The report emitted by the plugin after evaluation.
  */
@@ -113,7 +158,7 @@ export class PolicyValidationReportFormatter {
   }
 
   public formatPrettyPrinted(reps: NamedValidationPluginReport[]): string {
-    const json = this.formatJson(reps);
+    const json = this.formatLegacyJson(reps);
     const output = [json.title];
     output.push('-'.repeat(json.title.length));
 
@@ -187,7 +232,7 @@ export class PolicyValidationReportFormatter {
     return output.join(os.EOL);
   }
 
-  public formatJson(reps: NamedValidationPluginReport[]): PolicyValidationReportJson {
+  public formatLegacyJson(reps: NamedValidationPluginReport[]): LegacyPolicyValidationReportJson {
     return {
       title: 'Validation Report',
       pluginReports: reps
@@ -234,6 +279,92 @@ export class PolicyValidationReportFormatter {
         })),
     };
   }
+
+  public formatJson(reps: NamedValidationPluginReport[], schemaVersion: string): 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;
+              }),
+            };
+          }),
+        })),
+    };
+  }
+
+  private formatStackTraces(constructPath: string): string[] | undefined {
+    const trace = this.reportTrace.formatJson(constructPath);
+    if (!trace) return undefined;
+    const lines: string[] = [];
+    let current: ConstructTrace | undefined = trace;
+    while (current) {
+      if (current.location) {
+        lines.push(current.location);
+      }
+      current = current.child;
+    }
+    return lines.length > 0 ? [lines.join('\n')] : undefined;
+  }
+}
+
+const KNOWN_SEVERITIES = new Set(['fatal', 'error', 'warning', 'info']);
+
+function normalizeSeverity(severity: string | undefined): { severity: PolicyViolationSeverity; customSeverity?: string } {
+  if (!severity) {
+    return { severity: 'error' };
+  }
+  const lower = severity.toLowerCase();
+  if (KNOWN_SEVERITIES.has(lower)) {
+    return { severity: lower as PolicyViolationSeverity };
+  }
+  return { severity: 'custom', customSeverity: severity };
 }
 
 function reset(s: string) {