Coverage is measured on one CI version and held at 90% statements, 80% branches

.github/workflows/ci.yml

@@ -80,8 +80,17 @@ jobs:
       - name: check
         env:
           CTRLRUN_REQUIRE_RELEASE_FIXTURES: "1"
+          # Measured on one version only; the number is the same on every version, and the
+          # measuring is not free.
+          CTRLRUN_COVERAGE: ${{ matrix.python-version == '3.12' && '1' || '' }}
         run: ./scripts/check.sh
 
+      # CONTRIBUTING.md states the floors; this is what holds them. A drop below either one is
+      # a red check on the pull request that caused it, not a number somebody notices later.
+      - name: Coverage floors
+        if: matrix.python-version == '3.12'
+        run: python scripts/coverage_floor.py coverage.json --statements 90 --branches 80
+
   # SPEC-v0.4 §5, T118. The composite action, run against this repository's own
   # configurations, with `install: .` so it dogfoods the checkout rather than the last
   # release. Two runs, because the second is the one that matters: the N/A path has to be

CONTRIBUTING.md

@@ -45,6 +45,11 @@ that and asserts nothing skipped.
 Use the project's own interpreter for every check. A bare `python` from elsewhere gives two
 spurious failures, one of which is a false green.
 
+`CTRLRUN_COVERAGE=1 scripts/check.sh` measures coverage as well and writes `coverage.json`.
+CI does that on Python 3.12 and holds two floors with `scripts/coverage_floor.py`: **90% of
+statements and 80% of branches**, subprocess workers included. A change that drops either is
+red on its own pull request.
+
 CI does not install the extras the way the block above does. It installs from
 `requirements/*.txt`, hash-pinned locks that `scripts/lock.sh` writes with `uv pip compile`,
 and then the checkout with `--no-deps`; the floors in `pyproject.toml` are unchanged by that.

pyproject.toml

@@ -73,6 +73,10 @@ dev = [
     # isolation the tests did not already have. `scripts/check.sh` passes `-n auto`; `-p
     # no:randomly -n0` is how an ordering bug is reproduced.
     "pytest-xdist>=3",
+    # Coverage is measured once per CI run, on one Python version, and `scripts/coverage_floor.py`
+    # holds the floors CONTRIBUTING.md states. Subprocess workers are covered too: pytest-cov
+    # starts coverage in every child interpreter it spawns.
+    "pytest-cov>=6",
     "mypy>=2.3",
     "ruff>=0.16",
     # SPEC-v0.4 §4.3 - T115 validates `ctrlrun verify --junit` against the checked-in

scripts/check.sh

@@ -31,13 +31,23 @@ run mypy --strict src
 # whose fixtures are per-file (the Postgres schema fixtures especially) pays fewer setups that
 # way, and an ordering assumption inside a file still holds. PYTEST_ARGS overrides for a single
 # test or a serial reproduction.
+# Coverage on request. CI sets CTRLRUN_COVERAGE on one Python version and holds the floors with
+# `scripts/coverage_floor.py`; off by default because a developer wants the verdict and not the
+# number, and measuring costs a third of the wall clock. pytest-cov starts coverage inside the
+# worker processes the suite spawns, so the subprocess backends count too.
+COV_FIRST=""
+COV_SECOND=""
+if [ -n "${CTRLRUN_COVERAGE:-}" ]; then
+    COV_FIRST="--cov=ctrlrun --cov-branch --cov-report="
+    COV_SECOND="--cov=ctrlrun --cov-branch --cov-append --cov-report= --cov-report=json:coverage.json"
+fi
 # shellcheck disable=SC2086
-run pytest -n auto --dist loadfile -m "not serial" ${PYTEST_ARGS:-}
+run pytest -n auto --dist loadfile -m "not serial" $COV_FIRST ${PYTEST_ARGS:-}
 # The windows, on their own. `tests/failure_injection.py`'s proxy holds one statement, kills one
 # COMMIT or partitions one connection, and the assertion is about what a store did inside that
 # window. Seven other workers on the same box turn that into a race, which is how T155b came to
 # report "the window never opened" on one Python version and pass on three.
 # shellcheck disable=SC2086
-run pytest -m serial ${PYTEST_ARGS:-}
+run pytest -m serial $COV_SECOND ${PYTEST_ARGS:-}
 
 printf '\nall checks passed\n'

scripts/coverage_floor.py

@@ -0,0 +1,47 @@
+# SPDX-FileCopyrightText: 2026 The CTRLRun contributors
+# SPDX-License-Identifier: Apache-2.0
+"""Hold the coverage floors CONTRIBUTING.md states, from the JSON `scripts/check.sh` writes.
+
+    python scripts/coverage_floor.py coverage.json --statements 90 --branches 80
+
+Two numbers rather than coverage.py's single blended one, because the blend hides which of the
+two slipped and the floors are stated separately. Exit 1 names the one that did.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def measure(report: Path) -> tuple[float, float]:
+    totals = json.loads(report.read_text(encoding="utf-8"))["totals"]
+    statements = 100.0 * totals["covered_lines"] / totals["num_statements"]
+    branches = 100.0 * totals["covered_branches"] / totals["num_branches"]
+    return statements, branches
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("report", type=Path)
+    parser.add_argument("--statements", type=float, required=True, help="floor, percent")
+    parser.add_argument("--branches", type=float, required=True, help="floor, percent")
+    arguments = parser.parse_args(argv)
+    statements, branches = measure(arguments.report)
+    print(f"statements {statements:6.2f}%  floor {arguments.statements:g}%")
+    print(f"branches   {branches:6.2f}%  floor {arguments.branches:g}%")
+    below = []
+    if statements < arguments.statements:
+        below.append("statements")
+    if branches < arguments.branches:
+        below.append("branches")
+    if below:
+        print(f"coverage_floor: below the floor: {', '.join(below)}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_repository_signals.py

@@ -626,6 +626,57 @@ def test_every_lock_a_workflow_installs_from_exists_and_is_hashed():
                 assert "--hash=" in lines[index + 1], f"{lock}: {line} carries no hash"
 
 
+# --- coverage is measured and the floors are held ---------------------------------------------
+
+
+def test_ci_measures_coverage_on_one_version_and_holds_the_floors():
+    """CONTRIBUTING.md states 90% of statements and 80% of branches; this is the step that
+    holds them, on one version of the matrix, from the JSON `scripts/check.sh` writes."""
+    workflow = yaml.safe_load((WORKFLOWS / "ci.yml").read_text(encoding="utf-8"))
+    steps = workflow["jobs"]["check"]["steps"]
+    check = next(s for s in steps if s.get("name") == "check")
+    assert "CTRLRUN_COVERAGE" in check["env"]
+    floors = next(s for s in steps if s.get("name") == "Coverage floors")
+    assert "scripts/coverage_floor.py coverage.json" in floors["run"]
+    assert "--statements 90" in floors["run"] and "--branches 80" in floors["run"]
+    assert floors["if"] == "matrix.python-version == '3.12'"
+
+    script = (REPO_ROOT / "scripts" / "check.sh").read_text(encoding="utf-8")
+    assert "--cov=ctrlrun --cov-branch" in script and "json:coverage.json" in script
+    contributing = (REPO_ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8")
+    assert "90% of\nstatements and 80% of branches" in contributing
+
+
+def test_coverage_floor_names_the_number_that_slipped(tmp_path):
+    report = tmp_path / "coverage.json"
+    report.write_text(
+        json.dumps(
+            {
+                "totals": {
+                    "covered_lines": 91,
+                    "num_statements": 100,
+                    "covered_branches": 79,
+                    "num_branches": 100,
+                }
+            }
+        )
+    )
+    script = REPO_ROOT / "scripts" / "coverage_floor.py"
+    held = subprocess.run(
+        [sys.executable, str(script), str(report), "--statements", "90", "--branches", "79"],
+        capture_output=True,
+        text=True,
+    )
+    assert held.returncode == 0, held.stderr
+    slipped = subprocess.run(
+        [sys.executable, str(script), str(report), "--statements", "90", "--branches", "80"],
+        capture_output=True,
+        text=True,
+    )
+    assert slipped.returncode == 1
+    assert slipped.stderr.strip() == "coverage_floor: below the floor: branches"
+
+
 # --- a build anyone can repeat ---------------------------------------------------------------