feat(coverage-gate): systematic new-code coverage tool [mache-66d8df]

[jamestexas]

Summary

A diff-aware NEW-CODE coverage gate (tools/coverage-gate/) that enforces
"every new prod line is covered" per PR. Pure stdlib Go, no new module deps.
Lives alongside the existing one-off tools in tools/.

This PR ships the tool only. CI wiring (calling it from task check
or a GHA job) is a deliberate follow-up so the contract can land and be
exercised locally first.

Contract

coverage-gate <cover.out> <diff.patch>

• cover.out — produced by go test -coverprofile=cover.out ./...
• diff.patch — git diff base..HEAD > diff.patch or gh pr diff <num> > diff.patch

Exit codes:

• 0 — every new prod line is either covered, not a statement (decl, blank,
  comment), or annotated // coverage:ignore
• 1 — at least one new prod line is uncovered; per-file report on stdout
• 2 — usage / I/O / parse error

What counts as "new prod line":

• +-prefixed line in a unified-diff hunk
• file is .go, NOT _test.go, NOT under /testdata/
• line is not blank
• line does not start with // or /* (after trim)
• line does not contain // coverage:ignore suffix

Output format (failure)

NEW PROD LINES NOT COVERED:

internal/leyline/socket.go
  L190-191
  L256-257

4 new prod line(s) uncovered. Either add tests or annotate the line with `// coverage:ignore`.

Contiguous uncovered lines collapse into Lstart-end blocks. Files sort
alphabetically. Total count at the bottom.

Per-PR verification

PR #389 (DiscoverOrStart rewrite)

$ go run ./tools/coverage-gate /tmp/pr389.cov /tmp/pr389.diff
NEW PROD LINES NOT COVERED:

internal/leyline/socket.go
  L190-191
  L256-257

4 new prod line(s) uncovered.   exit 1

L190-191 is the stale-managed-daemon reap branch; L256-257 is the
last-chance pre-spawn liveness check + leftover-socket cleanup. Both are
real new prod lines without test coverage — exactly the kind of thing
this gate exists to surface.

PR #388 (download-leyline retarget)

$ go run ./tools/coverage-gate /tmp/pr388.cov /tmp/pr388.diff
NEW PROD LINES NOT COVERED:

internal/leyline/socket.go
  L583
  L605

2 new prod line(s) uncovered.   exit 1

Both are inside downloadLeyline — assetName := fmt.Sprintf(...) and
the http.StatusNotFound branch. Exercised only via network, hence
no automated coverage. Honest report; humans decide whether to backfill
with an httptest-driven test or annotate // coverage:ignore.

Self-tests

15 tests, all pass:

• TestParseProfile / TestParseProfileMalformed
• TestParseDiff / TestParseHunkNewStart
• TestIgnoreTestFiles / TestIgnoreTestdataAndNonGo / TestIgnoreComments
• TestIntersect / TestIntersectOverlappingCoveredWins / TestIntersectStableSort
• TestCollapseBlocks
• TestNormalizeProfilePaths
• TestExitCodeZeroWhenCovered / TestExitCodeOneWhenUncovered / TestExitCodeOneReportFormat
  (integration via built binary + os/exec)

ok  github.com/agentic-research/mache/tools/coverage-gate  1.18s

task check clean (fmt + vet + golangci-lint + full test suite +
validate + docs:lint).

Test plan

• go test ./tools/coverage-gate/ passes locally (15 tests)
• task check passes
• Tool reports uncovered lines on PR fix(leyline): dedup DiscoverOrStart auto-spawn [mache-52a23a] #389 (verbatim above)
• Tool reports uncovered lines on PR fix(leyline): public ley-line-open download + version pin [mache-9051f0] #388 (verbatim above)
• No edits outside tools/coverage-gate/
• Reviewer: confirm exit-code contract matches expectations
• Follow-up PR: wire into task check and/or GHA workflow

Files

Single new package, single new directory:

• tools/coverage-gate/main.go (~340 LOC)
• tools/coverage-gate/main_test.go (~290 LOC, 15 tests)

[github-actions]

find_smells (advisory)

Scoped to files changed in this PR. Rules below run on the standalone (no-LLO) cross-ref tables; _ast rules (cyclomatic_complexity, long_function, long_file, magic_int_in_comparison) are not exercised here.

fan_out_skew — 1 finding(s) in changed files

Source	Node	Metric
tools/coverage-gate/main.go	main/functions/parseProfile/source	22

Rules: see docs/ARCHITECTURE.md for the full registry. Advisory only — these are heuristics, not gates.