Repository navigation
Description
Links to salient comments:
- See proposal: go test should run analyzers specified by the workspace #82464 (comment) for current "Mk.5" design, plus addenda at proposal: go test should run analyzers specified by the workspace #82464 (comment). --adonovan, Nov 4
- Full design documented here: proposal: go test should run analyzers specified by the workspace #82464 (comment).
- for freeze exception rationale, see proposal: go test should run analyzers specified by the workspace #82464 (comment).
Background: go test today runs a fixed set of analyzers, a subset of the suite used by go vet. This set is hard-wired into the tool, and therefore these analyzers must be public and general. Yet there are a great many analyzers that users could and would write, either to enforce internal invariants of their own codebase ("housekeeping") or to help clients of their public packages use the APIs correctly, analogous to how the printf analyzer checks calls to fmt.Printf. This would allow both human users and coding agents to discover problems faster in their edit/test "inner loop", without waiting for later involvement of the CI systems that usually enforce such rules.
Proposal: We propose to change go test so that it runs not only the current subset of cmd/vet analyzers, but analyzers designated by annotations in the workspace itself. These analyzers should be fully specified by the source code of each module, so that test behaviors are deterministic, versioned, and predictable. Because Go users already expect that go test executes code in the workspace, there is no security risk in additionally running static analysis logic provided by the workspace. (By contrast, making go vet or gopls execute tests specified in this way would be insecure, since these are assumed to be static analysis tools and are thus not permitted to execute the code being studied.)
I will update this issue in due course with a full proposal, including the specification of the annotations, the proposed user documentation, a design, and a prototype implementation. In the meantime this issue will serve as a placeholder for some preparatory work and experimentation.
All new interfaces and behavior changes will be subject to the GODEBUG=vetfiles flag, until this proposal is decided one way or another.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsIncoming
- StatusShow more project fieldsIncoming
Activity
gopherbot commentedon Oct 23, 2026
Change https://go.dev/cl/853445 mentions this issue:
go/analysis: add core analysis types under GOEXPERIMENT=goanalysisadonovan commentedon Oct 26, 2026
(This revision is Mk.III.)
This note briefly describes the entire proposed change to the UX. Motivation, rationale, copious implementation details, evaluation, and open questions will be covered by the design doc (forthcoming).
We propose to change the behavior of
go test, so that, in addition to running a hard-wired subset of the analyzer suite ofcmd/vet, it runs arbitrary analyzers as defined by annotations in the source code.Consider a database named
example.com/dbthat defines two static checkers: one for various internal project housekeeping tasks and another that validates calls to its SQL query API from client code.The database maintainer adds the
goanalysis.gofile below. Each time the maintainer subsequently runsgo test, it runs theHousekeepinganalyzers over their database implementation. And each time a customer using this version of the database runs go test, it runs theQuerychecker over each customer package that transitively imports thedatabase.
In this way, the set of static analysis checks that is ordinarily run by
go testcan be deterministically extended beyond the usual subset ofgo vetsimply by adding code to your project.Annotations take the form of
//go:analyzedirective comments, to enable an analyzer. Each such directive must precede an import spec. You can only enable an analyzer to which you have import access.Annotations must appear in a file named
goanalysis.go. This restriction reduces the number of files the build system needs to parse to find all applicable annotations.The annotation file must have a build tag of the form
//go:build goanalysis. This ensures that the file is not part of the ordinary build. (We are effectively clawing back a reserved tag, albeit one unlikely to have ever been used in practice.) Annotation files thus do not create true import dependencies; no real import cycle arises from a package (fmt, say) declaring an analyzer that depends onfmtitself. However, import declarations in annotation files are visible togo mod tidy, so analyzer dependencies are versioned by go.mod, just like any other dependency.The first argument of each annotation is its scope, which denotes a set of packages relative to the current package. It must have one of these forms:
(There is no "direct importers" scope for now. Though it would be useful and easy to implement, it can be efficiently simulated with a cheap direct-import check in an analyzer using
importersscope.)The
./...and.scopes are used to enable "housekeeping" analyzers, intended to check packages within the same module. Theimportersscope is used to enable API checking in client packages, analogous to the way that theprintfanalyzer checks all uses of thefmt.Printffunction and wrappers such aslog.Printf.The second argument of each annotation is its name, which denotes an exported package-level variable. This name identifies an analyzer to the build system. When an annotation precedes an import spec, as in the example above, the package path may be omitted (for example,
//go:analyze importers Query). The example above thus enables the Housekeeping rules within the entireexample.com/db/...tree, and enables the Query analyzer on all packages that transitively import theexample.com/dbpackage.A
//go:noanalyzedirective disables an analyzer. It need not precede an import spec. This ensures that you can disable an analyzer without needing import access to it. This is particularly important for analyzers enabled withimportersscope. A//go:noanalyzeannotation may use only the.and./...scopes.The
go testcommand will run analysis in parallel with test execution, not before it (as today), and analyzer diagnostics will not prevent test execution. Diagnostics are reported in the usual way, along with a line showing the provenance of the enabling annotation, and causego testto exit non-zero. For example:No changes are proposed to
go vet,go fix,or gopls.We describe here only the user interface. The implementation strategy, in brief, is to build a
cmd/vet-like tool, analogous to the generated testmain.go, containing all applicable analyzers for the packages named in a givengo testcommand, then to execute a graph of vet actions using that tool. All analysis subproblems share the build cache, even across builds using different tools.We hope to add this feature to go1.28 under a
GODEBUG=goanalysisflag, with a full release in go1.29. Acceptance of proposal #82465 is a prerequisite. For more details (motivation, design, implementation, evaluation, and open questions), see the full design document (forthcoming).ianlancetaylor commentedon Oct 26, 2026
I appreciate the fact that this is being represented as a Go file. But when I read it I can't help but notice a set of restrictions:
//go:build goanalysis.//go:analyzecomments.It feels like there is a certain amount of syntactic ceremony that boils down to exactly the
//go:analyzecomments. And those comments are even Go code anyhow.Basically we want a mapping from a local import path to a set of (path spec, function) pairs. Should we consider possibilities other than shoehorning that into Go syntax? Such as the go.mod file.
I note in particular the the go.mod file seems particularly appropriate for the "importers"
//go:analyzeform, since the go.mod file is already all about importers.On the downside the go.mod file does not currently describe subdirectories of the module.
adonovan commentedon Oct 26, 2026
I agree the file is a strangely restricted dialect of Go. The abstract content of the file is:
go mod tidyto see the dependencies.So, (a)+(b) requires that it be a file in an arbitrary subdirectory (not go.mod), and (c) requires that
go mod tidycan see it. If we changego mod tidy, we could express the imports another way: perhaps ago.analyzeconfig file in each directory, containing a list of lines such asenable ./... pkg.Var, each of which tidy would treat like an import. This would need a new Analyzers field in thego/build.Packagestruct used bygo listetc. Is that better? I don't know.(Another notable gap in my proposal is suites: how to name a list of a dozen or a hundred analyzers.)
ianlancetaylor commentedon Oct 26, 2026
I don't see suites as an issue, because it's straightforward to write an analyzer that just calls other analyzers. I don't see a need for the annotation mechanism to introduce a new ontology. In any case that can clearly wait for later.
adonovan commentedon Oct 26, 2026
That's not really true. You could write an aggregating analyzer, but all configuration and diagnostics would be based on the wrapper name, not the aggregated elements; you'd have to declare a fact type and a result type that are products of all the elements' fact and result types; you would lose all the fine-grained parallelism; and so on. It would be fair amount of work and the result would be a bit of a mess. And to the build system it would appear as a single entity, so you wouldn't be able to switch off one nuisance analyzer from the set.
Yeah.
bystones commentedon Oct 26, 2026
Instead of having comments to declare the analyzers would it be possible to write "magic" Go code to make the structure of the comments more explicit?
This could be a little bit like writing a TestXXX function, just for analysers. It would allow to jump with "go to definition" to the goanalysis.* constant and types to learn more about that feature when you first encounter it.
adonovan commentedon Oct 27, 2026
It would certainly be possible to use pseudo-Go code for annotations. In fact, since the file is only ever parsed and cannot be type-checked or compiled (or processed by gopls's References query), it needn't be remotely valid. But as "magic" implies, that would be much less obvious than the comment notation.
The crucial difference with
func TestFoois that those declarations are actually compiled into the test; the only informationgo testneeds to extract from them statically is the function name.adonovan commentedon Oct 27, 2026
If we're changing
go/build.Package,go list, andgo mod tidy, other syntactic approaches become possible. For example, we could use a single annotation at the top of an ordinary file namedgoanalyze.go(or at the cost of more parsing, an unrestricted name). It would spell out the package path in full, and the tools would treat this as a first-class dependency edge in the metadata:The variable name part (
.Query) could be omitted in the common case when it's.Analyzer.This approach gives tools like gopls more traction on the annotations too (e.g. treating them as first-class reference), since the files are ordinary package members, unexcluded by build constraints.
To support suites requires (I think) a hybrid static/dynamic configuration scheme. For example,
example.com/internal/checks.Querywould name a single var of type *Analyzer; butstaticheck.QuickFix[*]could name an entire suite (a slice), andstaticheck.QuickFix[QF1000, QF1002]would name two elements of it. But that means the static configuration phase would only compute the upper bound of what analyzers are needed, and the dynamic phase (running the linked tool once to learn what's in it) would then allow the fine-grained resolution of suites and analyzers and the construction of the pass dependency graph. But we already need the dynamic step to learn about facts and requires edges, so this is fine.Thanks for the all the nudges. Let me respin this design.
47 remaining items
cmd/go: add GOEXPERIMENT=vetfiles flag
gopherbot commentedon Nov 16, 2026
Change https://go.dev/cl/864023 mentions this issue:
gopls: support go.vet files[-]proposal: go test should run analyzers specified by the workspace[/-][+]proposal: go test should run analyzers specified by the workspace [freeze exception][/+]adonovan commentedon Nov 17, 2026
I hereby petition for a go1.28 freeze exception. This will allow us to get this experimental feature into the hands of users six months earlier. All the implementation work is subject to the GOEXPERIMENT=vetfiles flag, so it won't affect production behavior. To make this crystal clear, I propose to cleanly separate the work into new files whose functions are only reached under
if cfg.Experiment.VetFiles { ... }conditions from the main code (see https://go.dev/cl/863561).In any case I hope to land the substance of the implementation before the freeze so that only bug fixes remain.
cc: @golang/release
gopherbot commentedon Nov 17, 2026
Change https://go.dev/cl/864830 mentions this issue:
cmd/go/internal/checks/vetfilesexperiment: housekeeping checkgopherbot commentedon Nov 17, 2026
Change https://go.dev/cl/864829 mentions this issue:
cmd/go: test: build the analysis tool in a child go command if neededgo/analysis: add API of Go analysis framework to standard library
gopherbot commentedon Nov 18, 2026
Change https://go.dev/cl/865403 mentions this issue:
{std,cmd}/vendor: update x/tools to f23c956{std,cmd}/vendor: update x/tools to f23c956
gopherbot commentedon Nov 19, 2026
Change https://go.dev/cl/863896 mentions this issue:
cmd/go: test: cache analysis results per (package, analyzer)[-]proposal: go test should run analyzers specified by the workspace [freeze exception][/-][+]proposal: go test should run analyzers specified by the workspace[/+]