coveragecheck

Documentation

Overview

Package coveragecheck is the mechanical coverage gate (Phase 21.5).

Until Phase 21.5, the AGENTS.md §11 coverage bands — 80% new packages, 85% the Store drivers and conformance-tested subsystems, 70% CLI / tooling — were aspirational: `make test` ran `go test -race ./...` with no `-coverprofile` and no threshold, so a coverage regression slipped through unless a reviewer caught it by eye. coveragecheck makes the bands mechanical: it parses a Go coverage profile, computes per-package statement coverage, compares each package against its required threshold, and exits non-zero on any shortfall.

The threshold map lives in coverage.json next to this package: each package maps to a required percentage keyed to its AGENTS.md band, with explicit, documented overrides where a package genuinely cannot reach its band hermetically (the subprocess-orchestrating CLI packages, the conformance harness packages whose statements are exercised only when a driver runs them). An override carries a reason string so the justification travels with the config — never a silent lowering of a band.

The checker is wired into `make coverage` and the CI `go` job; a regression fails the build (CLAUDE.md §11, §4.2).

Index

• Variables
• func WriteReport(w io.Writer, rep *Report)
• type Band
• type Config
  • func LoadConfig(r io.Reader) (*Config, error)
• type PackageCoverage
  • func ParseProfile(r io.Reader) ([]PackageCoverage, error)
  • func (p PackageCoverage) Percent() float64
• type PackageThreshold
• type Report
  • func Check(cfg *Config, profile io.Reader) (*Report, error)
• type Result

Variables

var ErrShortfall = errors.New("coverage below threshold")

ErrShortfall is returned (wrapped) by Check when one or more packages fall below their required coverage threshold.

var ErrUnconfigured = errors.New("package has no coverage threshold configured")

ErrUnconfigured is returned (wrapped) by Check when the profile names a package that has no entry in the threshold config and is not exempt — a new package must be added to coverage.json deliberately, never silently ungated.

Functions

func WriteReport

func WriteReport(w io.Writer, rep *Report)

WriteReport renders rep as an aligned, human-readable table to w. A write error to the report stream is not actionable, so it is intentionally not surfaced (the same convention the CLI print helpers follow).

Types

type Band

type Band string

Band is one AGENTS.md §11 coverage band. The band a package belongs to is recorded in the config so a report can show which bar a number is held to.

const (
	// BandNewPackage is the 80% band for a new package.
	BandNewPackage Band = "new-package"
	// BandConformance is the 85% band for the Store drivers and the other
	// conformance-tested subsystems.
	BandConformance Band = "conformance"
	// BandCLI is the 70% band for CLI / tooling packages.
	BandCLI Band = "cli-tooling"
	// BandHarness marks a conformance *harness* package — a test-helper
	// package whose statements are exercised only when a driver runs the
	// suite, so its self-coverage sits below every product band by
	// construction. Its threshold is a documented override, not a band.
	BandHarness Band = "harness-override"
	// BandSubprocess marks a package that orchestrates subprocesses with
	// branches a hermetic suite cannot reach (the Phase 20 buildpkg/runpkg/
	// installpkg finding); its threshold is a documented override.
	BandSubprocess Band = "subprocess-override"
)

The three AGENTS.md §11 bands plus the harness carve-out.

type Config

type Config struct {
	// Comment is a free-text header documenting the config; it has no effect
	// on the gate. Present so coverage.json can carry its own rationale (JSON
	// has no comment syntax).
	Comment string `json:"_comment,omitempty"`
	// Packages maps a full Go import path to its threshold.
	Packages map[string]PackageThreshold `json:"packages"`
	// Exempt lists import paths excused from the gate — a package that
	// legitimately has no coverable statements (an entrypoint shim). An exempt
	// package missing from the profile is not an error.
	Exempt []string `json:"exempt"`
}

Config is the parsed coverage.json: the per-package threshold map plus the list of import-path prefixes exempt from the gate entirely (a package with no statements to cover — a `main`, a pure-declaration package).

func LoadConfig

func LoadConfig(r io.Reader) (*Config, error)

LoadConfig parses a Config from JSON.

type PackageCoverage

type PackageCoverage struct {
	// Package is the full Go import path.
	Package string
	// Covered is the number of covered statements.
	Covered int64
	// Total is the total number of statements.
	Total int64
}

PackageCoverage is the computed statement coverage of one package.

func ParseProfile

func ParseProfile(r io.Reader) ([]PackageCoverage, error)

ParseProfile parses a Go coverage profile (the format `go test -coverprofile` writes) and aggregates per-package statement counts.

A profile line is `import/path/file.go:startLine.col,endLine.col numStmt count`. The package is the import path with the trailing `/file.go` stripped. The first line is the `mode:` header and is skipped.

func (PackageCoverage) Percent

func (p PackageCoverage) Percent() float64

Percent is the package's statement-coverage percentage. A package with no statements is reported as 100% — there is nothing to leave uncovered.

type PackageThreshold

type PackageThreshold struct {
	// Min is the minimum statement coverage percentage the package must hold.
	Min float64 `json:"min"`
	// Band records which AGENTS.md band (or override class) Min derives from.
	Band Band `json:"band"`
	// Reason documents an override — required when Band is an override class,
	// optional otherwise. It travels in the config so the justification is
	// reviewable (CLAUDE.md §11: never a silent lowering of a band).
	Reason string `json:"reason,omitempty"`
}

PackageThreshold is one package's required coverage and the rationale for the number.

type Report

type Report struct {
	// Results is every checked package, sorted by import path.
	Results []Result
	// Failures is the subset of Results that fell short of their threshold.
	Failures []Result
}

Report is the outcome of a full Check run.

func Check

func Check(cfg *Config, profile io.Reader) (*Report, error)

Check parses profile against cfg and returns a Report. It returns a wrapped ErrShortfall when any non-exempt package is below its threshold, and a wrapped ErrUnconfigured when the profile names a package with no config entry and no exemption — a new package must be gated deliberately.

A package listed in cfg but absent from the profile (it shipped no test binary, or it has no statements) is reported as a 100% pass: the gate never fails for a missing measurement, only for a measured shortfall.

type Result

type Result struct {
	// Package is the import path.
	Package string
	// Coverage is the measured statement-coverage percentage.
	Coverage float64
	// Required is the threshold the package was held to.
	Required float64
	// Band is the band (or override class) the threshold derives from.
	Band Band
	// Reason carries an override's documented justification, if any.
	Reason string
	// Exempt is true when the package is gate-exempt (no coverable statements).
	Exempt bool
	// Pass is true when the package met its threshold or is exempt.
	Pass bool
}

Result is one package's verdict.