How do you package custom analyzers into a binary that go vet -vettool can run, and what does that protocol constrain?

## Three drivers, one framework An `*analysis.Analyzer` cannot run by itself; something has to schedule it. `golang.org/x/tools/go/analysis` ships the drivers: - **`singlechecker.Main(a *analysis.Analyzer)`** — a `main` for exactly one check. The binary is conventionally named after the check. - **`multichecker.Main(analyzers ...*analysis.Analyzer)`** — one binary containing a suite. Each check gets its own `-name` flag so users can enable or disable them individually, and checks that share a `Requires` dependency (typically `inspect.Analyzer`) walk the syntax once between them. - **`unitchecker.Main(analyzers ...*analysis.Analyzer)`** — a driver that *only* speaks the build-tool protocol, for a binary that will never be run by hand. `singlechecker` and `multichecker` are dual-mode. Invoked with package patterns they load and analyse packages themselves and print diagnostics; invoked with a single `.cfg` file argument — which is what the go command does — they delegate to `unitchecker.Run` and behave as a vet tool. That is why one binary covers both `mycheck ./...` for local experimentation and `go vet -vettool=mycheck ./...` for the build. ## The protocol When you pass `-vettool=prog`, the go command: 1. runs `prog -V=full` to obtain the tool's identity, which becomes part of the cache key for vet results; 2. runs `prog -flags` to learn, as JSON, which flags the tool accepts, so that `go vet -mycheck.strict` can be forwarded; 3. for each package in the build, writes a config file describing that *compilation unit* — the Go files, the package's import map, the export data files for its dependencies, the paths of fact files for those dependencies, and where to write its own facts — and runs `prog thatfile.cfg`. Diagnostics come back on standard error and the exit status tells the go command whether the package failed. ## What the protocol constrains **One package per invocation.** The tool is not handed the module; it is handed a unit. It must not go looking for other source on disk — under a build system the source may not even be where the tool expects, and results would stop being reproducible or cacheable. **Cross-package information must be facts.** If your check needs to know that a function in another package is, say, a logging wrapper that takes a format string, the analyzer declares a `FactTypes` entry, exports a fact about that object with `pass.ExportObjectFact` when it analyses the declaring package, and reads it back with `pass.ImportObjectFact` when it analyses a caller. The driver serialises facts to files and passes them along the dependency edges; declaring `FactTypes` is also what makes the driver run your analyzer on dependencies at all. Fact types must be serialisable and pointer-shaped, and facts must be deterministic, or caching turns into flakiness. **Only what the build gave you.** Files excluded by build constraints or `GOOS`/`GOARCH` are not in `pass.Files`; they appear in `pass.IgnoredFiles`. A check that only fires in platform-specific code will not fire on a build for the other platform. **Your tool replaces the standard one.** `-vettool` names the program the go command runs instead of the toolchain's own vet binary. Checks that normally run come along only if your driver links them in, which is exactly why suites are usually built with `multichecker` and include the upstream analyzers the team still wants alongside the local ones. **Version compatibility matters.** The tool reads export data produced by the compiler in use. A driver built against a much older toolchain can fail to decode newer export data, so the analyzer binary is something that has to be rebuilt as the toolchain moves, not built once and forgotten. **Results are cached.** Because vet results are cached against the tool identity from `-V=full`, a rebuilt tool that reports an unchanged identity can serve stale results; this is worth knowing the first time a change to a check appears to have no effect. ## Choosing between them For a platform team shipping checks to many repositories, `multichecker` is almost always right: one binary, one version to roll, per-check flags for staged rollout, and shared traversal so the marginal cost of the fifth check is small. `singlechecker` is for a check that is genuinely standalone — published for others to compose into their own driver. `unitchecker` is for the case where a build system, not a human, is the only caller. ## The other thing the protocol buys you Because the go command drives it per package, a vettool inherits the build's own view of the world: the same build tags, the same module resolution, the same package set the compiler saw. A separate linter that loads packages itself has to reconstruct all of that and will disagree with the build sooner or later. That agreement is the main reason to run a custom check through `go vet` rather than as an independent binary.