Add coverage validation: 90% main-source line coverage gate (py_binary + py_test)

[tinder-maxwellelliott]

Summary

Wires up a coverage gate using a Python py_binary + py_test so the enforcement logic itself is covered by tests. Bazel already produces an LCOV combined report on the test-jre21 jobs (bazel coverage --combined_report=lcov //cli/...) and uploads it as an artifact, but nothing read it — a PR could land that dropped coverage arbitrarily. This PR adds:

• tools/coverage_check.py + //tools:coverage-check py_binary — parses the LCOV report, prints a per-file table sorted by coverage ascending, an overall summary, and exits non-zero if main-source line coverage is below $COVERAGE_THRESHOLD (default 90). Test sources and files with LF:0 (no instrumentation data) are filtered out so thin production-code coverage can't hide behind well-covered tests or placeholder records.
• tools/coverage_check_test.py + //tools:coverage_check_test py_test — 19 unit tests against parse_lcov, filter_main_source, format_report, and main(), covering per-file extraction, non-line LCOV fields skipped, malformed payloads tolerated, multi-prefix include union, zero-line records dropped, threshold boundary inclusive, missing-file → exit 2, env-var threshold override, and stdin/stderr expectations of the main entry point.
• make coverage / make coverage-check / make coverage-test — one-line invocations. make coverage runs bazel coverage then the binary; make coverage-check runs only the binary against an existing LCOV; make coverage-test runs the py_test.
• CI: updated Run bazel-diff tests step to coverage-instrument //cli/... //tools:coverage_check_test, plus a new Enforce coverage threshold step that invokes the py_binary on every test-jre21 matrix entry (ubuntu/macos × bazel 8.x/9.x). The threshold step is placed AFTER the artifact upload so a failed threshold check still preserves the LCOV report.

Threshold set to 90 per the goal.

Why py_binary + py_test (revised from the prior bash-script version)

You asked for the enforcement to be Python via py_binary and to add a py_test so the enforcement logic itself has coverage. The earlier draft of this PR used bash + awk, which couldn't be cleanly unit-tested. Replacing it with Python gave us:

• Importable units (parse_lcov, filter_main_source, format_report, main) that the py_test exercises directly without spawning subprocesses.
• A py_library shared between :coverage-check (the runnable binary) and :coverage_check_test (the test target). With imports = ["."] on the library, the test imports coverage_check by its module name without needing a workspace-rooted path.
• A BUILD_WORKING_DIRECTORY chdir hook in main() so bazel run //tools:coverage-check -- bazel-out/_coverage/... resolves the relative LCOV path against the user's cwd instead of the runfiles directory.

Why draft, still

CI on this PR will tell us the actual current main-source coverage — the data point I couldn't measure cleanly locally (E2ETest hangs on my machine due to a JDK-env sandbox issue, unrelated to this PR; I can run the rest, which shows main-source line coverage of 47.20% without E2E across //cli/... //tools:coverage_check_test). The CI run includes E2ETest, which exercises a lot of the integration paths (BazelQueryService.kt is 0.33% locally without E2E and likely much higher with it), so the real number will be higher — but very likely below 90%.

When the Enforce coverage threshold step fires on this PR, the log will print the per-file table and the overall % before exiting 1. From there we have three reasonable paths:

1. Land at 90% and add tests in follow-up PRs — pick the worst-covered files and write unit coverage for them. Keep the gate at 90; PRs that don't reach 90 stay red.
2. Land with a lower starting threshold and ratchet up — set $COVERAGE_THRESHOLD in the workflow to whatever CI reports today (rounded down a hair), get the gate green, then raise the number as tests land.
3. Refine scope — exclude CLI entry points (Main.kt, picocli command shells, DI wiring) from the denominator via --include.

I'd lean toward (2) for the merge, then (1) for the long game. Happy to do whichever you prefer.

Known limitation: Python coverage instrumentation

bazel coverage //tools:coverage_check_test emits LF:0/LH:0 for tools/coverage_check.py today — Bazel detects the file but doesn't gather data because the Python toolchain in MODULE.bazel doesn't have configure_coverage_tool = True set on the rules_python extension. The py_test still runs and asserts behavior of every public function, so the file IS covered by tests — just not numerically reported in LCOV. The threshold check filters out zero-line records so this doesn't tank the gate.

The day we configure the Python toolchain with coverage_tool, the file will start contributing real numerical coverage to the gate without further code changes; the default --include already lists tools/coverage_check.py.

Verification

• bazel test //tools:coverage_check_test — 19/19 PASS.
• bazel run //tools:coverage-check -- bazel-out/_coverage/_coverage_report.dat --threshold 40 — exit 0, prints overall 47.20%, "PASS".
• bazel run //tools:coverage-check -- bazel-out/_coverage/_coverage_report.dat --threshold 90 — exit 1, prints "FAIL: coverage 47.20% is below threshold 90.00%."
• bazel run //tools:generate-readme — regenerates README from template, in-sync output.
• Did not modify MODULE.bazel.lock; reverted incidental churn before commit.

Test plan

• 19 py_test cases cover the parser, filter, formatter, and main() entry.
• Threshold boundary inclusive (60% threshold against 60% coverage = PASS; 60.01% = FAIL).
• Per-file table sorted by coverage ascending (worst-covered first).
• Test sources (/test/) and zero-line records excluded from numerator and denominator.
• Makefile targets work; bazel run //tools:coverage-check honors BUILD_WORKING_DIRECTORY.
• README regenerated from template.
• CI run on this PR reports the actual main-source coverage % including E2ETest.
• Decide threshold strategy based on CI output.

🤖 Generated with Claude Code