feat(plugin-go): per-package go vet/lint with serialized facts

[raphaelvigee]

What

Per-package Go lint target with nogo-style serialized facts — interprocedural analyzers (printf wrappers, lostcancel, …) keep full fidelity across first-party package boundaries, while caching per package. Linter selection + suppression via .golangci.yml.

Why not golangci-lint directly

golangci-lint loads the whole graph in one process and keeps go/analysis facts in memory only — no fact-file export, incompatible with a per-package build cache. It also hides its analyzers (goanalysis.Linter.getAnalyzers is unexported) and its runner doesn't serialize facts, so it can't be reused as a library here.

But golangci doesn't own the analyzers — it curates upstream go/analysis packages that export theirs.

Approach

• Run x/tools unitchecker (the per-unit driver go vet uses): dep type info via PackageFile, dep facts via PackageVetx, own facts out via VetxOutput.
• heph-govet imports the same upstream analyzers golangci curates — go vet passes + honnef staticcheck/gosimple/stylecheck — and parses .golangci.yml itself (linters.default/enable/disable, linters.exclusions.rules) to select + suppress. No dependency on golangci-lint.
• heph's content-hash caching makes a package re-lint only when its own sources, a dep's archive, a dep's facts, the analyzer binary, or .golangci.yml change.

Targets

• _lint (go_lint) — runs heph-govet, writes lint.facts (consumed by dependents) + lint-report.json. Exits 0 even with findings so facts always cache.
• lint (go_lint_gate) — consumes _lint's report, fails on findings.
• lint-fix (go_lint_fix) — applies the report's suggested fixes back into source via codegen=in_place.
• format (go_format_check) — fails on any unformatted file (writes nothing).
• format-fix (go_format) — reformats sources and writes back via codegen=in_place.

Facts flow first-party-only (bounds the graph); std/thirdparty give type info via their build_lib archives.

.golangci.yml at the workspace root is a hashed config input, passed via HEPH_GOVET_GOLANGCI_CONFIG. Absent → the standard set.

.golangci.yml coverage

• linter selection — linters.default/enable/disable.
• linters.settings — govet (enable/disable/enable-all/disable-all + per-analyzer flags like printf.funcs, shadow.strict); honnef staticcheck/gosimple/stylecheck (checks patterns; initialisms, dot-import-whitelist, http-status-code-whitelist). govet flags are set via Analyzer.Flags.Set before unitchecker.Main (they survive its flag parse — our argv carries none); honnef knobs override config.Analyzer.Run in place; checks filters the analyzer set.
• suppression — //nolint[:l], linters.exclusions.rules (linter/path/text).
• formatters — enable + settings for gofmt/gofumpt/goimports.

Suppression (honored at analysis time)

• //nolint[:l1,l2] — trailing covers its line; own-line also covers the next line; bare covers all. Matched against the golangci linter name (//nolint:gosimple suppresses S1002).
• linters.exclusions.rules — per-rule linter scoping + path/text regexes.

Implemented by wrapping each analyzer's Pass.Report, so the report is already filtered (the gate needs no change).

Fix (lint-fix)

lint-fix (go_lint_fix) rewrites a package's Go sources with go/analysis suggested fixes and writes them back over the tracked files via codegen=in_place.

• Reuses _lint's -json report — which already carries each diagnostic's suggested_fixes (byte-offset text edits) — so it runs no analysis of its own and shares _lint's per-package cache. Inputs: that report + the package's own .go sources. Outputs: the rewritten sources, declared CodegenMode::InPlace, so the engine writes them back on a top-level run (and reaches a fixpoint on re-run).
• Application is purely mechanical, in two pure helpers: report_edits (parse → edits grouped by source basename; first suggested fix per diagnostic, the go/analysis auto-fix convention) and apply_edits (sort by offset, drop out-of-range/overlapping keeping the earliest, splice in one pass). Offsets line up because _lint and lint-fix stage byte-identical sources.
• Sources stage as writable copies (the default, non-read-only stage path), so the in-place overwrite can never touch a shared cache blob.
• .golangci.yml selection flows in through _lint, so the fix target needs no config wiring.
• No Go / heph-govet changes — the report already emits suggested_fixes.

Formatters (format / format-fix)

heph-govet doubles as the formatter driver in a -format mode (a whole-file rewrite path, separate from unitchecker), so formatting reuses the one hermetic Go binary — no second ~50-min tool build. Backends: gofmt (go/format + golangci/gofmt for -s + rewrite rules), gofumpt, goimports (FormatOnly — sort/group/remove; adding imports needs the module graph and would break the hermetic sandbox, so it is not attempted). format-fix mirrors lint-fix (codegen=in_place); format is the check gate.

Not supported in the per-package model (documented)

• unused (and unparam) — whole-program. Feasible via the facts model + a root fan-in target (honnef's SerializedGraph.Merge is exactly that combine); designed, not yet built.
• goimports import-adding (needs the module graph); exclusion presets + rules[].source (only path/text/linter parsed).

Tests

• Rust: spec builders, report parser, gate wiring, config-group wiring; provider resolution (real go list).
• Go: scanNolint + suppressed unit tests (nolint scoping, exclude text/path/linter).
• Smoke: gosimple S1002 + stylecheck ST1000 fire under unitchecker -json exit 0; 95 staticcheck analyzers wired; unknown linter fails; //nolint:gosimple and a text exclude-rule drop S1002 while ST1000 survives; mis-scoped rule does not suppress.
• lint-fix: report_edits / apply_edits (overlap, insertion, out-of-range, first-fix-only), spec builder, an async parse() check asserting in-place pkg-relative outputs, and provider resolution over real go list.
• settings: govet resolve (enable/disable/all) + flag application (printf.funcs, unknown-name failure), honnef check filtering (all/none/-/glob), honnef config override (initialisms + default fallback).
• formatters: each backend (reformat, -s simplify, gofumpt extra rules, goimports sort, idempotence), plus Rust spec builders + provider resolution.
• prod clippy clean; go test ./... green.

Remaining

Building heph-govet through heph (//tools/heph-govet:build) exercises the in-sandbox thirdparty download of x/tools + honnef (go.sum committed; host build verified). The end-to-end ws.run("//:lint") and ws.run("//:lint-fix") tests depend on that step.

🤖 Generated with Claude Code

[raphaelvigee]

In-sandbox build of heph-govet: proven ✅ (with a caveat)

Verified end-to-end that heph can build heph-govet itself — ran //:build on the tool through the engine; the full x/tools + honnef.co/go/tools thirdparty tree compiles hermetically (each package its own build_lib) and links. Test passed.

Caveat — cold build is ~50 min (3033s, no heph cache). heph caches per-package so subsequent builds are fast, but first-run lint latency is brutal.

Recommendation for productization:

• ship heph-govet as a prebuilt/released binary (what most linter integrations do), or
• rely on a warm remote cache so the x/tools+honnef build_libs are pulled, not recompiled.

govet_addr is currently hardcoded to //tools/heph-govet:build; making it injectable would allow a prebuilt path and a fast end-to-end lint test (the only reason the e2e //:lint run isn't in CI is the cold build time).

Coverage as-is: unit (spec builders, report parser, gate, config wiring), provider resolution (real go list), Go suppressor tests, heph-govet smoke tests — plus this manual proof of the in-sandbox build.

Infra notes for reviewers: needs an isolated CARGO_TARGET_DIR (shared target dir links a stale plugin-go rlib → phantom "cannot find GoLintDriver"); the parallel e2e suite trips a sqlite "eval cache disk I/O error", single tests are fine.