feat(core): integrate construct annotations into validation report by kaizencc · Pull Request #37712 · aws/aws-cdk

kaizencc · 2026-04-28T00:49:35Z

Reason for this change

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

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

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

…DK Apps

The merge from main duplicated full-body deprecated interfaces (from #37613) alongside the extends-based aliases that this PR uses. Restored report.ts and validation.ts to their correct pre-merge state.

This reverts commit 5d7d4b9.

The merge from main kept both the full-body deprecated Beta1 interfaces (from #37613) and the extends-based aliases from this branch, causing duplicate identifiers. Fixed by keeping the #37613 full-body approach with correct Beta1 names and removing the extends-based aliases.

…ons class

…rface, prefixed IDs, metadata recording

- Remove KNOWN_PREFIXES array; use colon detection in ensurePrefix instead of maintaining a hardcoded list of known prefixes. Any 'prefix:id' format is treated as already-prefixed; only bare IDs get the 'annotation:' prefix added. - Replace findLast (ES2023) with filter + last element for ES2020 compatibility. - Revert unrelated Location string test changes (scope creep).

…A_KEY

aws-cdk-automation · 2026-05-05T02:20:52Z

➡️ PR build request submitted to test-main-pipeline ⬅️

A maintainer must now check the pipeline and add the pr-linter/cli-integ-tested label once the pipeline succeeds.

mergify · 2026-05-05T02:45:31Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

mergify · 2026-05-05T02:45:35Z

mergify · 2026-05-05T03:14:51Z

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

github-actions · 2026-05-05T03:15:13Z

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.

kaizencc and others added 25 commits April 15, 2026 21:58

remove beta1 fro mapi

d1cbd87

udpate deps

01282a5

Merge branch 'main' into conroy/remove-beta1

8f07d02

beta interfaces implement graduated interfaces

783646f

revert enum change

25cb484

Merge branch 'main' into conroy/remove-beta1

e93eefb

feat: Validations class is the new way to add validation plugins to C…

b0e642b

…DK Apps

validations class uses new vlaidation interfaces

290f5bf

pluralize addPlugin, app does not reference deprecated stage prop

53eb6f4

Merge branch 'main' into conroy/validations

ef703ce

fix: resolve bad merge conflict in validation files

5d7d4b9

The merge from main duplicated full-body deprecated interfaces (from #37613) alongside the extends-based aliases that this PR uses. Restored report.ts and validation.ts to their correct pre-merge state.

Revert "fix: resolve bad merge conflict in validation files"

b65bfd3

This reverts commit 5d7d4b9.

fix: update metadata-resource test to use graduated validation APIs

e5be775

feat(core): add addWarning, addError, acknowledge methods to Validati…

7db477f

…ons class

Merge branch 'main' into conroy/validations-addons

667fcae

feat(core): update Validations API to match RFC — Acknowledgment inte…

58ae4e6

…rface, prefixed IDs, metadata recording

revert example change

a1e5af0

chore: remove @stability experimental from ACKNOWLEDGED_RULES_METADAT…

7719984

…A_KEY

Merge branch 'main' into conroy/validations-addons

bb28cfc

use :: as delimiter between prefix and id

df9d265

test fix

a87bd4e

wip: integrate annotation errors/warnings into validation report

3e42d3c

chore(core): migrate off of Beta1 properties internally

acc32df

kaizencc requested a review from a team as a code owner April 28, 2026 00:49

kaizencc temporarily deployed to automation April 28, 2026 00:49 — with GitHub Actions Inactive

github-actions Bot added the p2 label Apr 28, 2026

aws-cdk-automation requested a review from a team April 28, 2026 00:49

kaizencc requested a deployment to test-pipeline May 4, 2026 12:40 — with GitHub Actions Waiting

rix0rrr approved these changes May 4, 2026

View reviewed changes

dont break beta1

62c5c5f

kaizencc temporarily deployed to automation May 4, 2026 17:38 — with GitHub Actions Inactive

kaizencc requested a deployment to test-pipeline May 4, 2026 17:39 — with GitHub Actions Waiting

fix tests

9713a20

kaizencc temporarily deployed to automation May 4, 2026 23:32 — with GitHub Actions Inactive

kaizencc requested a deployment to test-pipeline May 4, 2026 23:33 — with GitHub Actions Waiting

validation tests for non-beta1

e814a8d

kaizencc temporarily deployed to automation May 4, 2026 23:51 — with GitHub Actions Inactive

kaizencc temporarily deployed to test-pipeline May 4, 2026 23:52 — with GitHub Actions Inactive

kaizencc temporarily deployed to automation May 5, 2026 00:13 — with GitHub Actions Inactive

allow breaking change

f58b297

kaizencc temporarily deployed to automation May 5, 2026 02:00 — with GitHub Actions Inactive

kaizencc temporarily deployed to test-pipeline May 5, 2026 02:01 — with GitHub Actions Inactive

kaizencc temporarily deployed to automation May 5, 2026 02:20 — with GitHub Actions Inactive

Merge branch 'main' into conroy/annotations-in-validation-report

8954665

mergify Bot temporarily deployed to automation May 5, 2026 02:45 Inactive

mergify Bot requested a deployment to test-pipeline May 5, 2026 02:46 Waiting

mergify Bot merged commit 438bd0b into main May 5, 2026
16 of 18 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

feat(core): integrate construct annotations into validation report#37712
mergify[bot] merged 40 commits intomainfrom
conroy/annotations-in-validation-report

kaizencc commented Apr 28, 2026 •

edited

Loading

Uh oh!

aws-cdk-automation commented May 5, 2026

Uh oh!

mergify Bot commented May 5, 2026

Uh oh!

mergify Bot commented May 5, 2026 •

edited

Loading

Uh oh!

mergify Bot commented May 5, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

kaizencc commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reason for this change

Description of changes

Sample output

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation commented May 5, 2026

Uh oh!

mergify Bot commented May 5, 2026

Uh oh!

mergify Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Queue Status

Uh oh!

mergify Bot commented May 5, 2026

Uh oh!

Uh oh!

github-actions Bot commented May 5, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kaizencc commented Apr 28, 2026 •

edited

Loading

mergify Bot commented May 5, 2026 •

edited

Loading