Documentation
¶
Overview ¶
surfacecheck is internal maintainer/CI tooling: it scans the complete compiler-visible surface of every public package, under each supported build-tag configuration and target profile, compares the result against the reviewed live baseline, and cross-validates the permanent public-surface audit. Successful modes write one minified JSON document to stdout; every failure writes exactly one minified ax.Error envelope to stderr.
Build constraints create a blind spot the other gates cannot see. go-apidiff diffs one configuration; `go vet ./...` and `go test ./...` compile one configuration; doccover parses source while ignoring build constraints entirely. Nothing else in the repository would notice that ax_no_grpc had quietly started removing a second identifier, or that a tag combination had stopped compiling on windows/arm64. surfacecheck scans the 4 supported tag combinations × 6 GOOS/GOARCH profiles = 24 loads of the seven public packages.
The load COUNT does not scale with the package count: a load is one (configuration, profile) combination, and scanCombination loads every requested package within it. Adding a seventh public package therefore leaves this at 24.
The gate is NOT a one-way ratchet (unlike doccover's baseline.txt): symbols legitimately come and go, so additions and removals both surface as drift and are resolved by a reviewed regeneration:
go run ./internal/cmd/surfacecheck -update git diff internal/cmd/surfacecheck/baseline.json # review every line
Policy as constants: the tag combinations, profile list, and public package list are hardcoded in inventory.go, so a matrix change is a reviewable Go commit auditable through git blame — matching covercheck and benchcheck.
Run from the module root:
go run ./internal/cmd/surfacecheck
Source Files