ci(bump-version[script]): Rewrite every workspace version literal in one pass

why: `just bump-version 0.0.1a8` failed mid-run: it rewrote pyproject.toml
and uv.lock, but `check-versions` then reported four packages with
runtime/pyproject drift because the old recipe only globbed
`**/pyproject.toml`. Packages carrying `__version__` (and the five with
`_EXTENSION_VERSION` / Sphinx setup-dict `"version"` literals that track
the workspace version) were silently left behind.
what:
- Extract bump logic into scripts/ci/bump_version.py with PEP 440 validation
  and same-version rejection.
- Widen glob coverage to pyproject.toml, packages/*/src/**/*.py,
  tests/**/*.py, and scripts/**/*.py; exclude .venv, build, dist, .git.
- Justfile recipe now calls the new script; dead one-liner removed.
- Add tests/ci/test_bump_version.py (5 tests) covering rewrite, skip,
  same-version reject, invalid PEP 440 reject, and CLI summary output.

Author: tony

justfile

@@ -162,19 +162,11 @@ _entr-warn:
     @echo "See https://eradman.com/entrproject/                      "
     @echo "----------------------------------------------------------"
 
-# Bump the workspace-wide version string in all pyproject.toml files.
+# Bump every workspace version literal (pyproject, __init__.py, tests, scripts).
 # Usage: just bump-version 0.0.1a8
 bump-version new_version:
     @echo "Bumping workspace version to {{new_version}}..."
-    uv run python -c "\
-    import pathlib, re; \
-    old = re.search(r'version\s*=\s*\"([^\"]+)\"', \
-        pathlib.Path('pyproject.toml').read_text()).group(1); \
-    print(f'  {old} -> {{new_version}}'); \
-    [p.write_text(p.read_text().replace(old, '{{new_version}}')) \
-     for p in sorted(pathlib.Path('.').glob('**/pyproject.toml')) \
-     if old in p.read_text()]; \
-    "
+    uv run python scripts/ci/bump_version.py {{new_version}}
     uv lock
     uv run python scripts/ci/package_tools.py check-versions
-    @echo "Done. Review with: git diff '**/pyproject.toml' uv.lock"
+    @echo "Done. Review with: git diff"

scripts/ci/bump_version.py

@@ -0,0 +1,211 @@
+"""Rewrite the workspace version literal across pyproject, source, tests, and scripts.
+
+The workspace keeps its version duplicated in several places:
+
+- ``pyproject.toml`` (root + every publishable package)
+- ``__version__`` / ``_EXTENSION_VERSION`` constants in package ``__init__.py``
+- Sphinx ``setup()`` return-dict ``"version"`` keys
+- ``tests/test_package_tools.py`` assertions
+- ``smoke_gp_sphinx`` template in ``scripts/ci/package_tools.py``
+
+``scripts/ci/package_tools.py check-versions`` catches drift between the
+pyproject version and whatever the runtime source says, so any literal missed
+by this bump will surface immediately after ``uv lock``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+import typing as t
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[import-not-found]
+
+try:
+    from packaging.version import InvalidVersion, Version
+except ImportError:  # pragma: no cover - packaging is a runtime dep via uv
+    InvalidVersion = ValueError  # type: ignore[assignment,misc]
+    Version = None  # type: ignore[assignment,misc]
+
+
+#: Glob patterns (relative to the workspace root) that may contain version
+#: literals. Order is informational only; rewrites are idempotent.
+BUMP_GLOBS: t.Final[tuple[str, ...]] = (
+    "pyproject.toml",
+    "packages/*/pyproject.toml",
+    "packages/*/src/**/*.py",
+    "tests/**/*.py",
+    "scripts/**/*.py",
+)
+
+#: Path fragments to skip even if a glob matches them.
+EXCLUDE_FRAGMENTS: t.Final[tuple[str, ...]] = (
+    ".venv/",
+    "/build/",
+    "/dist/",
+    "/.git/",
+    "__pycache__/",
+)
+
+
+def _workspace_root() -> pathlib.Path:
+    """Return the repository root."""
+    return pathlib.Path(__file__).resolve().parents[2]
+
+
+def _read_root_version(root: pathlib.Path) -> str:
+    """Return the root ``pyproject.toml`` version string.
+
+    Parameters
+    ----------
+    root : pathlib.Path
+        Repository root containing the root ``pyproject.toml``.
+
+    Returns
+    -------
+    str
+        Version string for the workspace root package.
+    """
+    with (root / "pyproject.toml").open("rb") as handle:
+        data = tomllib.load(handle)
+    return t.cast("str", data["project"]["version"])
+
+
+def _validate_new_version(new_version: str, old_version: str) -> None:
+    """Validate that ``new_version`` is PEP 440 and not the same as ``old_version``.
+
+    Parameters
+    ----------
+    new_version : str
+        Proposed new version.
+    old_version : str
+        Current workspace version.
+    """
+    if new_version == old_version:
+        message = f"new version {new_version!r} equals current version"
+        raise SystemExit(message)
+    if Version is not None:
+        try:
+            Version(new_version)
+        except InvalidVersion as exc:
+            message = f"invalid PEP 440 version {new_version!r}: {exc}"
+            raise SystemExit(message) from exc
+
+
+def _iter_candidate_files(root: pathlib.Path) -> t.Iterator[pathlib.Path]:
+    """Yield files matching any :data:`BUMP_GLOBS` pattern, deduplicated."""
+    seen: set[pathlib.Path] = set()
+    for pattern in BUMP_GLOBS:
+        for path in sorted(root.glob(pattern)):
+            if not path.is_file():
+                continue
+            resolved = path.resolve()
+            if resolved in seen:
+                continue
+            as_posix = resolved.as_posix()
+            if any(fragment in as_posix for fragment in EXCLUDE_FRAGMENTS):
+                continue
+            seen.add(resolved)
+            yield path
+
+
+def _rewrite_file(
+    path: pathlib.Path,
+    old_version: str,
+    new_version: str,
+) -> int:
+    """Rewrite ``old_version`` -> ``new_version`` in ``path``; return replacement count.
+
+    Parameters
+    ----------
+    path : pathlib.Path
+        File to rewrite.
+    old_version : str
+        Literal to replace. Matched verbatim; no regex.
+    new_version : str
+        Replacement literal.
+
+    Returns
+    -------
+    int
+        Number of occurrences replaced. Zero if the file did not change.
+    """
+    original = path.read_text()
+    if old_version not in original:
+        return 0
+    updated = original.replace(old_version, new_version)
+    replacements = original.count(old_version)
+    path.write_text(updated)
+    return replacements
+
+
+def bump_workspace_version(
+    new_version: str,
+    *,
+    root: pathlib.Path | None = None,
+) -> list[tuple[pathlib.Path, int]]:
+    """Rewrite every workspace version literal to ``new_version``.
+
+    Parameters
+    ----------
+    new_version : str
+        Target version, validated as PEP 440.
+    root : pathlib.Path | None
+        Repository root. Defaults to the script's enclosing workspace.
+
+    Returns
+    -------
+    list[tuple[pathlib.Path, int]]
+        (path, replacement_count) pairs for every file touched.
+    """
+    workspace_root = root if root is not None else _workspace_root()
+    old_version = _read_root_version(workspace_root)
+    _validate_new_version(new_version, old_version)
+
+    changes: list[tuple[pathlib.Path, int]] = []
+    for path in _iter_candidate_files(workspace_root):
+        count = _rewrite_file(path, old_version, new_version)
+        if count:
+            changes.append((path, count))
+    return changes
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser."""
+    parser = argparse.ArgumentParser(
+        description=(
+            "Rewrite the shared workspace version across every "
+            "pyproject.toml, __init__.py, and test file."
+        ),
+    )
+    parser.add_argument("new_version", help="Target version (PEP 440)")
+    return parser
+
+
+def main(argv: t.Sequence[str] | None = None) -> int:
+    """CLI entry point."""
+    args = _build_parser().parse_args(argv)
+    root = _workspace_root()
+    old_version = _read_root_version(root)
+    changes = bump_workspace_version(args.new_version, root=root)
+
+    total_replacements = sum(count for _, count in changes)
+    print(f"  {old_version} -> {args.new_version}")
+    for path, count in changes:
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            rel = path
+        print(f"    {rel} ({count})")
+    print(
+        f"  {len(changes)} file(s) changed, {total_replacements} replacement(s)",
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/ci/__init__.py

@@ -0,0 +1,101 @@
+"""Tests for the workspace version-bump CLI."""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+import textwrap
+
+import pytest
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[2] / "scripts" / "ci"))
+import bump_version
+
+
+def _seed_workspace(tmp_path: pathlib.Path, version: str = "0.0.1a7") -> None:
+    """Populate a minimal workspace tree for bump tests."""
+    (tmp_path / "pyproject.toml").write_text(
+        textwrap.dedent(f"""
+            [project]
+            name = "demo-workspace"
+            version = "{version}"
+        """).lstrip(),
+    )
+    pkg = tmp_path / "packages" / "demo" / "src" / "demo"
+    pkg.mkdir(parents=True)
+    (pkg.parent.parent / "pyproject.toml").write_text(
+        textwrap.dedent(f"""
+            [project]
+            name = "demo"
+            version = "{version}"
+        """).lstrip(),
+    )
+    (pkg / "__init__.py").write_text(f'__version__ = "{version}"\n')
+    tests_dir = tmp_path / "tests"
+    tests_dir.mkdir()
+    (tests_dir / "test_demo.py").write_text(
+        f'EXPECTED = "{version}"\n',
+    )
+    scripts_dir = tmp_path / "scripts"
+    scripts_dir.mkdir()
+    (scripts_dir / "helper.py").write_text(
+        f'DEFAULT = "{version}"\n',
+    )
+
+
+def test_bump_updates_pyproject_and_source(tmp_path: pathlib.Path) -> None:
+    """Bumping rewrites pyproject.toml, package source, tests, and scripts."""
+    _seed_workspace(tmp_path, version="0.0.1a7")
+    changes = bump_version.bump_workspace_version("0.0.1a8", root=tmp_path)
+
+    changed_names = {path.name for path, _ in changes}
+    assert "pyproject.toml" in changed_names
+    assert "__init__.py" in changed_names
+    assert "test_demo.py" in changed_names
+    assert "helper.py" in changed_names
+
+    pkg_init = tmp_path / "packages" / "demo" / "src" / "demo" / "__init__.py"
+    assert pkg_init.read_text() == '__version__ = "0.0.1a8"\n'
+    assert '"0.0.1a8"' in (tmp_path / "pyproject.toml").read_text()
+
+
+def test_bump_skips_files_without_old_version(tmp_path: pathlib.Path) -> None:
+    """Files that do not mention the old version are not rewritten."""
+    _seed_workspace(tmp_path, version="0.0.1a7")
+    unrelated = tmp_path / "tests" / "test_unrelated.py"
+    unrelated.write_text('UNRELATED = "something-else"\n')
+
+    changes = bump_version.bump_workspace_version("0.0.1a8", root=tmp_path)
+    assert unrelated.read_text() == 'UNRELATED = "something-else"\n'
+    assert all(path != unrelated for path, _ in changes)
+
+
+def test_bump_rejects_same_version(tmp_path: pathlib.Path) -> None:
+    """Bumping to the current version is rejected loudly."""
+    _seed_workspace(tmp_path, version="0.0.1a7")
+    with pytest.raises(SystemExit, match="equals current version"):
+        bump_version.bump_workspace_version("0.0.1a7", root=tmp_path)
+
+
+def test_bump_rejects_invalid_pep440(tmp_path: pathlib.Path) -> None:
+    """Non-PEP-440 version strings are rejected."""
+    _seed_workspace(tmp_path, version="0.0.1a7")
+    with pytest.raises(SystemExit, match="invalid PEP 440 version"):
+        bump_version.bump_workspace_version("not-a-version!!", root=tmp_path)
+
+
+def test_bump_main_prints_summary(
+    tmp_path: pathlib.Path,
+    capsys: pytest.CaptureFixture[str],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The CLI entry point prints the old -> new header and per-file lines."""
+    _seed_workspace(tmp_path, version="0.0.1a7")
+    monkeypatch.setattr(bump_version, "_workspace_root", lambda: tmp_path)
+
+    exit_code = bump_version.main(["0.0.1a8"])
+
+    assert exit_code == 0
+    out = capsys.readouterr().out
+    assert "0.0.1a7 -> 0.0.1a8" in out
+    assert "file(s) changed" in out