ci(vault): lint scripts/ too, and refuse to plant a tree over a real checkout

Two gaps a verification pass found in the guards added an hour ago.

The lint job named src/ and tests/ and stopped there, so scripts/ was linted by nothing. That is
where check_release_consistency.py lives: the one script CI runs to protect a release was itself
unchecked, and it was unformatted. Both ruff steps cover scripts/ now, and
test_the_lint_job_covers_every_python_directory fails if a directory of Python falls outside the
linter's named paths again. It ships with its own vacuity test, because the assertion would
otherwise pass just as happily against a lint job that named no paths at all.

_plant() writes two FIXED filenames, pyproject.toml and src/qp_vault/__init__.py, into a
directory the caller names. Pointed at a real checkout it would have overwritten this package's
own version declarations. That is the arbitrary-file-write shape a directory check plus a fixed
name always has. It refuses an existing directory now, so it can only land where nothing lives.

Six functions gained the docstrings the house standard requires.

Author: bradleygauthier

.github/workflows/python-ci.yaml

@@ -41,10 +41,13 @@ jobs:
         with:
           python-version: ${{ env.LINT_PYTHON }}
       - run: pip install "ruff==${{ env.RUFF_VERSION }}"
-      - run: ruff check src/ tests/
+      # `scripts/` is in scope, and it was not. The release guard that gates publishing lives
+      # there, so leaving it out meant the one script CI executes to protect a release was itself
+      # linted by nothing. Found by running ruff over the paths the workflow does NOT name.
+      - run: ruff check src/ tests/ scripts/
       # Formatting is checked, not merely available. 95 files were unformatted when this line was
       # added, which is what happens when a formatter is installed and never asserted on.
-      - run: ruff format --check src/ tests/
+      - run: ruff format --check src/ tests/ scripts/
 
   typecheck:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -24,8 +24,12 @@ the code released here.
   and upgrading either is a deliberate line in a diff.
 - **`publish` is gated on `typecheck`.** It was gated only on `lint` and `test`, which is how 1.5.2
   reached the index from a run whose overall conclusion reads `failure`.
-- **`ruff format --check` runs in CI**, and `src/` and `tests/` were formatted to match. 95 files
-  were unformatted, which is what happens when a formatter is installed and never asserted on.
+- **`ruff check` and `ruff format --check` run in CI over `src/`, `tests/` AND `scripts/`**, and
+  all three were formatted to match. 95 files were unformatted, which is what happens when a
+  formatter is installed and never asserted on. `scripts/` was added after a verification pass
+  found that the release guard protecting publishing was itself linted by nothing, and
+  `test_the_lint_job_covers_every_python_directory` now fails if a directory of Python falls
+  outside the linter's named paths again.
 - **The tag must match both declared versions.** `scripts/check_release_consistency.py` refuses a
   publish whose tag disagrees with `pyproject.toml` or `__version__`. `pyproject` read 1.7.0 while
   `main` sat fourteen commits past that tag, and nothing in the build objected.

scripts/check_release_consistency.py

@@ -76,7 +76,25 @@ def check(root: pathlib.Path, tag: str) -> list[str]:
 
 
 def _plant(root: pathlib.Path, project_version: str, dunder: str) -> pathlib.Path:
-    """Write the smallest tree this guard can read, carrying the versions given."""
+    """Write the smallest tree this guard can read, carrying the versions given.
+
+    Args:
+        root: A directory that must NOT already exist. See the refusal below.
+        project_version: Version to write into ``pyproject.toml``.
+        dunder: Version to write into ``__init__.py``.
+
+    Returns:
+        The tree root.
+
+    Raises:
+        FileExistsError: ``root`` already exists.
+    """
+    # `exist_ok=False` is the guard, not a default. This function writes two FIXED filenames,
+    # `pyproject.toml` and `src/qp_vault/__init__.py`, into a directory the caller names. Pointed
+    # at a real checkout it would silently overwrite this package's own version declarations,
+    # which is the arbitrary-file-write shape a dir check plus a fixed name always has. Refusing
+    # an existing directory means it can only ever land somewhere nothing lives yet.
+    root.mkdir(parents=True, exist_ok=False)
     (root / "src" / "qp_vault").mkdir(parents=True, exist_ok=True)
     (root / "pyproject.toml").write_text(
         f'[project]\nname = "qp-vault"\nversion = "{project_version}"\n'
@@ -100,7 +118,9 @@ def self_test() -> int:
         base = pathlib.Path(tmp)
 
         agree = _plant(base / "agree", "9.9.9", "9.9.9")
-        checks.append(("passes when tag, pyproject and __version__ agree", not check(agree, "v9.9.9")))
+        checks.append(
+            ("passes when tag, pyproject and __version__ agree", not check(agree, "v9.9.9"))
+        )
 
         stale = _plant(base / "stale", "9.9.8", "9.9.8")
         checks.append(("fires when the tag is ahead of pyproject", bool(check(stale, "v9.9.9"))))
@@ -127,6 +147,17 @@ def self_test() -> int:
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Run the guard, or its self-test, and report an exit code CI can act on.
+
+    Args:
+        argv: Command-line arguments, or None to read ``sys.argv``.
+
+    Returns:
+        0 when the versions agree (or the self-test passes), 1 when they disagree, and 2 when the
+        tree could not be read at all. Two is deliberately distinct from one: "could not look" is
+        not "nothing wrong", and a caller that collapses them turns an unreadable checkout into a
+        pass.
+    """
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--tag", help="the git tag being published, e.g. v1.8.0")
     parser.add_argument("--root", default=".", help="repository checkout to read")

tests/test_release_guards.py

@@ -35,6 +35,11 @@
 
 
 def _current_version() -> str:
+    """Read the version this checkout declares.
+
+    Returns:
+        The ``project.version`` string from ``pyproject.toml``.
+    """
     import tomllib
 
     with PYPROJECT.open("rb") as handle:
@@ -61,6 +66,15 @@ def _fixture_tree(root: pathlib.Path, project_version: str, dunder: str) -> path
 
 
 def _run_guard(root: pathlib.Path, tag: str) -> subprocess.CompletedProcess[str]:
+    """Invoke the guard as CI does, out of process.
+
+    Args:
+        root: The tree the guard should read.
+        tag: The tag to compare against, with or without its leading ``v``.
+
+    Returns:
+        The completed process, so a test can assert on the exit code AND the message.
+    """
     return subprocess.run(
         [sys.executable, str(GUARD), "--tag", tag, "--root", str(root)],
         capture_output=True,
@@ -139,6 +153,14 @@ def test_the_release_guard_agrees_with_the_real_tree() -> None:
 
 
 def _ruff() -> str:
+    """Locate the ruff the workflow would run.
+
+    Returns:
+        Absolute path to the ruff executable.
+
+    Raises:
+        Skipped: Via ``pytest.skip`` when ruff is not installed.
+    """
     ruff = shutil.which("ruff")
     if ruff is None:
         pytest.skip("ruff is not on PATH")
@@ -181,6 +203,15 @@ def test_ruff_format_check_passes_on_the_real_source_tree() -> None:
 
 
 def _workflow() -> dict:
+    """Parse the CI workflow so its gates can be asserted rather than eyeballed.
+
+    Returns:
+        The parsed workflow document.
+
+    Raises:
+        Skipped: Via ``importorskip`` when PyYAML is absent, which should not happen: it is
+            declared in the dev extra precisely so these assertions run instead of skipping.
+    """
     yaml = pytest.importorskip(
         "yaml", reason="PyYAML is declared in the dev extra; a skip here means it went missing"
     )
@@ -232,6 +263,45 @@ def test_the_workflow_pins_its_linters_to_exact_versions() -> None:
     assert 'pip install "ruff==${{ env.RUFF_VERSION }}"' in text
 
 
+def test_the_lint_job_covers_every_python_directory() -> None:
+    """No directory of Python may sit outside the linter's named paths.
+
+    The lint job named ``src/`` and ``tests/`` and stopped there, so ``scripts/`` was linted by
+    nothing. That is where ``check_release_consistency.py`` lives: the one script CI runs to
+    protect a release was itself unchecked, and it was unformatted when this test was written.
+    A guard outside the guarded set is the shape this whole file exists to catch.
+    """
+    lint_steps = _workflow()["jobs"]["lint"]["steps"]
+    commands = " ".join(step.get("run", "") for step in lint_steps)
+
+    covered = {part.rstrip("/") for part in commands.split() if part.endswith("/")}
+    python_dirs = {
+        child.name
+        for child in REPO.iterdir()
+        if child.is_dir()
+        and not child.name.startswith((".", "_"))
+        and child.name not in {"dist", "docs", "examples", "evals", "node_modules"}
+        and any(child.rglob("*.py"))
+    }
+
+    missing = python_dirs - covered
+    assert not missing, f"lint does not cover: {sorted(missing)} (covers {sorted(covered)})"
+
+
+def test_the_coverage_assertion_can_fail() -> None:
+    """The vacuity test for the one above.
+
+    Without it, that assertion would pass just as happily against a lint job that named no paths
+    at all, since an empty `python_dirs` minus anything is still empty.
+    """
+    commands = "ruff check src/ tests/"
+
+    covered = {part.rstrip("/") for part in commands.split() if part.endswith("/")}
+    missing = {"src", "tests", "scripts"} - covered
+
+    assert missing == {"scripts"}
+
+
 def test_the_workflow_runs_on_a_schedule() -> None:
     """A silent red must become a dated red.