feat(core): Validations class is the new way to add validation plugins to CDK Apps (#37611)

### Reason for this change

Part of aws/aws-cdk-rfcs#899. Depends on #37613. `Validations` is the new one-stop shop for post-synthesis validation. This PR starts with the `addPlugins()` API that mirrors the functionality of supplying `policyValidationBeta1` to your CDK App today. 


### Description of how you validated changes

Existing tests succeed and new tests verify that `Validations.addPlugin()` does the same thing.

### 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-testing/framework-integ/test/core/test/metadata-resource.test.ts

@@ -1,7 +1,7 @@
 import { constructAnalyticsFromScope } from 'aws-cdk-lib/core/lib/helpers-internal';
 import { localCdkVersion } from './util';
-import type { IPolicyValidationPluginBeta1, PolicyViolationBeta1, PolicyValidationPluginReportBeta1, IPolicyValidationContextBeta1 } from 'aws-cdk-lib/core';
-import { App, NestedStack, Stack, Stage } from 'aws-cdk-lib/core';
+import type { IPolicyValidationPlugin, PolicyViolation, PolicyValidationPluginReport, IPolicyValidationContext } from 'aws-cdk-lib/core';
+import { App, NestedStack, Stack, Stage, Validations } from 'aws-cdk-lib/core';
 import { Construct } from 'constructs';
 
 const JSII_RUNTIME_SYMBOL = Symbol.for('jsii.rtti');
@@ -105,9 +105,8 @@ describe('constructAnalyticsFromScope', () => {
   });
 
   test('return info from validator plugins', () => {
-    const validatedApp = new App({
-      policyValidationBeta1: [new FakePlugin('fake', [], '1.0.0', ['RULE_1', 'RULE_2'])],
-    });
+    const validatedApp = new App();
+    Validations.of(validatedApp).addPlugins(new FakePlugin('fake', [], '1.0.0', ['RULE_1', 'RULE_2']));
     const validatedStack = new Stack(validatedApp, 'ValidatedStack');
     const constructInfos = constructAnalyticsFromScope(validatedStack);
 
@@ -128,15 +127,15 @@ class TestConstruct extends Construct {
   private static readonly [JSII_RUNTIME_SYMBOL] = { fqn: '@aws-cdk/test.TestConstruct', version: localCdkVersion() };
 }
 
-class FakePlugin implements IPolicyValidationPluginBeta1 {
+class FakePlugin implements IPolicyValidationPlugin {
   constructor(
     public readonly name: string,
-    private readonly violations: PolicyViolationBeta1[],
+    private readonly violations: PolicyViolation[],
     public readonly version?: string,
     public readonly ruleIds?: string []) {
   }
 
-  validate(_context: IPolicyValidationContextBeta1): PolicyValidationPluginReportBeta1 {
+  validate(_context: IPolicyValidationContext): PolicyValidationPluginReport {
     return {
       success: this.violations.length === 0,
       violations: this.violations,

packages/aws-cdk-lib/README.md

@@ -1614,31 +1614,20 @@ generated CloudFormation templates against your policies immediately after
 synthesis. If there are any violations, the synthesis will fail and a report
 will be printed to the console or to a file (see below).
 
-> [!NOTE]
-> This feature is considered experimental, and both the plugin API and the
-> format of the validation report are subject to change in the future.
-
 ### For application developers
 
 To use one or more validation plugins in your application, use the
-`policyValidationBeta1` property of `Stage`:
+`Validations.of()` API:
 
 ```ts fixture=validation-plugin
 // globally for the entire app (an app is a stage)
-const app = new App({
-  policyValidationBeta1: [
-    // These hypothetical classes implement IPolicyValidationPluginBeta1:
-    new ThirdPartyPluginX(),
-    new ThirdPartyPluginY(),
-  ],
-});
+const app = new App();
+Validations.of(app).addPlugins(new ThirdPartyPluginX());
+Validations.of(app).addPlugins(new ThirdPartyPluginY());
 
 // only apply to a particular stage
-const prodStage = new Stage(app, 'ProdStage', {
-  policyValidationBeta1: [
-    new ThirdPartyPluginX(),
-  ],
-});
+const prodStage = new Stage(app, 'ProdStage');
+Validations.of(prodStage).addPlugins(new ThirdPartyPluginX());
 ```
 
 Immediately after synthesis, all plugins registered this way will be invoked to
@@ -1656,7 +1645,7 @@ By default, the report will be printed in a human-readable format. If you want a
 report in JSON format, enable it using the `@aws-cdk/core:validationReportJson`
 context passing it directly to the application:
 
-```ts
+```ts fixture=validation-plugin
 const app = new App({
   context: { '@aws-cdk/core:validationReportJson': true },
 });
@@ -1669,7 +1658,7 @@ Alternatively, you can set this context key-value pair using the `cdk.json` or
 It is also possible to enable both JSON and human-readable formats by setting
 `@aws-cdk/core:validationReportPrettyPrint` context key explicitly:
 
-```ts
+```ts fixture=validation-plugin
 const app = new App({
   context: {
     '@aws-cdk/core:validationReportJson': true,
@@ -1686,21 +1675,21 @@ the standard output.
 ### For plugin authors
 
 The communication protocol between the CDK core module and your policy tool is
-defined by the `IPolicyValidationPluginBeta1` interface. To create a new plugin you must
+defined by the `IPolicyValidationPlugin` interface. To create a new plugin you must
 write a class that implements this interface. There are two things you need to
 implement: the plugin name (by overriding the `name` property), and the
 `validate()` method.
 
-The framework will call `validate()`, passing an `IPolicyValidationContextBeta1` object.
+The framework will call `validate()`, passing an `IPolicyValidationContext` object.
 The location of the templates to be validated is given by `templatePaths`. The
-plugin should return an instance of `PolicyValidationPluginReportBeta1`. This object
-represents the report that the user wil receive at the end of the synthesis.
+plugin should return an instance of `PolicyValidationPluginReport`. This object
+represents the report that the user will receive at the end of the synthesis.
 
 ```ts fixture=validation-plugin
-class MyPlugin implements IPolicyValidationPluginBeta1 {
+class MyPlugin implements IPolicyValidationPlugin {
   public readonly name = 'MyPlugin';
 
-  public validate(context: IPolicyValidationContextBeta1): PolicyValidationPluginReportBeta1 {
+  public validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
     // First read the templates using context.templatePaths...
 
     // ...then perform the validation, and then compose and return the report.
@@ -1723,7 +1712,7 @@ class MyPlugin implements IPolicyValidationPluginBeta1 {
 ```
 
 In addition to the name, plugins may optionally report their version (`version`
-property ) and a list of IDs of the rules they are going to evaluate (`ruleIds`
+property) and a list of IDs of the rules they are going to evaluate (`ruleIds`
 property).
 
 Note that plugins are not allowed to modify anything in the cloud assembly. Any

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

@@ -127,6 +127,7 @@ export interface AppProps {
    * Validation plugins to run after synthesis
    *
    * @default - no validation plugins
+   * @deprecated Use `Validations.of(app).addPlugins()` instead.
    */
   readonly policyValidationBeta1?: IPolicyValidationPluginBeta1[];
 
@@ -185,14 +186,17 @@ export class App extends Stage {
   constructor(props: AppProps = {}) {
     super(undefined as any, '', {
       outdir: props.outdir ?? process.env[cxapi.OUTDIR_ENV],
-      policyValidationBeta1: props.policyValidationBeta1,
     });
 
     if (props.propertyInjectors) {
       const injectors = PropertyInjectors.of(this);
       injectors.add(...props.propertyInjectors);
     }
 
+    if (props.policyValidationBeta1) {
+      this._addValidationPlugins(...props.policyValidationBeta1);
+    }
+
     Object.defineProperty(this, APP_SYMBOL, { value: true });
 
     this.loadContext(props.context, props.postCliContext);

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

@@ -96,6 +96,7 @@ export interface StageProps {
    * synthesis will be interrupted and the report displayed to the user.
    *
    * @default - no validation plugins are used
+   * @deprecated Use `Validations.of(stage).addPlugins()` instead.
    */
   readonly policyValidationBeta1?: IPolicyValidationPluginBeta1[];
 
@@ -219,6 +220,15 @@ export class Stage extends Construct {
     }
   }
 
+  /**
+   * Register a validation plugin on this stage.
+   *
+   * @internal
+   */
+  public _addValidationPlugins(...plugins: IPolicyValidationPluginBeta1[]): void {
+    this._policyValidationBeta1.push(...plugins);
+  }
+
   /**
    * The cloud assembly output directory.
    */

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

@@ -1,2 +1,3 @@
 export * from './validation';
+export * from './validations';
 export * from './report';

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

@@ -5,10 +5,10 @@ import type { PolicyValidationPluginReport, PolicyValidationPluginReportBeta1 }
  *
  * @example
  * /// fixture=validation-plugin
- * class MyPlugin implements IPolicyValidationPluginBeta1 {
+ * class MyPlugin implements IPolicyValidationPlugin {
  *   public readonly name = 'MyPlugin';
  *
- *   public validate(context: IPolicyValidationContextBeta1): PolicyValidationPluginReportBeta1 {
+ *   public validate(context: IPolicyValidationContext): PolicyValidationPluginReport {
  *     // First read the templates using context.templatePaths...
  *
  *     // ...then perform the validation, and then compose and return the report.

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

@@ -0,0 +1,44 @@
+import type { IConstruct } from 'constructs';
+import type { IPolicyValidationPlugin } from './validation';
+import { UnscopedValidationError } from '../errors';
+import { lit } from '../private/literal-string';
+import { Stage } from '../stage';
+
+/**
+ * Manages validations for CDK constructs.
+ *
+ * @example
+ * /// fixture=validation-plugin
+ * declare const myApp: App;
+ * declare const plugin: IPolicyValidationPlugin;
+ * Validations.of(myApp).addPlugins(plugin);
+ */
+export class Validations {
+  /**
+   * Returns the Validations for the given construct scope.
+   *
+   * @param scope any construct
+   */
+  public static of(scope: IConstruct): Validations {
+    return new Validations(scope);
+  }
+
+  private constructor(private readonly scope: IConstruct) {}
+
+  /**
+   * Register one or more validation plugins that will be executed during synthesis.
+   *
+   * Plugins can only be registered within a Stage or App scope.
+   * If any plugin reports a violation, synthesis will be interrupted and the
+   * report displayed to the user.
+   *
+   * @param plugins the validation plugins to add
+   */
+  public addPlugins(...plugins: IPolicyValidationPlugin[]): void {
+    const stage = Stage.isStage(this.scope) ? this.scope : Stage.of(this.scope);
+    if (!stage) {
+      throw new UnscopedValidationError(lit`NoStageForValidationPlugins`, 'Cannot add validation plugins on a construct without an enclosing Stage');
+    }
+    stage._addValidationPlugins(...plugins);
+  }
+}

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

@@ -814,10 +814,75 @@ Policy Validation Report Summary
   });
 
   test('a plugin implementing Beta1 is assignable to IPolicyValidationPlugin', () => {
+    // GIVEN
     const beta1Plugin: core.IPolicyValidationPluginBeta1 = new FakePlugin('beta1-plugin', []);
+
+    // WHEN
     const plugin: core.IPolicyValidationPlugin = beta1Plugin;
+
+    // THEN
     expect(plugin.name).toEqual('beta1-plugin');
   });
+
+  describe('Validations.of()', () => {
+    test('addPlugins adds plugin to enclosing stage', () => {
+      // GIVEN
+      const app = new core.App();
+      const plugin = new FakePlugin('test-plugin', []);
+
+      // WHEN
+      core.Validations.of(app).addPlugins(plugin);
+
+      // THEN
+      expect(app.policyValidationBeta1).toContain(plugin);
+    });
+
+    test('addPlugins from nested construct resolves to enclosing stage', () => {
+      // GIVEN
+      const app = new core.App();
+      const stack = new core.Stack(app, 'MyStack');
+      const plugin = new FakePlugin('test-plugin', []);
+
+      // WHEN
+      core.Validations.of(stack).addPlugins(plugin);
+
+      // THEN - plugin is registered on the app (enclosing stage), not the stack
+      expect(app.policyValidationBeta1).toContain(plugin);
+    });
+
+    test('throws when addPlugins called without enclosing stage', () => {
+      // GIVEN
+      const construct = new Construct(undefined as any, '');
+
+      // THEN
+      expect(() => core.Validations.of(construct).addPlugins(new FakePlugin('test', []))).toThrow(/without an enclosing Stage/);
+    });
+
+    test('plugin added via addPlugins runs during synth', () => {
+      // GIVEN
+      const app = new core.App();
+      const stack = new core.Stack(app);
+      new core.CfnResource(stack, 'Fake', {
+        type: 'Test::Resource::Fake',
+        properties: { result: 'success' },
+      });
+
+      // WHEN
+      core.Validations.of(app).addPlugins(new FakePlugin('added-plugin', [{
+        description: 'test recommendation',
+        ruleName: 'test-rule',
+        violatingResources: [{
+          locations: ['test-location'],
+          resourceLogicalId: 'Fake',
+          templatePath: '/path/to/Default.template.json',
+        }],
+      }]));
+      app.synth();
+
+      // THEN - exitCode 1 means the plugin ran and reported violations
+      expect(process.exitCode).toEqual(1);
+    });
+  });
 });
 
 class FakePlugin implements core.IPolicyValidationPluginBeta1 {

packages/aws-cdk-lib/rosetta/validation-plugin.ts-fixture

@@ -1,12 +1,12 @@
 import { Construct } from 'constructs';
-import { App, IPolicyValidationPluginBeta1, Stage, IPolicyValidationContextBeta1, PolicyValidationPluginReportBeta1 } from 'aws-cdk-lib';
+import { App, IPolicyValidationPlugin, Stage, IPolicyValidationContext, PolicyValidationPluginReport, Validations } from 'aws-cdk-lib';
 
-declare class ThirdPartyPluginX implements IPolicyValidationPluginBeta1 {
+declare class ThirdPartyPluginX implements IPolicyValidationPlugin {
   public readonly name: string;
   public validate(x: any): any;
 }
 
-declare class ThirdPartyPluginY implements IPolicyValidationPluginBeta1 {
+declare class ThirdPartyPluginY implements IPolicyValidationPlugin {
   public readonly name: string;
   public validate(x: any): any;
 }
@@ -18,4 +18,3 @@ class fixture$construct extends Construct {
     /// here
   }
 }
-