fix: harden stable release finalization

Author: CometAPI

README.md

@@ -29,13 +29,14 @@ Project links: [CometAPI](https://www.cometapi.com),
 
 ## Installation
 
-Install the stable release from PyPI with:
+After the protected publication workflow and public-registry verification
+succeed, install the stable release from PyPI with:
 
 ```bash
 python -m pip install 'cometapi==0.1.0'
 ```
 
-See the immutable
+After those gates succeed, the immutable
 [GitHub release](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0)
 and exact [PyPI release](https://pypi.org/project/cometapi/0.1.0/) for the
 published artifact.

scripts/check_version.py

@@ -67,7 +67,7 @@ def _artifact_version(path: Path) -> str:
 }
 
 
-def require_canonical_tag(tag: str, project_version: str) -> str:
+def _require_canonical_tag(tag: str, project_version: str) -> str:
     normalized = normalize_version(project_version)
     alpha = re.fullmatch(r"(?P<base>\d+\.\d+\.\d+)a(?P<number>\d+)", normalized)
     expected = (
@@ -310,7 +310,7 @@ def main() -> int:
     if args.expected:
         versions.append(("expected", args.expected))
     if args.tag:
-        versions.append(("tag", require_canonical_tag(args.tag, project)))
+        versions.append(("tag", _require_canonical_tag(args.tag, project)))
     for value in args.artifacts:
         path = Path(value)
         if not path.is_file():

tests/test_release_documents.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import shutil
 import subprocess
 import sys
 from collections.abc import Callable
@@ -15,16 +16,20 @@
     CANONICAL_SUPPORT,
     CheckError,
 )
-from scripts.check_version import (
-    require_canonical_tag,
-    require_public_preview_docs,
-    require_releasable_docs,
-)
+from scripts.check_version import require_public_preview_docs, require_releasable_docs
 
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
 VERSION_SCRIPT = PROJECT_ROOT / "scripts" / "check_version.py"
 
 
+def _copy_version_checker(root: Path) -> Path:
+    scripts = root / "scripts"
+    scripts.mkdir(exist_ok=True)
+    for name in ("_checks.py", "check_version.py"):
+        shutil.copy2(PROJECT_ROOT / "scripts" / name, scripts / name)
+    return scripts / "check_version.py"
+
+
 def _write_release_documents(root: Path) -> None:
     files = {
         "pyproject.toml": f'''\
@@ -256,11 +261,41 @@ def test_release_version_cli_accepts_current_stable_tag() -> None:
     assert "version agreement passed: 0.1.0" in result.stdout
 
 
-def test_release_version_accepts_approved_initial_alpha_recovery_tag() -> None:
-    assert require_canonical_tag("v0.1.0-alpha.1+recovery.1", "0.1.0a1") == "0.1.0a1"
+def test_release_version_cli_accepts_approved_initial_alpha_recovery_tag(
+    releasable_documents: Path,
+) -> None:
+    version_script = _copy_version_checker(releasable_documents)
+    result = subprocess.run(
+        [
+            sys.executable,
+            str(version_script),
+            "--tag",
+            "v0.1.0-alpha.1+recovery.1",
+            "--require-changelog",
+        ],
+        cwd=releasable_documents,
+        text=True,
+        check=False,
+        capture_output=True,
+    )
+
+    assert result.returncode == 0, result.stderr
+    assert "version agreement passed: 0.1.0a1" in result.stdout
 
 
 @pytest.mark.parametrize("tag", ["v0.1.0-alpha.1", "v0.1.0-alpha.1+recovery.2"])
-def test_release_version_rejects_unapproved_initial_alpha_tag(tag: str) -> None:
-    with pytest.raises(CheckError, match="release tag must use an approved spelling"):
-        require_canonical_tag(tag, "0.1.0a1")
+def test_release_version_cli_rejects_unapproved_initial_alpha_tag(
+    releasable_documents: Path,
+    tag: str,
+) -> None:
+    version_script = _copy_version_checker(releasable_documents)
+    result = subprocess.run(
+        [sys.executable, str(version_script), "--tag", tag, "--require-changelog"],
+        cwd=releasable_documents,
+        text=True,
+        check=False,
+        capture_output=True,
+    )
+
+    assert result.returncode != 0
+    assert "release tag must use an approved spelling" in result.stderr