Changed: improve internal release scripts and expand test coverage

Refine SemVer regex to support digit-prefixed alphanumeric prerelease
identifiers. Ensure GitHub anchors match exact version headers to avoid
stable/prerelease collisions. Add unit tests for changelog
post-processing and enable type-checking for the release toolset.

Author: acgetchell

justfile

@@ -243,6 +243,12 @@ help-workflows:
     @echo "  just plot-vs-linalg         # Plot Criterion results (CSV + SVG)"
     @echo "  just plot-vs-linalg-readme  # Plot + update README benchmark table"
     @echo ""
+    @echo "Changelog & releases:"
+    @echo "  just changelog              # Regenerate CHANGELOG.md from full history"
+    @echo "  just changelog-unreleased <ver>  # Prepend unreleased changes for a version"
+    @echo "  just tag <ver>              # Create annotated tag from CHANGELOG.md"
+    @echo "  just tag-force <ver>        # Recreate an existing tag"
+    @echo ""
     @echo "Setup:"
     @echo "  just setup             # Setup project environment (depends on setup-tools)"
     @echo "  just setup-tools       # Install/verify external tooling (best-effort)"
@@ -333,7 +339,7 @@ python-sync: _ensure-uv
 
 python-typecheck: python-sync
     uv run ty check scripts/
-    uv run mypy scripts/criterion_dim_plot.py
+    uv run mypy scripts/criterion_dim_plot.py scripts/tag_release.py scripts/postprocess_changelog.py scripts/subprocess_utils.py
 
 # Setup
 setup: setup-tools

scripts/tag_release.py

@@ -44,13 +44,17 @@
 # ---------------------------------------------------------------------------
 
 # SemVer 2.0.0 strict with required 'v' prefix
+# Alphanumeric prerelease identifier: any [0-9A-Za-z-]+ containing at least one
+# non-digit.  This permits identifiers like "1a" that start with a digit but are
+# not purely numeric (SemVer 2.0.0 §9).
+_ALNUM_ID = r"(?:(?=[0-9A-Za-z-]*[A-Za-z-])[0-9A-Za-z-]+)"
 _SEMVER_RE = re.compile(
     r"^v"
     r"(0|[1-9]\d*)\."
     r"(0|[1-9]\d*)\."
     r"(0|[1-9]\d*)"
-    r"(?:-(?:(?:0|[1-9]\d*)|(?:[A-Za-z-][0-9A-Za-z-]*))"
-    r"(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*"
+    rf"(?:-(?:(?:0|[1-9]\d*)|{_ALNUM_ID})"
+    rf"(?:\.(?:(?:0|[1-9]\d*)|{_ALNUM_ID}))*"
     r")?"
     r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$"
 )
@@ -94,8 +98,7 @@ def extract_changelog_section(changelog: Path, version: str) -> str:
         LookupError: If the version section is not found or empty.
     """
     content = changelog.read_text(encoding="utf-8")
-    escaped = re.escape(version)
-    header_re = re.compile(rf"^##\s*\[?v?{escaped}\]?(?:$|\s|\()", re.MULTILINE)
+    header_re = _version_header_re(version)
 
     lines = content.split("\n")
     section: list[str] = []
@@ -166,11 +169,17 @@ def _get_repo_url() -> str:
     return raw  # best-effort fallback
 
 
+def _version_header_re(version: str) -> re.Pattern[str]:
+    """Build the header regex for *version*, matching ``extract_changelog_section``."""
+    return re.compile(rf"^##\s*\[?v?{re.escape(version)}\]?(?:$|\s|\()")
+
+
 def _github_anchor(changelog: Path, version: str) -> str:
     """Build a GitHub-compatible heading anchor (matches ``github-slugger``)."""
+    header_re = _version_header_re(version)
     try:
         for line in changelog.read_text(encoding="utf-8").splitlines():
-            if line.startswith("## ") and (f"v{version}" in line or f"[{version}]" in line):
+            if header_re.match(line):
                 heading = line.removeprefix("## ").strip()
                 # Strip inline-link markup [text](url) → text
                 heading = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", heading)

scripts/tests/test_postprocess_changelog.py

@@ -0,0 +1,63 @@
+"""Tests for postprocess_changelog.py — trailing blank line hygiene."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from postprocess_changelog import postprocess
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestPostprocess:
+    def test_strips_trailing_blank_lines(self, tmp_path: Path) -> None:
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text("# Changelog\n\n- Item\n\n\n\n", encoding="utf-8")
+
+        postprocess(f)
+
+        assert f.read_text(encoding="utf-8") == "# Changelog\n\n- Item\n"
+
+    def test_preserves_single_trailing_newline(self, tmp_path: Path) -> None:
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text("# Changelog\n\n- Item\n", encoding="utf-8")
+
+        postprocess(f)
+
+        assert f.read_text(encoding="utf-8") == "# Changelog\n\n- Item\n"
+
+    def test_adds_trailing_newline_if_missing(self, tmp_path: Path) -> None:
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text("# Changelog\n\n- Item", encoding="utf-8")
+
+        postprocess(f)
+
+        assert f.read_text(encoding="utf-8") == "# Changelog\n\n- Item\n"
+
+    def test_preserves_internal_blank_lines(self, tmp_path: Path) -> None:
+        content = "# Changelog\n\n## [1.0.0]\n\n### Added\n\n- Item\n\n\n\n"
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text(content, encoding="utf-8")
+
+        postprocess(f)
+
+        result = f.read_text(encoding="utf-8")
+        # Internal blank lines preserved, only trailing ones stripped
+        assert result == "# Changelog\n\n## [1.0.0]\n\n### Added\n\n- Item\n"
+
+    def test_single_newline_file(self, tmp_path: Path) -> None:
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text("\n", encoding="utf-8")
+
+        postprocess(f)
+
+        assert f.read_text(encoding="utf-8") == "\n"
+
+    def test_empty_file(self, tmp_path: Path) -> None:
+        f = tmp_path / "CHANGELOG.md"
+        f.write_text("", encoding="utf-8")
+
+        postprocess(f)
+
+        assert f.read_text(encoding="utf-8") == "\n"

scripts/tests/test_tag_release.py

@@ -36,6 +36,9 @@ class TestValidateSemver:
             "v1.2.3-alpha",
             "v1.2.3+build.42",
             "v1.2.3-beta.1+build.123",
+            "v1.0.0-1a",  # digit-prefixed alphanumeric prerelease
+            "v1.0.0-0a",  # leading zero OK when not purely numeric
+            "v1.0.0-1a.2b",  # dot-separated digit-prefixed IDs
         ],
     )
     def test_valid_versions(self, version: str) -> None:
@@ -50,6 +53,7 @@ def test_valid_versions(self, version: str) -> None:
             "v01.2.3",  # leading zero
             "v1.02.3",  # leading zero
             "v1.2.03",  # leading zero
+            "v1.0.0-01",  # leading zero in purely numeric prerelease
             "vfoo",  # garbage
             "",  # empty
         ],
@@ -175,6 +179,16 @@ def test_fallback_when_not_found(self, tmp_path: Path) -> None:
         changelog.write_text("# Changelog\n", encoding="utf-8")
         assert _github_anchor(changelog, "9.9.9") == "v999"
 
+    def test_does_not_match_prerelease_heading(self, tmp_path: Path) -> None:
+        """Looking for 1.0.0 must not match ## [1.0.0-rc.1]."""
+        changelog = tmp_path / "CHANGELOG.md"
+        changelog.write_text(
+            "# Changelog\n\n## [1.0.0-rc.1] - 2025-01-01\n\n- Item\n",
+            encoding="utf-8",
+        )
+        # Should fall back since no exact 1.0.0 heading exists
+        assert _github_anchor(changelog, "1.0.0") == "v100"
+
 
 # ---------------------------------------------------------------------------
 # Tag size limit handling