Skip to content

proposal: go test should run analyzers specified by the workspace #82464

Open
1 of 1 issue completed
Open

Description

@adonovan

Links to salient comments:

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.

Activity

  1. added this to the Proposal milestone on Oct 23, 2026
  2. added
    AnalysisIssues related to static analysis (vet, x/tools/go/analysis)
    on Oct 23, 2026
  3. moved this to Hold in Proposalson Oct 23, 2026
  4. gopherbot commented on Oct 23, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/853445 mentions this issue: go/analysis: add core analysis types under GOEXPERIMENT=goanalysis

  5. adonovan commented on Oct 26, 2026

    @adonovan
    MemberAuthor

    (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 of cmd/vet, it runs arbitrary analyzers as defined by annotations in the source code.

    Consider a database named example.com/db that 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.go file below. Each time the maintainer subsequently runs go test, it runs the Housekeeping analyzers over their database implementation. And each time a customer using this version of the database runs go test, it runs the Query checker over each customer package that transitively imports the
    database.

    //go:build goanalysis
    
    package db
    
    import (
    	//go:analyze ./...     example.com/internal/check.Housekeeping
    	//go:analyze importers example.com/internal/check.Query
    	_ "example.com/internal/check"
    )

    In this way, the set of static analysis checks that is ordinarily run by go test can be deterministically extended beyond the usual subset of go vet simply by adding code to your project.

    Annotations take the form of //go:analyze directive 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 on fmt itself. However, import declarations in annotation files are visible to go 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:

    	.    		this package
    	./...		all packages of this module beneath this directory
    	importers	all transitive importers of this package
    

    (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 importers scope.)

    The ./... and . scopes are used to enable "housekeeping" analyzers, intended to check packages within the same module. The importers scope is used to enable API checking in client packages, analogous to the way that the printf analyzer checks all uses of the fmt.Printf function and wrappers such as log.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 entire example.com/db/... tree, and enables the Query analyzer on all packages that transitively import the example.com/db package.

    A //go:noanalyze directive 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 with importers scope. A //go:noanalyze annotation may use only the . and ./... scopes.

    The go test command 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 cause go test to exit non-zero. For example:

    $ go test ./myapp
    myapp/myapp.go:123: insecure SQL query
    example.com/db/goanalysis.go:7:  (from example.com/db/internal/check.Query)
    

    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 given go test command, 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=goanalysis flag, 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).

  6. ianlancetaylor commented on Oct 26, 2026

    @ianlancetaylor
    Contributor

    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:

    • The file must be named goanalysis.go.
    • The file must contain the line //go:build goanalysis.
    • The file must have one or more imports (or it is useless).
    • Each import is expected to be annotated with one or more //go:analyze comments.
    • The import comments restate the import path.
    • Any other code in the file is useless in practice.

    It feels like there is a certain amount of syntactic ceremony that boils down to exactly the //go:analyze comments. 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:analyze form, 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.

  7. adonovan commented on Oct 26, 2026

    @adonovan
    MemberAuthor

    I agree the file is a strangely restricted dialect of Go. The abstract content of the file is:

    • a. the current package, which needn't be the module root. This is important for configuration autonomy of subtrees in large modules.
    • b. a relation over (package, analyzer) pairs, expressed compactly relative to (a) in terms of the three scope operators and negation.
    • c. a valid import of the analyzer-providing package. This is critical for "access control" and for go mod tidy to 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 tidy can see it. If we change go mod tidy, we could express the imports another way: perhaps a go.analyze config file in each directory, containing a list of lines such as enable ./... pkg.Var, each of which tidy would treat like an import. This would need a new Analyzers field in the go/build.Package struct used by go list etc. 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.)

  8. ianlancetaylor commented on Oct 26, 2026

    @ianlancetaylor
    Contributor

    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.

  9. adonovan commented on Oct 26, 2026

    @adonovan
    MemberAuthor

    it's straightforward to write an analyzer that just calls other analyzers.

    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.

    In any case that can clearly wait for later.

    Yeah.

  10. bystones commented on Oct 26, 2026

    @bystones
    Contributor

    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?

    //go:build goanalysis
    
    package db
    
    import (
    	"goanalysis"
    
    	"example.com/db/internal/check"
    )
    
    var Analysers = []goanalysis.Declaration {
    		{
    			Scope: goanalysis.ScopePackage,
    			Analyser: check.Housekeeping,
    		},
    		{
    			Scope: goanalysis.ScopeImporters,
    			Analyser: check.Query,
    		},
    }

    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.

  11. adonovan commented on Oct 27, 2026

    @adonovan
    MemberAuthor

    would it be possible to write "magic" Go code

    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 TestFoo is that those declarations are actually compiled into the test; the only information go test needs to extract from them statically is the function name.

  12. adonovan commented on Oct 27, 2026

    @adonovan
    MemberAuthor

    If we're changing go/build.Package, go list, and go mod tidy, other syntactic approaches become possible. For example, we could use a single annotation at the top of an ordinary file named goanalyze.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:

    //go:analyze importers example.com/internal/checks.Query
    //go:noanalyze ./... leftpad.com/check.Nuisance
    package db

    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.Query would name a single var of type *Analyzer; but staticheck.QuickFix[*] could name an entire suite (a slice), and staticheck.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.

  13. 47 remaining items

  14. gopherbot commented on Nov 16, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/864023 mentions this issue: gopls: support go.vet files

  15. changed the title [-]proposal: go test should run analyzers specified by the workspace[/-] [+]proposal: go test should run analyzers specified by the workspace [freeze exception][/+] on Nov 17, 2026
  16. adonovan commented on Nov 17, 2026

    @adonovan
    MemberAuthor

    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

  17. modified the milestones: Proposal, Go1.28 on Nov 17, 2026
  18. gopherbot commented on Nov 17, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/864830 mentions this issue: cmd/go/internal/checks/vetfilesexperiment: housekeeping check

  19. gopherbot commented on Nov 17, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/864829 mentions this issue: cmd/go: test: build the analysis tool in a child go command if needed

  20. gopherbot commented on Nov 18, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/865403 mentions this issue: {std,cmd}/vendor: update x/tools to f23c956

  21. gopherbot commented on Nov 19, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/863896 mentions this issue: cmd/go: test: cache analysis results per (package, analyzer)

  22. changed the title [-]proposal: go test should run analyzers specified by the workspace [freeze exception][/-] [+]proposal: go test should run analyzers specified by the workspace[/+] on Nov 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

AnalysisIssues related to static analysis (vet, x/tools/go/analysis)Proposal

Type

No type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions