Skip to content

feat(cli): write cdk diff as machine-readable JSON to a file with --json-file - #1899

Draft
9pace wants to merge 1 commit into
aws:mainfrom
9pace:feat/diff-json-output
Draft

feat(cli): write cdk diff as machine-readable JSON to a file with --json-file#1899
9pace wants to merge 1 commit into
aws:mainfrom
9pace:feat/diff-json-output

Conversation

@9pace

@9pace 9pace commented Aug 25, 2026

Copy link
Copy Markdown
Contributor

Adds a --json-file <path> option to cdk diff that writes the computed diff as a machine-readable JSON document to the given path, while leaving the console output unchanged. This lets tooling consume diffs — e.g. review automation attaching evidence of what a change does to the synthesized templates — without scraping the formatted console output. Related to aws/aws-cdk#679.

  • The file maps each selected stack (including nested stacks) to its structural diff: resource changes with property-level old/new values and change impact (WILL_REPLACE, ...), plus iamChanges (statement/managed-policy additions and removals) and securityGroupChanges, and a permissionsBroadened flag
  • Composes with all existing diff options; exit code behavior (--fail) is unchanged

Design decisions:

  • The serialization (templateDiffToJson()) lives in @aws-cdk/cloudformation-diff, which owns the TemplateDiff model and already had machine-readable serializers for the IAM scrutiny data and security group changes — this composes them and adds the structural part, reading the public getters into plain JSON (a TemplateDiff is a graph of class instances whose derived values are getters, so it cannot be stringified directly)
  • The CLI writes the file from CdkToolkit.diff(), where DiffFormatter already caches the structured TemplateDiff per stack; serialization happens after formatting so the JSON reflects the same --strict filtering as the console output
  • --json-file requires its argument: diff takes a variadic STACKS positional, so an optional-value flag would silently swallow a stack name as a filename (same reason deploy --outputs-file requires one)
  • No JSON-to-stdout mode: that would require suppressing/rerouting the human output (which goes to stdout in CI mode) and interacts with --security-only and --quiet; a file write keeps diff's behavior identical and is what automation needs. Can be added later without breaking this contract
  • IAM statements containing unresolvable intrinsics are emitted as { "type": "unparseable", "repr": "..." } rather than dropped (documented in the README)

Checklist

  • This change contains a major version upgrade for a dependency and I confirm all breaking changes are addressed

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

@9pace
9pace deployed to automation August 25, 2026 16:55 — with GitHub Actions Active
@github-actions github-actions Bot added the p2 label Aug 25, 2026
@aws-cdk-automation
aws-cdk-automation requested a review from a team August 25, 2026 16:56
…son-file

Adds a '--json-file <path>' option to 'cdk diff' that writes the computed
diff as a JSON document to the given path, while leaving the console
output unchanged.

The file maps each selected stack to its structural template diff
(per-property old/new values with change impact), plus the IAM policy
changes and security group rule changes already computed by
@aws-cdk/cloudformation-diff, serialized by a new templateDiffToJson()
function in that package.
@9pace
9pace force-pushed the feat/diff-json-output branch from 2b4762d to d0c221d Compare August 25, 2026 18:28
@9pace 9pace changed the title feat(cli): machine-readable JSON output for cdk diff feat(cli): write cdk diff as machine-readable JSON to a file with --json-file Aug 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant