Coverage Gap Audit¶

Date added: 2026-05-06

This note records the coverage-gap audit slice of the broader coverage/test-quality release task. It does not claim that total line coverage has reached 100 percent.

Tool¶

The deterministic audit helper is:

./.venv-linux/bin/python tools/audit_coverage_gaps.py

It inventories Python package files under src/scpn_quantum_control/, parses a coverage.xml report produced by pytest-cov, and classifies each source file as:

Status	Meaning
`ok`	Present in the XML report and at or above the configured per-file threshold.
`below_threshold`	Present in the report but below the configured per-file threshold.
`missing_from_report`	Present in source but absent from the coverage report.

The machine-readable form is:

./.venv-linux/bin/python tools/audit_coverage_gaps.py --json

If the human-readable summary reports coverage_report_warning, regenerate coverage.xml before treating missing_from_report rows as real coverage gaps.

The release-gating form is:

./.venv-linux/bin/python tools/audit_coverage_gaps.py --fail-on-gap

Justified Exclusions Gate¶

Release gating stays strict by default: missing files and files below the configured line-rate threshold fail --fail-on-gap. If a file has an accepted, reviewed reason to remain outside the executable coverage surface, record it in an explicit exclusions file instead of relying on an implicit omission.

{
  "exclusions": [
    {
      "path": "src/scpn_quantum_control/example.py",
      "reason": "Hardware-only path covered by integration gate with external device access."
    }
  ]
}

Run the gate with the exclusions file:

./.venv-linux/bin/python tools/audit_coverage_gaps.py \
  --fail-on-gap \
  --justified-exclusions coverage_justified_exclusions.json

Every exclusion requires a non-empty path and reason. Justified exclusions remain visible in the text summary and JSON output as justified_exclusion; they are accepted review decisions, not silently omitted coverage gaps.

As of 2026-05-18, the exclusions file also accepts path_glob for reviewed generated-code packages whose release contract is covered by higher-level reconciliation tests. The release exclusions file is:

docs/coverage_justified_exclusions_2026-05-18.json

Intended Coverage Workflow¶

Generate a fresh XML report first:

./.venv-linux/bin/pytest --cov=scpn_quantum_control --cov-report=xml

Then run the audit:

./.venv-linux/bin/python tools/audit_coverage_gaps.py --fail-on-gap

The tool is intentionally read-only. It does not run tests, mutate coverage settings, or infer scientific validation from coverage percentage alone.

CI Integration¶

The main CI workflow runs the audit after the Python 3.12 coverage job creates coverage.xml:

python tools/audit_coverage_gaps.py --json > coverage-gap-audit.json

CI uploads coverage-gap-audit.json as a 30-day artifact named coverage-gap-audit-3.12. This is intentionally an observation step, not a hard per-file gate. The existing CI gate remains --cov-fail-under=95; the stricter --fail-on-gap mode is reserved for release closure once uncovered files have been closed with behavioural tests or explicitly justified exclusions.

Claim Boundary¶

This closes only the release-safety need for a reproducible coverage-gap inventory. The broader roadmap item remains open until uncovered files are closed with behavioural tests or explicitly justified exclusions.