cdk-diff-summary 1.1.1__py3-none-any.whl

cdk_diff_summary/__init__.py

@@ -0,0 +1,3 @@
+"""Summarize AWS CDK diff JSON as compact Markdown."""
+
+__version__ = "1.1.1"

cdk_diff_summary/cli.py

@@ -0,0 +1,167 @@
+"""Command-line interface for cdk-diff-summary."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from os import environ
+from pathlib import Path
+from typing import TextIO
+
+from cdk_diff_summary.config import DEFAULT_TITLE, parse_bool, parse_max_changed_fields
+from cdk_diff_summary.diff import DiffSummary, parse_diff
+from cdk_diff_summary.render import render_summary
+
+
+@dataclass(frozen=True)
+class CliConfig:
+    diff_json_path: str
+    title: str
+    max_changed_fields: int
+    collapse_iam_policies: bool
+    collapse_assets: bool
+    fail_on_remove: bool
+    fail_on_replace: bool
+    output_path: str
+    github_step_summary: str
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        config = parse_args(argv)
+        diff_summary = parse_diff_from_file(config)
+        markdown = render_summary(
+            diff_summary,
+            title=config.title,
+            max_changed_fields=config.max_changed_fields,
+        )
+        append_outputs(config, markdown)
+        return fail_status(config, diff_summary)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"cdk-diff-summary: {exc}", file=sys.stderr)
+        return 1
+
+
+def parse_args(argv: list[str] | None = None) -> CliConfig:
+    parser = argparse.ArgumentParser(
+        description="Render a compact Markdown summary from AWS CDK diff JSON.",
+    )
+    parser.add_argument(
+        "diff_json_path",
+        nargs="?",
+        help="Path to JSON produced by cdk diff --json. Defaults to DIFF_JSON_PATH.",
+    )
+    parser.add_argument(
+        "--title",
+        default=environ.get("SUMMARY_TITLE", DEFAULT_TITLE) or DEFAULT_TITLE,
+        help="Markdown heading for the summary.",
+    )
+    parser.add_argument(
+        "--max-changed-fields",
+        default=environ.get("MAX_CHANGED_FIELDS", "8"),
+        help="Maximum changed field paths to show for each resource.",
+    )
+    parser.add_argument(
+        "--collapse-iam-policies",
+        action=argparse.BooleanOptionalAction,
+        default=parse_bool(environ.get("COLLAPSE_IAM_POLICIES"), default=True),
+        help="Collapse IAM policy document changes. Enabled by default.",
+    )
+    parser.add_argument(
+        "--collapse-assets",
+        action=argparse.BooleanOptionalAction,
+        default=parse_bool(environ.get("COLLAPSE_ASSETS"), default=True),
+        help="Collapse common CDK asset/hash churn. Enabled by default.",
+    )
+    parser.add_argument(
+        "--fail-on-remove",
+        action="store_true",
+        default=parse_bool(environ.get("FAIL_ON_REMOVE"), default=False),
+        help="Exit non-zero after writing the summary if visible removes exist.",
+    )
+    parser.add_argument(
+        "--fail-on-replace",
+        action="store_true",
+        default=parse_bool(environ.get("FAIL_ON_REPLACE"), default=False),
+        help="Exit non-zero after writing the summary if visible replacements exist.",
+    )
+    parser.add_argument(
+        "--output",
+        default=environ.get("SUMMARY_OUTPUT_PATH", "").strip(),
+        help="Optional path to append the generated Markdown summary.",
+    )
+    parser.add_argument(
+        "--github-step-summary",
+        default=environ.get("GITHUB_STEP_SUMMARY", "").strip(),
+        help="Optional path to append GitHub Step Summary Markdown.",
+    )
+
+    args = parser.parse_args(argv)
+    diff_json_path = args.diff_json_path or environ.get("DIFF_JSON_PATH", "").strip()
+    if not diff_json_path:
+        raise ValueError("diff-json-path argument or DIFF_JSON_PATH is required")
+
+    return CliConfig(
+        diff_json_path=diff_json_path,
+        title=args.title,
+        max_changed_fields=parse_max_changed_fields(str(args.max_changed_fields)),
+        collapse_iam_policies=args.collapse_iam_policies,
+        collapse_assets=args.collapse_assets,
+        fail_on_remove=args.fail_on_remove,
+        fail_on_replace=args.fail_on_replace,
+        output_path=args.output,
+        github_step_summary=args.github_step_summary,
+    )
+
+
+def parse_diff_from_file(config: CliConfig) -> DiffSummary:
+    with Path(config.diff_json_path).open(encoding="utf-8") as handle:
+        document = json.load(handle)
+    return parse_diff(
+        document,
+        collapse_iam_policies=config.collapse_iam_policies,
+        collapse_assets=config.collapse_assets,
+    )
+
+
+def append_outputs(config: CliConfig, markdown: str) -> None:
+    if config.github_step_summary:
+        append_file(Path(config.github_step_summary), markdown)
+    if config.output_path:
+        append_file(Path(config.output_path), markdown)
+    if not config.github_step_summary and not config.output_path:
+        sys.stdout.write(markdown)
+
+
+def append_file(path: Path, markdown: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        append_markdown(handle, markdown)
+
+
+def append_markdown(handle: TextIO, markdown: str) -> None:
+    handle.write(markdown)
+    if not markdown.endswith("\n"):
+        handle.write("\n")
+
+
+def fail_status(config: CliConfig, diff_summary: DiffSummary) -> int:
+    if config.fail_on_remove and diff_summary.removes > 0:
+        print(
+            "cdk-diff-summary: visible removes found and --fail-on-remove is set",
+            file=sys.stderr,
+        )
+        return 2
+    if config.fail_on_replace and diff_summary.replacements > 0:
+        print(
+            "cdk-diff-summary: visible replacements found and --fail-on-replace is set",
+            file=sys.stderr,
+        )
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cdk_diff_summary/config.py

@@ -0,0 +1,64 @@
+"""Runtime configuration for the cdk-diff-summary action."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from os import environ
+
+DEFAULT_TITLE = "CDK diff summary"
+TRUE_VALUES = {"1", "true", "yes", "y", "on"}
+FALSE_VALUES = {"0", "false", "no", "n", "off", ""}
+
+
+@dataclass(frozen=True)
+class Config:
+    diff_json_path: str
+    summary_title: str
+    max_changed_fields: int
+    collapse_iam_policies: bool
+    collapse_assets: bool
+    fail_on_remove: bool
+    fail_on_replace: bool
+    summary_output_path: str
+    github_step_summary: str
+
+
+def parse_bool(value: str | None, *, default: bool = False) -> bool:
+    if value is None:
+        return default
+    normalized = value.strip().lower()
+    if normalized in TRUE_VALUES:
+        return True
+    if normalized in FALSE_VALUES:
+        return False
+    raise ValueError(f"expected a boolean value, got {value!r}")
+
+
+def parse_max_changed_fields(value: str | None) -> int:
+    raw_value = "8" if value is None or value.strip() == "" else value.strip()
+    try:
+        parsed = int(raw_value)
+    except ValueError as exc:
+        message = "MAX_CHANGED_FIELDS must be an integer greater than or equal to 1"
+        raise ValueError(message) from exc
+    if parsed < 1:
+        raise ValueError("MAX_CHANGED_FIELDS must be greater than or equal to 1")
+    return parsed
+
+
+def load_config() -> Config:
+    diff_json_path = environ.get("DIFF_JSON_PATH", "").strip()
+    if not diff_json_path:
+        raise ValueError("DIFF_JSON_PATH is required")
+
+    return Config(
+        diff_json_path=diff_json_path,
+        summary_title=environ.get("SUMMARY_TITLE", DEFAULT_TITLE) or DEFAULT_TITLE,
+        max_changed_fields=parse_max_changed_fields(environ.get("MAX_CHANGED_FIELDS")),
+        collapse_iam_policies=parse_bool(environ.get("COLLAPSE_IAM_POLICIES"), default=True),
+        collapse_assets=parse_bool(environ.get("COLLAPSE_ASSETS"), default=True),
+        fail_on_remove=parse_bool(environ.get("FAIL_ON_REMOVE"), default=False),
+        fail_on_replace=parse_bool(environ.get("FAIL_ON_REPLACE"), default=False),
+        summary_output_path=environ.get("SUMMARY_OUTPUT_PATH", "").strip(),
+        github_step_summary=environ.get("GITHUB_STEP_SUMMARY", "").strip(),
+    )

cdk_diff_summary/diff.py

@@ -0,0 +1,320 @@
+"""Parse CDK diff JSON into a small internal model."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cdk_diff_summary.policy import collapse_paths
+
+ADD_ACTIONS = {"add", "create", "+", "addition"}
+REMOVE_ACTIONS = {"delete", "remove", "destroy", "-", "deletion"}
+MODIFY_ACTIONS = {"modify", "update", "change", "~"}
+REPLACE_ACTIONS = {"replace", "replacement", "+/-", "-/+"}
+
+
+@dataclass(frozen=True)
+class ResourceChange:
+    stack: str
+    logical_id: str
+    action: str
+    resource_type: str
+    changed_fields: tuple[str, ...]
+    replacement: bool = False
+
+    @property
+    def group(self) -> str:
+        if self.replacement:
+            return "replacements"
+        normalized = normalize_action(self.action)
+        if normalized == "remove":
+            return "removes"
+        if normalized == "add":
+            return "adds"
+        if normalized == "modify":
+            return "modifies"
+        return "other"
+
+
+@dataclass(frozen=True)
+class SecurityGroupChange:
+    stack: str
+    security_group: str
+    direction: str
+    protocol: str
+    port: str
+    action: str
+
+
+@dataclass(frozen=True)
+class DiffSummary:
+    stack_changes: int
+    resources: tuple[ResourceChange, ...]
+    security_group_changes: tuple[SecurityGroupChange, ...] = ()
+
+    @property
+    def adds(self) -> int:
+        return sum(1 for resource in self.resources if resource.group == "adds")
+
+    @property
+    def modifies(self) -> int:
+        return sum(1 for resource in self.resources if resource.group == "modifies")
+
+    @property
+    def removes(self) -> int:
+        return sum(1 for resource in self.resources if resource.group == "removes")
+
+    @property
+    def replacements(self) -> int:
+        return sum(1 for resource in self.resources if resource.group == "replacements")
+
+
+def parse_diff(
+    document: Any,
+    *,
+    collapse_iam_policies: bool = True,
+    collapse_assets: bool = True,
+) -> DiffSummary:
+    stacks = extract_stacks(document)
+    resources: list[ResourceChange] = []
+    security_group_changes: list[SecurityGroupChange] = []
+    stack_changes = 0
+
+    for stack in stacks:
+        stack_name = str(first_present(stack, "stackName", "name", "id", "stack") or "Unknown")
+        stack_resources = extract_resources(stack)
+        stack_security_group_changes = extract_security_group_changes(stack)
+        has_differences = bool(stack.get("hasDifferences")) if isinstance(stack, dict) else False
+        if stack_resources or stack_security_group_changes or has_differences:
+            stack_changes += 1
+        for resource in stack_resources:
+            resources.append(
+                parse_resource(
+                    resource,
+                    stack_name=stack_name,
+                    collapse_iam_policies=collapse_iam_policies,
+                    collapse_assets=collapse_assets,
+                )
+            )
+        for security_group_change in stack_security_group_changes:
+            security_group_changes.append(
+                parse_security_group_change(
+                    security_group_change,
+                    stack_name=stack_name,
+                )
+            )
+
+    return DiffSummary(
+        stack_changes=stack_changes,
+        resources=tuple(resources),
+        security_group_changes=tuple(security_group_changes),
+    )
+
+
+def extract_stacks(document: Any) -> list[dict[str, Any]]:
+    if isinstance(document, dict):
+        stacks = first_present(document, "stacks", "Stacks", "stackDiffs", "differences")
+        if isinstance(stacks, list):
+            return [stack for stack in stacks if isinstance(stack, dict)]
+        if isinstance(stacks, dict):
+            return [
+                dict({"stackName": name}, **value)
+                for name, value in stacks.items()
+                if isinstance(value, dict)
+            ]
+        if has_resource_collection(document):
+            return [document]
+    if isinstance(document, list):
+        return [stack for stack in document if isinstance(stack, dict)]
+    return []
+
+
+def extract_resources(stack: dict[str, Any]) -> list[dict[str, Any]]:
+    raw_resources = first_present(
+        stack,
+        "resources",
+        "resourceChanges",
+        "ResourceChanges",
+        "changes",
+    )
+    if isinstance(raw_resources, list):
+        return [resource for resource in raw_resources if isinstance(resource, dict)]
+    if isinstance(raw_resources, dict):
+        resources = []
+        for logical_id, resource in raw_resources.items():
+            if isinstance(resource, dict):
+                resources.append(dict({"logicalId": logical_id}, **resource))
+        return resources
+    return []
+
+
+def extract_security_group_changes(stack: dict[str, Any]) -> list[dict[str, Any]]:
+    raw_changes = first_present(
+        stack,
+        "securityGroupChanges",
+        "securityGroups",
+        "SecurityGroupChanges",
+    )
+    if isinstance(raw_changes, list):
+        return [change for change in raw_changes if isinstance(change, dict)]
+    if isinstance(raw_changes, dict):
+        changes = []
+        for security_group, change in raw_changes.items():
+            if isinstance(change, dict):
+                changes.append(dict({"securityGroup": security_group}, **change))
+        return changes
+    return []
+
+
+def parse_resource(
+    resource: dict[str, Any],
+    *,
+    stack_name: str,
+    collapse_iam_policies: bool,
+    collapse_assets: bool,
+) -> ResourceChange:
+    logical_id = str(
+        first_present(resource, "logicalId", "logicalResourceId", "id", "name") or "Unknown"
+    )
+    resource_type = str(first_present(resource, "resourceType", "type", "resourceTypeName") or "")
+    action = normalize_action(
+        str(first_present(resource, "action", "changeType", "operation") or "other")
+    )
+    changed_fields = extract_changed_fields(resource)
+    replacement = is_replacement(resource, changed_fields)
+    if replacement:
+        action = "replace"
+    collapsed_fields = collapse_paths(
+        changed_fields,
+        collapse_iam_policies=collapse_iam_policies,
+        collapse_assets=collapse_assets,
+    )
+
+    return ResourceChange(
+        stack=stack_name,
+        logical_id=logical_id,
+        action=action,
+        resource_type=resource_type,
+        changed_fields=tuple(collapsed_fields),
+        replacement=replacement,
+    )
+
+
+def parse_security_group_change(
+    change: dict[str, Any],
+    *,
+    stack_name: str,
+) -> SecurityGroupChange:
+    security_group = first_present(
+        change,
+        "securityGroup",
+        "securityGroupId",
+        "groupId",
+        "groupName",
+        "name",
+    )
+    direction = first_present(change, "direction", "ruleType", "type")
+    protocol = first_present(change, "protocol", "ipProtocol")
+    port = first_present(change, "port", "fromPort", "toPort", "ports")
+    action = first_present(change, "action", "changeType", "operation")
+
+    return SecurityGroupChange(
+        stack=stack_name,
+        security_group=str(security_group or "Unknown"),
+        direction=str(direction or ""),
+        protocol=str(protocol or ""),
+        port=format_port(port),
+        action=normalize_action(str(action or "other")),
+    )
+
+
+def extract_changed_fields(resource: dict[str, Any]) -> list[str]:
+    raw_changes = first_present(
+        resource,
+        "propertyChanges",
+        "propertyDiffs",
+        "details",
+        "changes",
+        "changedFields",
+    )
+    fields: list[str] = []
+
+    if isinstance(raw_changes, list):
+        for change in raw_changes:
+            if isinstance(change, str):
+                fields.append(change)
+            elif isinstance(change, dict):
+                field = first_present(change, "path", "propertyPath", "name", "field", "target")
+                if field:
+                    fields.append(str(field))
+    elif isinstance(raw_changes, dict):
+        for key, value in raw_changes.items():
+            if isinstance(value, dict):
+                field = first_present(value, "path", "propertyPath", "name", "field")
+                fields.append(str(field or key))
+            else:
+                fields.append(str(key))
+
+    if not fields:
+        field = first_present(resource, "path", "propertyPath")
+        if field:
+            fields.append(str(field))
+    return dedupe(fields)
+
+
+def is_replacement(resource: dict[str, Any], changed_fields: list[str]) -> bool:
+    replacement = first_present(resource, "replacement", "requiresReplacement", "willReplace")
+    if isinstance(replacement, bool) and replacement:
+        return True
+    action = str(first_present(resource, "action", "changeType", "operation") or "").strip().lower()
+    if action in REPLACE_ACTIONS:
+        return True
+
+    raw_changes = first_present(resource, "propertyChanges", "propertyDiffs", "details", "changes")
+    if isinstance(raw_changes, list):
+        for change in raw_changes:
+            if isinstance(change, dict) and change.get("requiresReplacement") is True:
+                return True
+    return any(field.lower() == "replacement" for field in changed_fields)
+
+
+def normalize_action(action: str) -> str:
+    normalized = action.strip().lower()
+    if normalized in ADD_ACTIONS:
+        return "add"
+    if normalized in REMOVE_ACTIONS:
+        return "remove"
+    if normalized in MODIFY_ACTIONS:
+        return "modify"
+    if normalized in REPLACE_ACTIONS:
+        return "replace"
+    return normalized or "other"
+
+
+def first_present(mapping: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in mapping and mapping[key] is not None:
+            return mapping[key]
+    return None
+
+
+def format_port(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, list | tuple):
+        return ", ".join(str(item) for item in value)
+    return str(value)
+
+
+def has_resource_collection(document: dict[str, Any]) -> bool:
+    return any(key in document for key in ("resources", "resourceChanges", "ResourceChanges"))
+
+
+def dedupe(values: list[str]) -> list[str]:
+    seen: set[str] = set()
+    result: list[str] = []
+    for value in values:
+        if value not in seen:
+            seen.add(value)
+            result.append(value)
+    return result

cdk_diff_summary/policy.py

@@ -0,0 +1,99 @@
+"""Noise reduction helpers for changed field paths."""
+
+from __future__ import annotations
+
+import re
+
+IAM_POLICY_ROOTS = (
+    "PolicyDocument",
+    "AssumeRolePolicyDocument",
+    "Policies[].PolicyDocument",
+)
+
+ASSET_PATTERNS = tuple(
+    re.compile(pattern, re.IGNORECASE)
+    for pattern in (
+        r"assetparameters.*artifacthash",
+        r"assethash",
+        r"sourcehash",
+        r"codehash",
+        r"imageuri",
+        r"imageasset",
+        r"docker.*asset",
+        r"s3(object)?key",
+        r"sourceobjectkey",
+        r"metadata.*aws:cdk:path",
+        r"metadata.*asset",
+        r"code\.s3key",
+        r"code\.zipfile",
+    )
+)
+
+
+def normalize_path(path: str) -> str:
+    normalized = path.replace("/", ".")
+    normalized = re.sub(r"\[[0-9]+\]", "[]", normalized)
+    normalized = re.sub(r"\.+", ".", normalized)
+    return normalized.strip(".")
+
+
+def collapse_iam_policy_path(path: str) -> str:
+    normalized = normalize_path(path)
+    if normalized.startswith("PolicyDocument."):
+        return "PolicyDocument"
+    if normalized == "PolicyDocument":
+        return "PolicyDocument"
+    if normalized.startswith("AssumeRolePolicyDocument."):
+        return "AssumeRolePolicyDocument"
+    if normalized == "AssumeRolePolicyDocument":
+        return "AssumeRolePolicyDocument"
+    if ".PolicyDocument." in normalized:
+        return normalized.split(".PolicyDocument.", maxsplit=1)[0] + ".PolicyDocument"
+    return path
+
+
+def collapse_asset_path(path: str) -> str | None:
+    normalized = normalize_path(path)
+    compact = re.sub(r"[^a-z0-9:]", "", normalized.lower())
+    for pattern in ASSET_PATTERNS:
+        if pattern.search(compact) or pattern.search(normalized):
+            return asset_bucket(normalized)
+    return path
+
+
+def asset_bucket(path: str) -> str | None:
+    lowered = path.lower()
+    if "metadata" in lowered:
+        return "Metadata.Asset"
+    if "s3" in lowered or "objectkey" in lowered:
+        return "Code.S3Key"
+    if "image" in lowered or "docker" in lowered:
+        return "Image.Asset"
+    if "hash" in lowered or "assetparameters" in lowered:
+        return "Asset.Hash"
+    if "zipfile" in lowered:
+        return "Code.ZipFile"
+    return None
+
+
+def collapse_paths(
+    paths: list[str],
+    *,
+    collapse_iam_policies: bool,
+    collapse_assets: bool,
+) -> list[str]:
+    collapsed: list[str] = []
+    seen: set[str] = set()
+    for path in paths:
+        next_path = path
+        if collapse_iam_policies:
+            next_path = collapse_iam_policy_path(next_path)
+        if collapse_assets:
+            asset_path = collapse_asset_path(next_path)
+            if asset_path is None:
+                continue
+            next_path = asset_path
+        if next_path not in seen:
+            seen.add(next_path)
+            collapsed.append(next_path)
+    return collapsed

cdk_diff_summary/py.typed

@@ -0,0 +1 @@
+

cdk_diff_summary/render.py

@@ -0,0 +1,129 @@
+"""Render compact Markdown summaries."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from cdk_diff_summary.diff import DiffSummary, ResourceChange, SecurityGroupChange
+
+GROUP_TITLES = (
+    ("replacements", "Replacements"),
+    ("removes", "Removes"),
+    ("adds", "Adds"),
+    ("modifies", "Modifies"),
+    ("other", "Other changes"),
+)
+
+
+def render_summary(summary: DiffSummary, *, title: str, max_changed_fields: int) -> str:
+    lines = [
+        f"## {escape_markdown(title)}",
+        "",
+        "| Metric | Count |",
+        "| --- | ---: |",
+        f"| Stack changes | {summary.stack_changes} |",
+        f"| Resource changes | {len(summary.resources)} |",
+        f"| Adds | {summary.adds} |",
+        f"| Modifies | {summary.modifies} |",
+        f"| Removes | {summary.removes} |",
+        f"| Replacements | {summary.replacements} |",
+        f"| Security group changes | {len(summary.security_group_changes)} |",
+        f"| Changes shown below | {len(summary.resources) + len(summary.security_group_changes)} |",
+        "",
+    ]
+
+    for group, group_title in GROUP_TITLES:
+        resources = [resource for resource in summary.resources if resource.group == group]
+        if not resources:
+            continue
+        lines.extend(render_group(group_title, resources, max_changed_fields=max_changed_fields))
+        lines.append("")
+
+    if summary.security_group_changes:
+        lines.extend(render_security_group_changes(summary.security_group_changes))
+        lines.append("")
+
+    if not summary.resources and not summary.security_group_changes:
+        lines.append("No resource changes found in the CDK diff JSON.")
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_group(
+    title: str,
+    resources: Iterable[ResourceChange],
+    *,
+    max_changed_fields: int,
+) -> list[str]:
+    lines = [
+        f"### {title}",
+        "",
+        "| Stack | Logical ID | Action | Resource type | Changed fields |",
+        "| --- | --- | --- | --- | --- |",
+    ]
+    for resource in resources:
+        fields = format_changed_fields(
+            resource.changed_fields,
+            max_changed_fields=max_changed_fields,
+        )
+        lines.append(
+            "| "
+            + " | ".join(
+                escape_table_cell(value)
+                for value in (
+                    resource.stack,
+                    resource.logical_id,
+                    resource.action,
+                    resource.resource_type,
+                    fields,
+                )
+            )
+            + " |"
+        )
+    return lines
+
+
+def render_security_group_changes(
+    changes: Iterable[SecurityGroupChange],
+) -> list[str]:
+    lines = [
+        "### Security group changes",
+        "",
+        "| Stack | Security group | Direction | Protocol | Port | Action |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ]
+    for change in changes:
+        lines.append(
+            "| "
+            + " | ".join(
+                escape_table_cell(value)
+                for value in (
+                    change.stack,
+                    change.security_group,
+                    change.direction,
+                    change.protocol,
+                    change.port,
+                    change.action,
+                )
+            )
+            + " |"
+        )
+    return lines
+
+
+def format_changed_fields(fields: tuple[str, ...], *, max_changed_fields: int) -> str:
+    if not fields:
+        return "_n/a_"
+    visible = list(fields[:max_changed_fields])
+    if len(fields) > max_changed_fields:
+        visible.append("...")
+    return "`" + "`, `".join(visible) + "`"
+
+
+def escape_table_cell(value: str) -> str:
+    return escape_markdown(value).replace("|", "\\|").replace("\n", "<br>")
+
+
+def escape_markdown(value: str) -> str:
+    return str(value).replace("\r", "")

cdk_diff_summary-1.1.1.dist-info/METADATA

@@ -0,0 +1,170 @@
+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.

cdk_diff_summary-1.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+cdk_diff_summary/__init__.py,sha256=hLZXtj9mBFhZV-3WKIcp25WxzObT_qjPg-mlmApdy4k,78
+cdk_diff_summary/cli.py,sha256=KLhoTskGdLaV6-SgXqXW8IdkPDeDF_DC5hM0FJMrQN8,5650
+cdk_diff_summary/config.py,sha256=WbLw8qw5lTbqYsVsL-YpSnDwWAA78UDJNToRNx9XAuE,2261
+cdk_diff_summary/diff.py,sha256=-BClnXze3c0uvFJ1V5CylsWA1Hb_F11dgtv6OAMVAh0,10254
+cdk_diff_summary/policy.py,sha256=JQHgqAxTTS9N6E1XcCylrIZ6B4wivET7x6-kOwHKweE,2842
+cdk_diff_summary/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+cdk_diff_summary/render.py,sha256=sMdzMecdif5mnA-Dku8hKizKvcLKqlDHogoYLHYZGaQ,3871
+cdk_diff_summary-1.1.1.dist-info/licenses/LICENSE,sha256=rbiCJSp5zGpy3nb6XprOxrr6dMv4FNADz65obU3Y0EE,1086
+cdk_diff_summary-1.1.1.dist-info/METADATA,sha256=_4CB2KyRp75OsjdPvhQ5CteJqlCqjFKMMSO9B3DwvKw,5176
+cdk_diff_summary-1.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+cdk_diff_summary-1.1.1.dist-info/entry_points.txt,sha256=tr-Ta0dOJTLZlEYRT717Op_RrzRvleJzWwRCxWqJEVA,63
+cdk_diff_summary-1.1.1.dist-info/top_level.txt,sha256=dRfbg05BhDK7GtGdImSOpBonIzdoGvrnwICnqVcv9JI,17
+cdk_diff_summary-1.1.1.dist-info/RECORD,,

cdk_diff_summary-1.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cdk_diff_summary-1.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cdk-diff-summary = cdk_diff_summary.cli:main

cdk_diff_summary-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cdk-diff-summary contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdk_diff_summary-1.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cdk_diff_summary