feat(cloud-assembly-schema): add preamble feature, document contract

packages/@aws-cdk/cloud-assembly-schema/lib/cloud-assembly/validation-report-schema.ts

@@ -74,6 +74,13 @@ export interface PluginReportJson {
    */
   readonly metadata?: { readonly [key: string]: string };
 
+  /**
+   * Any preamble text that the plugin wants to include in the report that is not a violation itself.
+   *
+   * @default - no preamble
+   */
+  readonly preamble?: string;
+
   /**
    * Violations found by this plugin.
    */
@@ -261,6 +268,8 @@ export interface SuppressedViolationJson extends PolicyViolationJson {
 export interface CloudFormationResourceJson {
   /**
    * The path to the CloudFormation template containing this resource.
+   *
+   * This path is relative to the Cloud Assembly root directory.
    */
   readonly templatePath: string;
 

packages/@aws-cdk/toolkit-lib/lib/api/validate/validate-formatting.ts

@@ -30,6 +30,7 @@ export function formatValidationReports(fileRoot: string, reports: PluginReportJ
 
   return [
     ...pluginFailures.map(formatPluginFailure),
+    ...successfullyExecutedPlugins.flatMap((r) => r.preamble ? [`${chalk.underline(sanitize(r.pluginName))}: ${sanitize(r.preamble)}`] : []),
     ...violations.map((v) => formatViolationBlock(fileRoot, v)),
   ];
 }

packages/@aws-cdk/toolkit-lib/test/api/validate/validate-formatting.test.ts

@@ -220,6 +220,25 @@ describe('formatValidateResult', () => {
     expect(output).toContain('Fake passed message');
     expect(output).toContain('Evil');
   });
+
+  test('preambles are printed', () => {
+    const result = makeResult([{
+      pluginName: 'Some Plugin',
+      conclusion: 'success',
+      preamble: 'OMG there are warnings',
+      violations: [{
+        ruleName: 'RULE',
+        description: 'Make sure you fix this',
+        severity: 'warning',
+        violatingConstructs: [{
+          constructPath: 'Stack/Resource',
+        }],
+      }],
+    }]);
+
+    const output = formatValidateResult(result);
+    expect(output).toMatchSnapshot();
+  });
 });
 
 function formatValidateResult(result: ValidateResult) {