covergate

Overview ¶

Command covergate turns a Go coverage profile into a number that can carry a threshold, and then enforces one.

The raw profile cannot. `go test ./... -coverprofile` instruments every package in the module, generated output included. A tree carrying a large protoc surface sits at 0% over a big share of the module's statements, which drags the module total far below what the hand-written half measures, so any threshold set on the raw figure would be measuring how much protobuf the service happens to have generated this month. Regenerate a fat service and the number falls with no test having changed. Nothing can be gated on that.

So this tool splits the profile in two, reports the hand-written half, and compares it to a floor:

covergate -dir . -profile cover.out -gate

Generated code is identified by Go's own marker, `// Code generated ... DO NOT EDIT.` before the package clause (golang.org/s/generatedcode), not by a hardcoded gen/ path. That choice pays off the first time a second generator lands outside the directory the list names: its output is excluded on the day it appears without anyone editing anything. It cuts both ways rather than being a way to hide uncovered code, since a well-covered generated tree leaves the denominator too. It is also the same rule golangci-lint applies, so a file exempt from lint for being generated is exempt from coverage for the same reason. Every excluded package is named in the report, so widening the exclusion is visible on the PR that does it rather than only in the total.

The marker itself is read by internal/gomarker, shared with the scan so the coverage denominator and the scanned-code boundary cannot disagree about which files are machine-written.

Exit status: 0 when the report was produced and (under -gate) the floor holds, 1 when the floor is breached, 2 when the tool could not run.