Overview¶

Package analysis defines the interface between a modular staticanalysis and an analysis driver program.

Background¶

A static analysis is a function that inspects a package of Go code andreports a set of diagnostics (typically mistakes in the code), andperhaps produces other results as well, such as suggested refactoringsor other facts. An analysis that reports mistakes is informally called a"checker". For example, the printf checker reports mistakes infmt.Printf format strings.

A "modular" analysis is one that inspects one package at a time but cansave information from a lower-level package and use it when inspecting ahigher-level package, analogous to separate compilation in a toolchain.The printf checker is modular: when it discovers that a function such aslog.Fatalf delegates to fmt.Printf, it records this fact, and checkscalls to that function too, including calls made from another package.

By implementing a common interface, checkers from a variety of sourcescan be easily selected, incorporated, and reused in a wide range ofdriver programs including command-line tools (such as vet), text editors andIDEs, build and test systems (such as go build, Bazel, or Buck), testframeworks, code review tools, code-base indexers (such as SourceGraph),documentation viewers (such as godoc), batch pipelines for large codebases, and so on.

Analyzer¶

The primary type in the API isAnalyzer. An Analyzer staticallydescribes an analysis function: its name, documentation, flags,relationship to other analyzers, and of course, its logic.

To define an analysis, a user declares a (logically constant) variableof type Analyzer. Here is a typical example from one of the analyzers inthe go/analysis/passes/ subdirectory:

package unusedresultvar Analyzer = &analysis.Analyzer{Name: "unusedresult",Doc:  "check for unused results of calls to some functions",Run:  run,...}func run(pass *analysis.Pass) (interface{}, error) {...}

An analysis driver is a program such as vet that runs a set ofanalyses and prints the diagnostics that they report.The driver program must import the list of Analyzers it needs.Typically each Analyzer resides in a separate package.To add a new Analyzer to an existing driver, add another item to the list:

import ( "unusedresult"; "nilness"; "printf" )var analyses = []*analysis.Analyzer{unusedresult.Analyzer,nilness.Analyzer,printf.Analyzer,}

A driver may use the name, flags, and documentation to provide on-linehelp that describes the analyses it performs.The doc comment contains a brief one-line summary,optionally followed by paragraphs of explanation.

TheAnalyzer type has more fields besides those shown above:

type Analyzer struct {Name             stringDoc              stringFlags            flag.FlagSetRun              func(*Pass) (interface{}, error)RunDespiteErrors boolResultType       reflect.TypeRequires         []*AnalyzerFactTypes        []Fact}

The Flags field declares a set of named (global) flag variables thatcontrol analysis behavior. Unlike vet, analysis flags are not declareddirectly in the command line FlagSet; it is up to the driver to set theflag variables. A driver for a single analysis, a, might expose its flagf directly on the command line as -f, whereas a driver for multipleanalyses might prefix the flag name by the analysis name (-a.f) to avoidambiguity. An IDE might expose the flags through a graphical interface,and a batch pipeline might configure them from a config file.See the "findcall" analyzer for an example of flags in action.

The RunDespiteErrors flag indicates whether the analysis is equipped tohandle ill-typed code. If not, the driver will skip the analysis ifthere were parse or type errors.The optional ResultType field specifies the type of the result valuecomputed by this analysis and made available to other analyses.The Requires field specifies a list of analyses upon whichthis one depends and whose results it may access, and it constrains theorder in which a driver may run analyses.The FactTypes field is discussed in the section on Modularity.The analysis package provides a Validate function to perform basicsanity checks on an Analyzer, such as that its Requires graph isacyclic, its fact and result types are unique, and so on.

Finally, the Run field contains a function to be called by the driver toexecute the analysis on a single package. The driver passes it aninstance of the Pass type.

Pass¶

APass describes a single unit of work: the application of a particularAnalyzer to a particular package of Go code.The Pass provides information to the Analyzer's Run function about thepackage being analyzed, and provides operations to the Run function forreporting diagnostics and other information back to the driver.

type Pass struct {Fset         *token.FileSetFiles        []*ast.FileOtherFiles   []stringIgnoredFiles []stringPkg          *types.PackageTypesInfo    *types.InfoResultOf     map[*Analyzer]interface{}Report       func(Diagnostic)...}

The Fset, Files, Pkg, and TypesInfo fields provide the syntax trees,type information, and source positions for a single package of Go code.

The OtherFiles field provides the names of non-Gofiles such as assembly that are part of this package.Similarly, the IgnoredFiles field provides the names of Go and non-Gosource files that are not part of this package with the current buildconfiguration but may be part of other build configurations.The contents of these files may be read using Pass.ReadFile;see the "asmdecl" or "buildtags" analyzers for examples of loadingnon-Go files and reporting diagnostics against them.

The ResultOf field provides the results computed by the analyzersrequired by this one, as expressed in its Analyzer.Requires field. Thedriver runs the required analyzers first and makes their resultsavailable in this map. Each Analyzer must return a value of the typedescribed in its Analyzer.ResultType field.For example, the "ctrlflow" analyzer returns a *ctrlflow.CFGs, whichprovides a control-flow graph for each function in the package (seegolang.org/x/tools/go/cfg); the "inspect" analyzer returns a value thatenables other Analyzers to traverse the syntax trees of the package moreefficiently; and the "buildssa" analyzer constructs an SSA-formintermediate representation.Each of these Analyzers extends the capabilities of later Analyzerswithout adding a dependency to the core API, so an analysis tool paysonly for the extensions it needs.

The Report function emits a diagnostic, a message associated with asource position. For most analyses, diagnostics are their primaryresult.For convenience, Pass provides a helper method, Reportf, to report a newdiagnostic by formatting a string.Diagnostic is defined as:

type Diagnostic struct {Pos      token.PosCategory string // optionalMessage  string}

The optional Category field is a short identifier that classifies thekind of message when an analysis produces several kinds of diagnostic.

TheDiagnostic struct does not have a field to indicate its severitybecause opinions about the relative importance of Analyzers and theirdiagnostics vary widely among users. The design of this framework doesnot hold each Analyzer responsible for identifying the severity of itsdiagnostics. Instead, we expect that drivers will allow the user tocustomize the filtering and prioritization of diagnostics based on theproducing Analyzer and optional Category, according to the user'spreferences.

Most Analyzers inspect typed Go syntax trees, but a few, such as asmdecland buildtag, inspect the raw text of Go source files or even non-Gofiles such as assembly. To report a diagnostic against a line of araw text file, use the following sequence:

content, err := pass.ReadFile(filename)if err != nil { ... }tf := fset.AddFile(filename, -1, len(content))tf.SetLinesForContent(content)...pass.Reportf(tf.LineStart(line), "oops")

Modular analysis with Facts¶

To improve efficiency and scalability, large programs are routinelybuilt using separate compilation: units of the program are compiledseparately, and recompiled only when one of their dependencies changes;independent modules may be compiled in parallel. The same technique maybe applied to static analyses, for the same benefits. Such analyses aredescribed as "modular".

A compiler’s type checker is an example of a modular static analysis.Many other checkers we would like to apply to Go programs can beunderstood as alternative or non-standard type systems. For example,vet's printf checker infers whether a function has the "printf wrapper"type, and it applies stricter checks to calls of such functions. Inaddition, it records which functions are printf wrappers for use bylater analysis passes to identify other printf wrappers by induction.A result such as “f is a printf wrapper” that is not interesting byitself but serves as a stepping stone to an interesting result (such asa diagnostic) is called aFact.

The analysis API allows an analysis to define new types of facts, toassociate facts of these types with objects (named entities) declaredwithin the current package, or with the package as a whole, and to queryfor an existing fact of a given type associated with an object orpackage.

An Analyzer that uses facts must declare their types:

var Analyzer = &analysis.Analyzer{Name:      "printf",FactTypes: []analysis.Fact{new(isWrapper)},...}type isWrapper struct{} // => *types.Func f “is a printf wrapper”

The driver program ensures that facts for a pass’s dependencies aregenerated before analyzing the package and is responsible for propagatingfacts from one package to another, possibly across address spaces.Consequently, Facts must be serializable. The API requires that driversuse the gob encoding, an efficient, robust, self-describing binaryprotocol. A fact type may implement the GobEncoder/GobDecoder interfacesif the default encoding is unsuitable. Facts should be stateless.Because serialized facts may appear within build outputs, the gob encodingof a fact must be deterministic, to avoid spurious cache misses inbuild systems that use content-addressable caches.The driver makes a single call to the gob encoder for all factsexported by a given analysis pass, so that the topology ofshared data structures referenced by multiple facts is preserved.

The Pass type has functions to import and export facts,associated either with an object or with a package:

type Pass struct {...ExportObjectFact func(types.Object, Fact)ImportObjectFact func(types.Object, Fact) boolExportPackageFact func(fact Fact)ImportPackageFact func(*types.Package, Fact) bool}

An Analyzer may only export facts associated with the current package orits objects, though it may import facts from any package or object thatis an import dependency of the current package.

Conceptually, ExportObjectFact(obj, fact) inserts fact into a hidden map keyed bythe pair (obj, TypeOf(fact)), and the ImportObjectFact functionretrieves the entry from this map and copies its value into the variablepointed to by fact. This scheme assumes that the concrete type of factis a pointer; this assumption is checked by the Validate function.See the "printf" analyzer for an example of object facts in action.

Some driver implementations (such as those based on Bazel and Blaze) donot currently apply analyzers to packages of the standard library.Therefore, for best results, analyzer authors should not rely onanalysis facts being available for standard packages.For example, although the printf checker is capable of deducing duringanalysis of the log package that log.Printf is a printf wrapper,this fact is built in to the analyzer so that it correctly checkscalls to log.Printf even when run in a driver that does not applyit to standard packages. We would like to remove this limitation in future.

Testing an Analyzer¶

The analysistest subpackage provides utilities for testing an Analyzer.In a few lines of code, it is possible to run an analyzer on a packageof testdata files and check that it reported all the expecteddiagnostics and facts (and no more). Expectations are expressed using"// want ..." comments in the input code.

Standalone commands¶

Analyzers are provided in the form of packages that a driver program isexpected to import. The vet command imports a set of several analyzers,but users may wish to define their own analysis commands that performadditional checks. To simplify the task of creating an analysis command,either for a single analyzer or for a whole suite, we provide thesinglechecker and multichecker subpackages.

The singlechecker package provides the main function for a command thatruns one analyzer. By convention, each analyzer such asgo/analysis/passes/findcall should be accompanied by a singlechecker-basedcommand such as go/analysis/passes/findcall/cmd/findcall, defined in itsentirety as:

package mainimport ("golang.org/x/tools/go/analysis/passes/findcall""golang.org/x/tools/go/analysis/singlechecker")func main() { singlechecker.Main(findcall.Analyzer) }

A tool that provides multiple analyzers can use multichecker in asimilar way, giving it the list of Analyzers.

Index¶

• func Validate(analyzers []*Analyzer) error
• type Analyzer
• • func (a *Analyzer) String() string
• type CycleInRequiresGraphError
• • func (e *CycleInRequiresGraphError) Error() string
• type Diagnostic
• type Fact
• type Module
• type ObjectFact
• type PackageFact
• type Pass
• • func (pass *Pass) ReportRangef(rng Range, format string, args ...any)
  • func (pass *Pass) Reportf(pos token.Pos, format string, args ...any)
  • func (pass *Pass) String() string
• type Range
• type RelatedInformation
• type SuggestedFix
• type TextEdit

This section is empty.

This section is empty.