Metadata-Version: 2.4
Name: cdk-diff-summary
Version: 1.1.1
Summary: Summarize AWS CDK diff JSON as compact Markdown.
Author: cdk-diff-summary contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/jalcock501/cdk-diff-summary-pypi
Project-URL: Repository, https://github.com/jalcock501/cdk-diff-summary-pypi
Project-URL: Documentation, https://github.com/jalcock501/cdk-diff-summary-pypi#readme
Project-URL: Issues, https://github.com/jalcock501/cdk-diff-summary-pypi/issues
Keywords: aws,cdk,cloudformation,github-actions,diff
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<10.0,>=8.3; extra == "dev"
Requires-Dist: ruff<0.16,>=0.8; extra == "dev"
Requires-Dist: twine<7.0,>=5.0; extra == "dev"
Dynamic: license-file

# cdk-diff-summary

`cdk-diff-summary` reads AWS CDK diff JSON and renders a compact Markdown summary.

It is useful locally, in CI systems, and in GitHub Actions workflows where raw CDK or CloudFormation diffs are too noisy. It groups adds, modifies, removes, replacements, security group rule changes, and other changes while reducing common churn from IAM policy documents and CDK asset hashes.

The tool deliberately shows changed field paths only, not before/after values, to avoid exposing sensitive infrastructure values in summaries.

## Install

```bash
pipx install cdk-diff-summary
```

or:

```bash
python -m pip install cdk-diff-summary
```

## Usage

Generate CDK diff JSON:

```bash
npx cdk diff --json > cdk-diff.json
```

Render Markdown to stdout:

```bash
cdk-diff-summary cdk-diff.json
```

Append Markdown to a file:

```bash
cdk-diff-summary cdk-diff.json --output cdk-diff-summary.md
```

Use a custom title and field limit:

```bash
cdk-diff-summary cdk-diff.json \
  --title "Production CDK diff" \
  --max-changed-fields 5
```

Fail when visible removals or replacements exist:

```bash
cdk-diff-summary cdk-diff.json --fail-on-remove --fail-on-replace
```

## CLI Options

| Option | Description |
| --- | --- |
| `diff-json-path` | Path to JSON produced by `cdk diff --json`. May also be set with `DIFF_JSON_PATH`. |
| `--title` | Markdown heading for the summary. Defaults to `CDK diff summary`. |
| `--max-changed-fields` | Maximum changed field paths shown per resource. Defaults to `8`. |
| `--collapse-iam-policies` / `--no-collapse-iam-policies` | Collapse large IAM policy document diffs to compact paths. Enabled by default. |
| `--collapse-assets` / `--no-collapse-assets` | Collapse common CDK asset/hash churn. Enabled by default. |
| `--fail-on-remove` | Write the summary, then exit non-zero if visible resource removes exist. |
| `--fail-on-replace` | Write the summary, then exit non-zero if visible resource replacements exist. |
| `--output` | Optional path to append the generated Markdown summary. |
| `--github-step-summary` | Optional path to append GitHub Step Summary Markdown. Defaults to `$GITHUB_STEP_SUMMARY`. |

Environment variables compatible with the GitHub Action wrapper are also supported:

- `DIFF_JSON_PATH`
- `SUMMARY_TITLE`
- `MAX_CHANGED_FIELDS`
- `COLLAPSE_IAM_POLICIES`
- `COLLAPSE_ASSETS`
- `FAIL_ON_REMOVE`
- `FAIL_ON_REPLACE`
- `SUMMARY_OUTPUT_PATH`
- `GITHUB_STEP_SUMMARY`

CLI arguments take precedence over environment variables.

## Example Output

```markdown
## CDK diff summary

| Metric | Count |
| --- | ---: |
| Stack changes | 1 |
| Resource changes | 3 |
| Adds | 1 |
| Modifies | 1 |
| Removes | 0 |
| Replacements | 1 |
| Security group changes | 1 |
| Changes shown below | 4 |

### Replacements

| Stack | Logical ID | Action | Resource type | Changed fields |
| --- | --- | --- | --- | --- |
| PaymentsStack | Worker | replace | AWS::Lambda::Function | `Architectures[]`, `Layers[]` |

### Security group changes

| Stack | Security group | Direction | Protocol | Port | Action |
| --- | --- | --- | --- | --- | --- |
| PaymentsStack | AppSecurityGroup | ingress | tcp | 443 | add |
```

## Local Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
ruff check .
python -m build
twine check dist/*
```

Run from source:

```bash
cdk-diff-summary example_cdk_diff_json/cdk-diff-json-tiny.json
```

## Publishing

This package is ready for PyPI trusted publishing. Create a PyPI project named `cdk-diff-summary`, configure a trusted publisher for this repository and the `publish.yml` workflow, then create a GitHub release.

For a manual dry run:

```bash
python -m build
twine check dist/*
```

CDK diff JSON shape can vary by CDK version. If parsing fails, please open an issue with a sanitized example of the JSON shape that failed.
