💫 Toolkit to help you get started with SDD or any other process!
Fix #4345 (3/4): CI guard requiring version bumps on bundled extension changes (#4395)
CrazyBaran13b760a068c7
diff --git a/.github/scripts/check_extension_version_bump.py b/.github/scripts/check_extension_version_bump.pynew file mode 100644index 000000000..4972c8778--- /dev/null+++ b/.github/scripts/check_extension_version_bump.py@@ -0,0 +1,232 @@+#!/usr/bin/env python3+"""Fail a PR that changes bundled extension content without a version bump.++Update offers from `specify extension update` are version-driven: an+extension is offered (and installed) only when the semver in+`extensions/catalog.json` exceeds the installed copy's registered+version. A content change shipped without a version bump is therefore+never delivered automatically (#4345) — a bump is what makes a change+actually reach existing installs, and this guard is what makes the bump+non-optional.++This check enforces two invariants on the extensions listed in+`extensions/catalog.json`:++1. Any change to a file under `extensions/<id>/` must increase the+ `version:` in that extension's `extension.yml` (PEP 440 comparison,+ the same semantics `extension update` uses), and the resulting+ version must itself parse as PEP 440 — including for a brand-new+ extension, since the CLI rejects a manifest whose version it cannot+ parse.+2. Every `version` in `extensions/catalog.json` must parse as PEP 440+ (`extension update` skips entries it cannot parse), and for entries+ with an in-repo directory it must equal a likewise-valid+ `extension.version` in the manifest (the catalog is what update+ checks compare against, and the update preflight rejects a manifest+ whose version differs from the catalog's). This runs over every+ catalog entry, so catalog-only (hosted) entries and catalog-only+ promotions of existing directories are covered too.++Usage:+ check_extension_version_bump.py BASE_REF [HEAD_REF]++BASE_REF is a git ref/SHA for the PR base (must be fetchable with+`git show`). HEAD_REF defaults to the working tree's HEAD. Exits 0 when+all invariants hold, 1 otherwise, printing one line per violation.++Extensions under `extensions/` that are not in the catalog (the+`selftest` fixture and the `template` scaffold) are exempt: no update+flow is driven by their versions.+"""++from __future__ import annotations++import json+import subprocess+import sys+from pathlib import PurePosixPath++import yaml+from packaging.version import InvalidVersion, Version++EXTENSIONS_ROOT = "extensions"+CATALOG_PATH = f"{EXTENSIONS_ROOT}/catalog.json"+++def _changed_paths(base_ref: str, head_ref: str) -> list[str]:+ """Paths under extensions/ that differ between *base_ref* and *head_ref*.++ Uses NUL-delimited output (``-z``): without it git C-quotes any path+ containing non-ASCII or control characters (``"extensions/x/caf\\303\\251"``,+ quotes included), so the leading component would no longer equal+ ``extensions`` and that change would silently escape the guard. Paths+ are decoded with surrogateescape so an undecodable byte can never crash+ the check; only the ASCII ``extensions/<id>/`` prefix is interpreted.+ """+ raw = subprocess.run(+ [+ "git", "diff", "--name-only", "-z", "--no-renames",+ base_ref, head_ref, "--", EXTENSIONS_ROOT,+ ],+ check=True,+ capture_output=True,+ ).stdout+ return [+ chunk.decode("utf-8", errors="surrogateescape")+ for chunk in raw.split(b"\0")+ if chunk+ ]+++def _show(ref: str, path: str) -> str | None:+ """Return the file's content at *ref*, or None when absent there."""+ result = subprocess.run(+ ["git", "show", f"{ref}:{path}"], capture_output=True, text=True+ )+ return result.stdout if result.returncode == 0 else None+++def _manifest_version(manifest_text: str, origin: str) -> str:+ data = yaml.safe_load(manifest_text)+ if not isinstance(data, dict) or not isinstance(data.get("extension"), dict):+ raise ValueError(f"{origin}: manifest is not a mapping with an 'extension' block")+ version = data["extension"].get("version")+ if not isinstance(version, str) or not version.strip():+ raise ValueError(f"{origin}: extension.version is missing or not a string")+ return version.strip()+++def main(argv: list[str]) -> int:+ if len(argv) < 2 or len(argv) > 3:+ print(__doc__, file=sys.stderr)+ return 2+ base_ref = argv[1]+ head_ref = argv[2] if len(argv) == 3 else "HEAD"++ catalog_text = _show(head_ref, CATALOG_PATH)+ if catalog_text is None:+ print(f"::error::{CATALOG_PATH} is missing at {head_ref}")+ return 1+ catalog = json.loads(catalog_text)+ catalog_entries = catalog.get("extensions", {})++ errors: list[str] = []++ # -- Invariant 1: content change requires a version bump ---------------+ changed_ids = {+ parts[1]+ for path in _changed_paths(base_ref, head_ref)+ if len(parts := PurePosixPath(path).parts) >= 3 and parts[0] == EXTENSIONS_ROOT+ }++ for ext_id in sorted(changed_ids):+ if ext_id not in catalog_entries:+ continue # not driven by `extension update` (selftest, template)+ manifest_path = f"{EXTENSIONS_ROOT}/{ext_id}/extension.yml"+ head_manifest = _show(head_ref, manifest_path)+ if head_manifest is None:+ continue # extension removed in this PR+ try:+ head_version = _manifest_version(head_manifest, f"{head_ref}:{manifest_path}")+ except ValueError as exc:+ errors.append(str(exc))+ continue++ # Parse the head version before the new-extension early return: the+ # CLI's ExtensionManifest rejects a version packaging cannot parse and+ # `extension update` skips catalog entries whose version is invalid,+ # so a new extension shipped with e.g. "not-a-version" in both places+ # would be uninstallable even though the catalog check below (plain+ # string equality) passes. Same PEP 440 semantics as the CLI, so+ # prereleases and other accepted forms are handled identically.+ try:+ head_parsed = Version(head_version)+ except InvalidVersion as exc:+ errors.append(+ f"{manifest_path}: extension.version {head_version!r} is not a valid "+ f"PEP 440 version ({exc}); the CLI rejects this manifest."+ )+ continue++ base_manifest = _show(base_ref, manifest_path)+ if base_manifest is None:+ continue # new extension; any valid initial version is fine+ try:+ base_version = _manifest_version(base_manifest, f"{base_ref}:{manifest_path}")+ except ValueError as exc:+ errors.append(str(exc))+ continue++ # Compare with the same PEP 440 semantics the extension update and+ # install code use, so prereleases and other accepted forms cannot+ # bypass the guard (e.g. 2.0.0 -> 1.0.0rc1 is a downgrade). An+ # unparseable base version fails closed.+ try:+ base_parsed = Version(base_version)+ except InvalidVersion as exc:+ errors.append(+ f"{manifest_path}: could not compare versions "+ f"{base_version!r} -> {head_version!r}: {exc}"+ )+ continue+ if head_parsed <= base_parsed:+ errors.append(+ f"{manifest_path}: files under {EXTENSIONS_ROOT}/{ext_id}/ changed but "+ f"extension.version did not increase ({base_version} -> {head_version}). "+ f"Installed copies only receive changes when the version is bumped."+ )++ # -- Invariant 2: catalog versions are valid and match the manifests ----+ # Runs over every catalog entry, changed or not: a catalog-only entry+ # (hosted elsewhere) never has files under extensions/<id>/, and a+ # catalog-only promotion of an existing uncataloged directory never+ # enters Invariant 1, so neither would otherwise have its version parsed.+ for ext_id, entry in sorted(catalog_entries.items()):+ catalog_version = entry.get("version") if isinstance(entry, dict) else None+ if not isinstance(catalog_version, str) or not catalog_version.strip():+ errors.append(f"{CATALOG_PATH}: entry '{ext_id}' has no string 'version'")+ continue+ # `extension update` skips a catalog entry whose version packaging+ # cannot parse, so an invalid catalog version is never offered.+ try:+ Version(catalog_version)+ except InvalidVersion as exc:+ errors.append(+ f"{CATALOG_PATH}: entry '{ext_id}' version {catalog_version!r} is not a "+ f"valid PEP 440 version ({exc}); `extension update` skips such entries."+ )+ continue++ manifest_path = f"{EXTENSIONS_ROOT}/{ext_id}/extension.yml"+ head_manifest = _show(head_ref, manifest_path)+ if head_manifest is None:+ continue # catalog-only entry (e.g. hosted elsewhere); version checked above+ try:+ manifest_version = _manifest_version(head_manifest, f"{head_ref}:{manifest_path}")+ except ValueError as exc:+ errors.append(str(exc))+ continue+ try:+ Version(manifest_version)+ except InvalidVersion as exc:+ errors.append(+ f"{manifest_path}: extension.version {manifest_version!r} is not a valid "+ f"PEP 440 version ({exc}); the CLI rejects this manifest."+ )+ continue+ if catalog_version != manifest_version:+ errors.append(+ f"{CATALOG_PATH}: entry '{ext_id}' has version {catalog_version!r} but "+ f"{manifest_path} declares {manifest_version!r}. `extension update` "+ f"compares against the catalog, so the two must move together."+ )++ for error in errors:+ print(f"::error::{error}")+ if not errors:+ print("Extension version guard: all invariants hold.")+ return 1 if errors else 0+++if __name__ == "__main__":+ sys.exit(main(sys.argv))diff --git a/.github/workflows/extension-version-guard.yml b/.github/workflows/extension-version-guard.ymlnew file mode 100644index 000000000..9dcb6c095--- /dev/null+++ b/.github/workflows/extension-version-guard.yml@@ -0,0 +1,57 @@+name: Extension Version Guard++permissions:+ contents: read++# Bundled extensions only reach existing installs through a version bump:+# `specify extension update` compares the semver in extensions/catalog.json+# against the installed copy and reports "Up to date" whenever they match.+# Content changes shipped without a bump go silently stale on every+# project that already installed the extension (#4345). This guard turns+# "please remember to bump" into a merge requirement.+#+# Deliberately no `paths:` filter: a required status check that is skipped+# by path filtering stays in "Expected" state and blocks every PR that does+# not touch extensions/**. The check runs on every pull request instead and+# the script reports success when nothing under extensions/ changed.+on:+ pull_request:++jobs:+ version-bump:+ runs-on: ubuntu-latest+ steps:+ - name: Checkout+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ # The pull_request checkout is GitHub's merge of the PR head into+ # the base tip. Depth 2 also fetches both parents of that merge+ # commit, so HEAD^1 - the base the merge was actually built on -+ # is available to diff against.+ fetch-depth: 2++ - name: Set up Python+ uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0+ with:+ python-version: "3.14"++ - name: Install check dependencies+ run: python -m pip install --quiet pyyaml packaging++ # Diff against the merge commit's first parent, NOT against+ # github.event.pull_request.base.sha. The payload SHA is the base tip+ # from when the PR was opened and is not refreshed when the base branch+ # moves, while refs/pull/N/merge is rebuilt against the current tip.+ # Diffing the stale SHA against the fresh merge commit attributes+ # unrelated base-branch drift to the PR (observed on #4395: two+ # unbumped extension changes merged to main were blamed on a PR that+ # never touched them). HEAD^1 is by construction the base the merge+ # was built on.+ - name: Check bundled extension version bumps+ run: |+ set -euo pipefail+ if ! git rev-parse --verify --quiet HEAD^2 >/dev/null; then+ echo "::error::HEAD is not the pull request merge commit; cannot determine the PR base"+ exit 1+ fi+ python .github/scripts/check_extension_version_bump.py HEAD^1diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.mdindex ff0e90c23..96d7efbcd 100644--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md@@ -625,6 +625,13 @@ See the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed- **MAJOR**: Breaking changes- **MINOR**: New features- **PATCH**: Bug fixes+- **Bump on every content change**: update offers from `specify extension+ update` are version-driven, so a content change shipped without a+ version bump is never delivered automatically to already-installed+ copies. For the bundled extensions in this repository the bump is+ enforced by CI (`extension-version-guard.yml`): a PR that changes+ files under `extensions/<id>/` must also bump that extension's+ `extension.yml` version and keep `extensions/catalog.json` in sync.### Securitydiff --git a/tests/contract/test_bundled_extension_versions.py b/tests/contract/test_bundled_extension_versions.pynew file mode 100644index 000000000..2d7f0c6c0--- /dev/null+++ b/tests/contract/test_bundled_extension_versions.py@@ -0,0 +1,83 @@+"""Contract tests: bundled extension versions must stay in sync with the catalog.++``specify extension update`` decides whether an installed extension needs+updating by comparing the semver in ``extensions/catalog.json`` against the+installed copy's registered version, and its preflight rejects a manifest+whose version differs from the catalog's. A catalog entry that drifts from+its ``extension.yml`` therefore either hides updates from every installed+copy or makes every offered update fail validation (#4345).++The companion "content change requires a version bump" rule needs the git+diff of a PR and lives in CI+(``.github/scripts/check_extension_version_bump.py`` via the+``extension-version-guard.yml`` workflow); this test enforces the half that+is checkable from a plain working tree.+"""++from __future__ import annotations++import json+from pathlib import Path++import pytest+import yaml+from packaging.version import InvalidVersion, Version++REPO_ROOT = Path(__file__).parents[2]+EXTENSIONS_ROOT = REPO_ROOT / "extensions"+++def _catalog_entries() -> dict[str, dict]:+ catalog = json.loads((EXTENSIONS_ROOT / "catalog.json").read_text(encoding="utf-8"))+ return catalog["extensions"]+++def _manifest_version(ext_id: str) -> str:+ manifest_path = EXTENSIONS_ROOT / ext_id / "extension.yml"+ data = yaml.safe_load(manifest_path.read_text(encoding="utf-8"))+ return data["extension"]["version"]+++def test_catalog_lists_extensions():+ assert _catalog_entries(), "expected at least one extension in extensions/catalog.json"++[email protected]("ext_id", sorted(_catalog_entries()))+def test_catalog_version_matches_manifest(ext_id: str):+ entry = _catalog_entries()[ext_id]+ manifest_path = EXTENSIONS_ROOT / ext_id / "extension.yml"+ if not manifest_path.is_file():+ pytest.skip(f"'{ext_id}' has no in-repo extension directory")+ assert entry.get("version") == _manifest_version(ext_id), (+ f"extensions/catalog.json entry '{ext_id}' and {manifest_path.relative_to(REPO_ROOT)} "+ f"declare different versions - `specify extension update` compares against the "+ f"catalog, so the two must move together"+ )++[email protected]("ext_id", sorted(_catalog_entries()))+def test_bundled_entries_ship_an_extension_directory(ext_id: str):+ entry = _catalog_entries()[ext_id]+ if not entry.get("bundled"):+ pytest.skip(f"'{ext_id}' is not marked bundled")+ assert (EXTENSIONS_ROOT / ext_id / "extension.yml").is_file(), (+ f"catalog marks '{ext_id}' as bundled but extensions/{ext_id}/extension.yml is missing"+ )++[email protected]("ext_id", sorted(_catalog_entries()))+def test_catalog_version_is_valid_pep440(ext_id: str):+ """`extension update` parses each catalog version with packaging and skips+ entries it cannot parse, so every entry - bundled or hosted - must carry+ a valid version, independent of whether it has an in-repo directory."""+ version = _catalog_entries()[ext_id].get("version")+ assert isinstance(version, str) and version.strip(), (+ f"extensions/catalog.json entry '{ext_id}' has no string version"+ )+ try:+ Version(version)+ except InvalidVersion as exc:+ pytest.fail(+ f"extensions/catalog.json entry '{ext_id}' version {version!r} is not a valid "+ f"PEP 440 version ({exc}); `extension update` would skip it"+ )diff --git a/tests/contract/test_extension_version_guard_script.py b/tests/contract/test_extension_version_guard_script.pynew file mode 100644index 000000000..6f31d7a14--- /dev/null+++ b/tests/contract/test_extension_version_guard_script.py@@ -0,0 +1,352 @@+"""Tests for the extension version-bump CI guard script (#4345).++The guard (`.github/scripts/check_extension_version_bump.py`) is the+primary regression prevention for bundled-extension version staleness, so+its failure behavior must be pinned by tests: each scenario builds a real+throwaway git repository and invokes the script against base/head SHAs,+exactly as the `extension-version-guard.yml` workflow does. Without this,+a change to the script's diff or parsing logic could silently disable the+guard while CI stays green.+"""++from __future__ import annotations++import json+import subprocess+import sys+from pathlib import Path++import pytest++REPO_ROOT = Path(__file__).parents[2]+SCRIPT = REPO_ROOT / ".github" / "scripts" / "check_extension_version_bump.py"+++def _git(repo: Path, *args: str) -> str:+ result = subprocess.run(+ ["git", "-C", str(repo), *args],+ check=True,+ capture_output=True,+ text=True,+ )+ return result.stdout.strip()+++def _write_extension(repo: Path, ext_id: str, version: str, script_line: str) -> None:+ ext_dir = repo / "extensions" / ext_id+ ext_dir.mkdir(parents=True, exist_ok=True)+ (ext_dir / "extension.yml").write_text(+ 'schema_version: "1.0"\n'+ "\n"+ "extension:\n"+ f" id: {ext_id}\n"+ f' version: "{version}"\n',+ encoding="utf-8",+ )+ (ext_dir / "script.sh").write_text(f"{script_line}\n", encoding="utf-8")+++def _write_catalog(repo: Path, versions: dict[str, str | dict]) -> None:+ """Write catalog.json; a value is either a bundled entry's version string+ or a full entry dict (for e.g. hosted, non-bundled entries)."""+ (repo / "extensions").mkdir(exist_ok=True)+ payload = {+ "schema_version": "1.0",+ "extensions": {+ ext_id: (+ {"id": ext_id, **spec}+ if isinstance(spec, dict)+ else {"id": ext_id, "version": spec, "bundled": True}+ )+ for ext_id, spec in versions.items()+ },+ }+ (repo / "extensions" / "catalog.json").write_text(+ json.dumps(payload, indent=2), encoding="utf-8"+ )+++def _commit_all(repo: Path, message: str) -> str:+ _git(repo, "add", "-A")+ _git(repo, "commit", "-q", "-m", message)+ return _git(repo, "rev-parse", "HEAD")+++def guard_repo(tmp_path: Path) -> tuple[Path, str]:+ """A git repo with one cataloged and one uncataloged extension at base."""+ repo = tmp_path / "repo"+ repo.mkdir()+ _git(repo, "init", "-q")+ _git(repo, "config", "user.email", "[email protected]")+ _git(repo, "config", "user.name", "Guard Tests")+ _git(repo, "config", "commit.gpgsign", "false")+ # git's default; pinned so the non-ASCII regression below exercises the+ # C-quoting code path even on machines whose global config disables it.+ _git(repo, "config", "core.quotePath", "true")++ _write_extension(repo, "demo", "1.0.0", "echo base")+ _write_extension(repo, "scratch", "1.0.0", "echo base") # not in catalog+ _write_catalog(repo, {"demo": "1.0.0"})+ base_sha = _commit_all(repo, "base")+ return repo, base_sha+++def _run_guard(+ repo: Path, base: str, head: str | None = None+) -> subprocess.CompletedProcess:+ """Invoke the guard as the workflow does: base ref only, head defaulting+ to HEAD inside the script. Pass *head* explicitly only to test the+ optional second argument."""+ return subprocess.run(+ [sys.executable, str(SCRIPT), base, *([head] if head else [])],+ cwd=repo,+ capture_output=True,+ text=True,+ )+++def test_valid_bump_passes(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "demo", "1.1.0", "echo changed")+ _write_catalog(repo, {"demo": "1.1.0"})+ _commit_all(repo, "content change with bump")++ result = _run_guard(repo, base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_unbumped_content_change_fails(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "demo", "1.0.0", "echo changed")+ _commit_all(repo, "content change without bump")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "did not increase" in result.stdout+ assert "extensions/demo/extension.yml" in result.stdout+++def test_unbumped_non_ascii_filename_fails(guard_repo):+ """With core.quotePath (git's default) `git diff --name-only` C-quotes a+ path like extensions/demo/café.txt, quotes included, so a line-based+ parser no longer sees `extensions` as the first component and the+ change escapes the guard. The NUL-delimited diff must still catch it."""+ repo, base = guard_repo+ (repo / "extensions" / "demo" / "café.txt").write_text("new\n", encoding="utf-8")+ _commit_all(repo, "add non-ascii file without bump")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "did not increase" in result.stdout+ assert "extensions/demo/extension.yml" in result.stdout+++def test_merge_commit_first_parent_ignores_base_branch_drift(guard_repo):+ """The workflow diffs against HEAD^1 of GitHub's pull-request merge commit,+ not github.event.pull_request.base.sha. The payload SHA is the base tip+ from when the PR was opened and is never refreshed, while the merge ref+ is rebuilt against the current base tip; diffing the stale SHA against+ the fresh merge commit blames base-branch drift on the PR (seen on+ #4395). The merge commit's first parent is the base it was built on."""+ repo, stale_base = guard_repo+ _git(repo, "checkout", "-q", "-b", "pr")+ (repo / "README.md").write_text("pr change\n", encoding="utf-8")+ _commit_all(repo, "unrelated PR change")++ # Base branch moves on after the PR branched off: an unbumped extension+ # change lands there. GitHub then rebuilds refs/pull/N/merge on top of it.+ _git(repo, "checkout", "-q", "-")+ _write_extension(repo, "demo", "1.0.0", "echo drifted on base")+ _commit_all(repo, "unbumped change on base after PR branched")+ _git(repo, "merge", "-q", "--no-ff", "--no-edit", "pr")++ stale = _run_guard(repo, stale_base)+ assert stale.returncode == 1, stale.stdout + stale.stderr+ assert "did not increase" in stale.stdout # the trap: drift blamed on the PR++ fresh = _run_guard(repo, "HEAD^1")+ assert fresh.returncode == 0, fresh.stdout + fresh.stderr+ assert "all invariants hold" in fresh.stdout+++def test_no_extension_changes_passes(guard_repo):+ """The workflow runs on every pull request (a path-filtered required check+ would block PRs that skip it), so a PR touching nothing under extensions/+ must pass rather than be reported as a violation."""+ repo, base = guard_repo+ (repo / "README.md").write_text("docs only\n", encoding="utf-8")+ _commit_all(repo, "unrelated change")++ result = _run_guard(repo, base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_downgrade_fails(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "demo", "0.9.0", "echo changed")+ _write_catalog(repo, {"demo": "0.9.0"})+ _commit_all(repo, "downgrade")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "did not increase" in result.stdout+++def test_prerelease_downgrade_fails(guard_repo):+ """PEP 440 semantics: 1.0.0rc1 is lower than 1.0.0, and it must not slip+ through as a plain string inequality."""+ repo, base = guard_repo+ _write_extension(repo, "demo", "1.0.0rc1", "echo changed")+ _write_catalog(repo, {"demo": "1.0.0rc1"})+ _commit_all(repo, "prerelease downgrade")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "did not increase" in result.stdout+++def test_manifest_bump_without_catalog_sync_fails(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "demo", "1.1.0", "echo changed")+ _commit_all(repo, "bump without catalog sync")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "must move together" in result.stdout+ assert "catalog.json" in result.stdout+++def test_uncataloged_extension_change_is_exempt(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "scratch", "1.0.0", "echo changed")+ _commit_all(repo, "uncataloged change without bump")++ result = _run_guard(repo, base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_new_cataloged_extension_passes_without_base_version(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "fresh", "0.1.0", "echo new")+ _write_catalog(repo, {"demo": "1.0.0", "fresh": "0.1.0"})+ _commit_all(repo, "add new extension")++ result = _run_guard(repo, base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_explicit_head_argument_is_honored(guard_repo):+ """The optional HEAD_REF argument must select the head to check: pointing+ it at the base commit yields an empty diff even though HEAD has an+ unbumped change."""+ repo, base = guard_repo+ _write_extension(repo, "demo", "1.0.0", "echo changed")+ _commit_all(repo, "content change without bump")++ result = _run_guard(repo, base, head=base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_catalog_only_entry_with_unparseable_version_fails(guard_repo):+ """A hosted (non-bundled) entry has no in-repo directory, so nothing under+ extensions/ changes and Invariant 1 never sees it; its catalog version+ must still parse because `extension update` skips entries it cannot."""+ repo, base = guard_repo+ _write_catalog(+ repo,+ {+ "demo": "1.0.0",+ "hosted": {+ "version": "not-a-version",+ "bundled": False,+ "download_url": "https://example.com/hosted-1.0.0.zip",+ },+ },+ )+ _commit_all(repo, "add hosted entry with invalid version")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "entry 'hosted'" in result.stdout+ assert "is not a valid PEP 440 version" in result.stdout+++def test_catalog_only_promotion_with_unparseable_version_fails(guard_repo):+ """Promoting an existing uncataloged directory by adding only its catalog+ entry changes nothing under extensions/<id>/, so Invariant 1 skips it;+ matching invalid strings must still fail because the CLI cannot use them.+ The catalog-version parse rejects the entry first."""+ repo, _ = guard_repo+ _write_extension(repo, "draft", "not-a-version", "echo draft")+ base = _commit_all(repo, "uncataloged draft with invalid version on base")++ _write_catalog(repo, {"demo": "1.0.0", "draft": "not-a-version"})+ _commit_all(repo, "promote draft via catalog only")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "entry 'draft'" in result.stdout+ assert "is not a valid PEP 440 version" in result.stdout+++def test_catalog_only_promotion_with_invalid_manifest_version_fails(guard_repo):+ """Same promotion, but the catalog carries a valid version while the+ untouched in-repo manifest does not: Invariant 2 must parse the manifest+ itself (not only compare strings) and name the manifest in the error."""+ repo, _ = guard_repo+ _write_extension(repo, "draft", "not-a-version", "echo draft")+ base = _commit_all(repo, "uncataloged draft with invalid version on base")++ _write_catalog(repo, {"demo": "1.0.0", "draft": "1.0.0"})+ _commit_all(repo, "promote draft with a valid catalog version only")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "extensions/draft/extension.yml" in result.stdout+ assert "is not a valid PEP 440 version" in result.stdout+++def test_catalog_only_promotion_with_valid_version_passes(guard_repo):+ """The uncataloged `scratch` fixture carries a valid 1.0.0; cataloging it+ without touching its directory is a legitimate promotion."""+ repo, base = guard_repo+ _write_catalog(repo, {"demo": "1.0.0", "scratch": "1.0.0"})+ _commit_all(repo, "promote scratch via catalog only")++ result = _run_guard(repo, base)+ assert result.returncode == 0, result.stdout + result.stderr+ assert "all invariants hold" in result.stdout+++def test_unparseable_version_fails_closed(guard_repo):+ repo, base = guard_repo+ _write_extension(repo, "demo", "not-a-version", "echo changed")+ _write_catalog(repo, {"demo": "not-a-version"})+ _commit_all(repo, "unparseable version")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "is not a valid PEP 440 version" in result.stdout+ assert "extensions/demo/extension.yml" in result.stdout+++def test_new_extension_with_unparseable_version_fails(guard_repo):+ """A brand-new extension has no base manifest to compare against, but its+ version must still parse: ExtensionManifest rejects a version packaging+ cannot parse and `extension update` skips such catalog entries. Matching+ strings in manifest and catalog must not let it through."""+ repo, base = guard_repo+ _write_extension(repo, "fresh", "not-a-version", "echo new")+ _write_catalog(repo, {"demo": "1.0.0", "fresh": "not-a-version"})+ _commit_all(repo, "add new extension with invalid version")++ result = _run_guard(repo, base)+ assert result.returncode == 1, result.stdout + result.stderr+ assert "is not a valid PEP 440 version" in result.stdout+ assert "extensions/fresh/extension.yml" in result.stdout