test(golden): normalize() — deterministic YAML rendering

Strips volatile Metadata.SamTransformMetrics, sort_keys=True,
single trailing newline. Used by both the harness and the
regenerator so they cannot diverge on serialization.

Author: bnusunny

tests/golden/normalize.py

@@ -0,0 +1,49 @@
+"""Deterministic YAML rendering for golden-template comparison.
+
+The harness and update_goldens.py both call normalize() so the bytes
+written to disk match the bytes the test compares. Determinism rules:
+
+- Resources / Mappings keys sorted alphabetically.
+- Metadata.SamTransformMetrics dropped (varies by run).
+- Empty Metadata block dropped.
+- yaml.safe_dump with sort_keys=True, default_flow_style=False.
+- Single trailing newline.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import yaml
+
+_VOLATILE_METADATA_KEYS = frozenset({"SamTransformMetrics"})
+
+
+def _filter_metadata(template: Dict[str, Any]) -> None:
+    metadata = template.get("Metadata")
+    if not isinstance(metadata, dict):
+        return
+    for key in _VOLATILE_METADATA_KEYS:
+        metadata.pop(key, None)
+    if not metadata:
+        template.pop("Metadata", None)
+
+
+def normalize(template: Dict[str, Any]) -> str:
+    """Render template to deterministic YAML string."""
+    # Mutate a copy so we don't surprise the caller.
+    template = {k: v for k, v in template.items()}
+    if isinstance(template.get("Metadata"), dict):
+        template["Metadata"] = dict(template["Metadata"])
+    _filter_metadata(template)
+
+    rendered = yaml.safe_dump(
+        template,
+        sort_keys=True,
+        default_flow_style=False,
+        width=10**9,  # don't wrap long strings
+        allow_unicode=True,
+    )
+    if not rendered.endswith("\n"):
+        rendered += "\n"
+    return rendered

tests/golden/test_normalize.py

@@ -0,0 +1,87 @@
+"""Unit tests for normalize() — deterministic YAML serialization."""
+
+import pytest
+
+from tests.golden.normalize import normalize
+
+
+def test_normalize_produces_trailing_newline():
+    out = normalize({"Resources": {}})
+    assert out.endswith("\n")
+    assert not out.endswith("\n\n")
+
+
+def test_normalize_sorts_resources_keys():
+    template = {
+        "Resources": {
+            "Zeta": {"Type": "AWS::Lambda::Function"},
+            "Alpha": {"Type": "AWS::Lambda::Function"},
+        },
+    }
+    out = normalize(template)
+    assert out.index("Alpha") < out.index("Zeta")
+
+
+def test_normalize_sorts_mappings_keys():
+    template = {
+        "Mappings": {
+            "Z": {"k": {"v": "1"}},
+            "A": {"k": {"v": "1"}},
+        },
+    }
+    out = normalize(template)
+    assert out.index("A:") < out.index("Z:")
+
+
+def test_normalize_drops_sam_transform_metrics():
+    template = {
+        "Metadata": {
+            "SamTransformMetrics": {"foo": "bar"},
+            "Other": "keep",
+        },
+        "Resources": {},
+    }
+    out = normalize(template)
+    assert "SamTransformMetrics" not in out
+    assert "Other" in out
+
+
+def test_normalize_drops_metadata_block_if_empty_after_filter():
+    template = {
+        "Metadata": {"SamTransformMetrics": {"foo": "bar"}},
+        "Resources": {},
+    }
+    out = normalize(template)
+    assert "Metadata" not in out
+
+
+def test_normalize_is_idempotent():
+    template = {"Resources": {"A": {"Type": "T"}}}
+    once = normalize(template)
+    import yaml
+    twice = normalize(yaml.safe_load(once))
+    assert once == twice
+
+
+def test_normalize_preserves_intrinsic_function_dicts():
+    template = {
+        "Resources": {
+            "F": {
+                "Type": "AWS::Lambda::Function",
+                "Properties": {
+                    "Code": {"ZipFile": {"Fn::Sub": "x-${AWS::Region}"}},
+                },
+            }
+        }
+    }
+    out = normalize(template)
+    assert "Fn::Sub" in out
+    assert "x-${AWS::Region}" in out
+
+
+def test_normalize_uses_block_style_not_flow_style():
+    template = {"Resources": {"A": {"Type": "T", "Properties": {"k": "v"}}}}
+    out = normalize(template)
+    # block style uses indentation, not braces
+    assert "{" not in out
+    assert "}" not in out