test(golden): semver gate enforcing major bump on pin modify/delete

Pure-function check() takes a changed-files list + base/head versions
and returns (exit_code, message). git interaction lives behind a thin
CLI shim that reads git diff --name-status and pulls __version__ from
both refs.

Author: bnusunny

tests/golden/check_semver_bump.py

@@ -0,0 +1,129 @@
+"""Semver gate: require a major version bump when an existing pinned
+golden output is modified or deleted.
+
+Usage (CI):
+    python tests/golden/check_semver_bump.py --base origin/develop --head HEAD
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+EXPECTED_GLOB = re.compile(r"^tests/golden/templates/.+/expected\.(build|package)\.yaml$")
+
+
+@dataclass(frozen=True)
+class Change:
+    path: str
+    status: str  # "A" added, "M" modified, "D" deleted
+
+
+def _parse_version(s: str) -> Tuple[int, int, int]:
+    m = re.fullmatch(r"(\d+)\.(\d+)\.(\d+)(?:.*)?", s.strip())
+    if not m:
+        raise ValueError(f"unparseable version: {s!r}")
+    return int(m.group(1)), int(m.group(2)), int(m.group(3))
+
+
+def _is_corpus_pin(path: str) -> bool:
+    return bool(EXPECTED_GLOB.match(path))
+
+
+def check(
+    changed: List[Change],
+    base_version: str,
+    head_version: str,
+) -> Tuple[int, str]:
+    """Return (exit_code, message)."""
+    relevant = [c for c in changed if _is_corpus_pin(c.path)]
+
+    if not relevant:
+        return 0, "No corpus pin changes; gate passes."
+
+    modifications = [c for c in relevant if c.status == "M"]
+    deletions = [c for c in relevant if c.status == "D"]
+    additions = [c for c in relevant if c.status == "A"]
+
+    if not (modifications or deletions):
+        # Additions only — no bump required.
+        return 0, f"{len(additions)} new pin(s); no version bump required."
+
+    base_major, _, _ = _parse_version(base_version)
+    head_major, _, _ = _parse_version(head_version)
+
+    if head_major > base_major:
+        return 0, "Major version bumped; gate passes."
+
+    suggested = f"{base_major + 1}.0.0"
+    summary_lines = [
+        "Semver gate FAILED.",
+        f"  base version: {base_version}",
+        f"  head version: {head_version}",
+        f"  required:     major bump (suggested {suggested})",
+        "",
+        "Reason: an existing pinned golden output was modified or deleted.",
+        "  Modifications:",
+        *[f"    M  {c.path}" for c in modifications],
+        "  Deletions:",
+        *[f"    D  {c.path}" for c in deletions],
+        "",
+        f'To fix: edit samcli/__init__.py and set __version__ = "{suggested}".',
+        "If the change is intentional, the major bump signals that to consumers.",
+        "If unintentional, run python tests/golden/update_goldens.py --diff to inspect.",
+    ]
+    return 1, "\n".join(summary_lines)
+
+
+def _read_version_at_ref(ref: str) -> str:
+    """Read __version__ from samcli/__init__.py at a git ref."""
+    out = subprocess.check_output(
+        ["git", "show", f"{ref}:samcli/__init__.py"], text=True
+    )
+    m = re.search(r'__version__\s*=\s*"([^"]+)"', out)
+    if not m:
+        raise RuntimeError(f"cannot find __version__ at {ref}")
+    return m.group(1)
+
+
+def _git_changed_files(base: str, head: str) -> List[Change]:
+    """Return all files changed between base and head with their git status."""
+    out = subprocess.check_output(
+        ["git", "diff", "--name-status", f"{base}...{head}"], text=True
+    )
+    changes: List[Change] = []
+    for line in out.splitlines():
+        if not line.strip():
+            continue
+        parts = line.split("\t")
+        status, path = parts[0], parts[-1]
+        # Renames present as "R<score>\tOLD\tNEW" — split into D + A for our purposes.
+        if status.startswith("R") and len(parts) == 3:
+            old, new = parts[1], parts[2]
+            changes.append(Change(old, "D"))
+            changes.append(Change(new, "A"))
+        else:
+            changes.append(Change(path, status[0]))
+    return changes
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base", required=True, help="git ref of merge base / target branch")
+    parser.add_argument("--head", required=True, help="git ref of PR head")
+    args = parser.parse_args(argv)
+
+    changed = _git_changed_files(args.base, args.head)
+    base_version = _read_version_at_ref(args.base)
+    head_version = _read_version_at_ref(args.head)
+    rc, msg = check(changed, base_version, head_version)
+    print(msg)
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/golden/test_check_semver_bump.py

@@ -0,0 +1,100 @@
+"""Unit tests for check_semver_bump.py — the semver-gate logic.
+
+Avoids actual git invocation by passing changed-files lists directly to
+the lower-level entrypoint.
+"""
+
+import pytest
+
+from tests.golden import check_semver_bump as csb
+
+
+def test_no_changes_passes():
+    rc, msg = csb.check(
+        changed=[],
+        base_version="1.161.1",
+        head_version="1.161.1",
+    )
+    assert rc == 0
+
+
+def test_addition_only_does_not_require_bump():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/case_a/expected.build.yaml", "A"),
+        ],
+        base_version="1.161.1",
+        head_version="1.161.1",
+    )
+    assert rc == 0
+
+
+def test_modification_without_major_bump_fails():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/case_a/expected.build.yaml", "M"),
+        ],
+        base_version="1.161.1",
+        head_version="1.161.2",
+    )
+    assert rc != 0
+    assert "major" in msg.lower()
+    assert "2.0.0" in msg  # suggested next version
+
+
+def test_modification_with_major_bump_passes():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/case_a/expected.build.yaml", "M"),
+        ],
+        base_version="1.161.1",
+        head_version="2.0.0",
+    )
+    assert rc == 0
+
+
+def test_deletion_requires_major_bump():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/case_a/expected.build.yaml", "D"),
+        ],
+        base_version="1.161.1",
+        head_version="1.162.0",
+    )
+    assert rc != 0
+
+
+def test_rename_treated_as_delete_plus_add():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/old/expected.build.yaml", "D"),
+            csb.Change("tests/golden/templates/x/new/expected.build.yaml", "A"),
+        ],
+        base_version="1.161.1",
+        head_version="1.161.2",
+    )
+    # The deletion alone forces major; rename is conservative.
+    assert rc != 0
+
+
+def test_changes_outside_corpus_ignored():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("samcli/lib/foo.py", "M"),
+            csb.Change("tests/golden/harness.py", "M"),
+        ],
+        base_version="1.161.1",
+        head_version="1.161.1",
+    )
+    assert rc == 0
+
+
+def test_template_yaml_changes_ignored_only_expected_yaml_gates():
+    rc, msg = csb.check(
+        changed=[
+            csb.Change("tests/golden/templates/x/case_a/template.yaml", "M"),
+        ],
+        base_version="1.161.1",
+        head_version="1.161.1",
+    )
+    assert rc == 0