README
¶
Extended "nogo" analysis
This package provides a build aspect that perform nogo analysis. This will be
automatically injected to all relevant libraries when using the default
go_binary
and go_library
rules.
It exists for several reasons.
-
The default
nogo
provided by bazel is insufficient with respect to the possibility of binary analysis. This package allows us to analyze the generated binary in addition to using the standard analyzers. -
The configuration provided in this package is much richer than the standard
nogo
JSON blob. Specifically, it allows us to exclude specific structures from the composite rules (such as the Ranges that are common with the set types). -
The bazel version of
nogo
is run directly against thego_library
andgo_binary
targets, meaning that any change to the configuration requires a rebuild from scratch (for some reason included all C++ source files in the process). Using an aspect is more efficient in this regard. -
The checks supported by this package are exported as tests, which makes it easier to reason about and plumb into the build system.
-
For uninteresting reasons, it is impossible to integrate the default
nogo
analyzer provided by bazel with internal Google tooling. To provide a consistent experience, this package allows those systems to be unified.
To use this package, import nogo_test
from defs.bzl
and add a single
dependency which is a go_binary
or go_library
rule.
Documentation
¶
Overview ¶
Package nogo implements binary analysis similar to bazel's nogo, or the unitchecker package. It exists in order to provide additional facilities for analysis, namely plumbing through the output from dumping the generated binary (to analyze actual produced code).
Index ¶
- Variables
- func WriteFindingsToBytes(findings []Finding) ([]byte, error)
- func WriteFindingsToFile(findings []Finding, filename string) error
- type AnalyzerConfig
- type AnalyzerName
- type Config
- type Finding
- func CheckPackage(config *PackageConfig, analyzers []*analysis.Analyzer, ...) (findings []Finding, factData []byte, err error)
- func CheckStdlib(config *StdlibConfig, analyzers []*analysis.Analyzer) (allFindings []Finding, facts []byte, err error)
- func ExtractFindingsFromBytes(content []byte) (findings []Finding, err error)
- func ExtractFindingsFromFile(filename string) ([]Finding, error)
- type Group
- type GroupName
- type ItemConfig
- type PackageConfig
- type StdlibConfig
Constants ¶
Variables ¶
var AllAnalyzers = []*analysis.Analyzer{ asmdecl.Analyzer, assign.Analyzer, atomic.Analyzer, bools.Analyzer, buildtag.Analyzer, cgocall.Analyzer, composite.Analyzer, copylock.Analyzer, errorsas.Analyzer, httpresponse.Analyzer, loopclosure.Analyzer, lostcancel.Analyzer, nilfunc.Analyzer, nilness.Analyzer, printf.Analyzer, shift.Analyzer, stdmethods.Analyzer, stringintconv.Analyzer, shadow.Analyzer, structtag.Analyzer, tests.Analyzer, unmarshal.Analyzer, unreachable.Analyzer, unsafeptr.Analyzer, unusedresult.Analyzer, checkescape.Analyzer, checkunsafe.Analyzer, checklocks.Analyzer, }
AllAnalyzers is a list of all available analyzers.
var ErrSkip = errors.New("skipped")
ErrSkip indicates the package should be skipped.
Functions ¶
func WriteFindingsToBytes ¶
WriteFindingsToBytes serializes findings as bytes.
func WriteFindingsToFile ¶
WriteFindingsToFile writes findings to a file.
Types ¶
type AnalyzerConfig ¶
type AnalyzerConfig map[GroupName]*ItemConfig
AnalyzerConfig is the configuration for a single analyzers.
This map is keyed by individual Group names, to allow for different configurations depending on what Group the file belongs to.
type Config ¶
type Config struct { // Prefixes defines a set of regular expressions that // are standard "prefixes", so that files can be grouped // and specific rules applied to individual groups. Groups []Group `yaml:"groups"` // Global is the global analyzer config. Global AnalyzerConfig `yaml:"global"` // Analyzers are individual analyzer configurations. The // key for each analyzer is the name of the analyzer. The // value is either a boolean (enable/disable), or a map to // the groups above. Analyzers map[AnalyzerName]AnalyzerConfig `yaml:"analyzers"` }
Config is a nogo configuration.
func (*Config) ShouldReport ¶
ShouldReport returns true iff the finding should match the Config.
type Finding ¶
type Finding struct { Category AnalyzerName Position token.Position Message string }
Finding is a single finding.
func CheckPackage ¶
func CheckPackage(config *PackageConfig, analyzers []*analysis.Analyzer, importCallback func(string) error) (findings []Finding, factData []byte, err error)
CheckPackage runs all given analyzers.
The implementation was adapted from [1], which was in turn adpated from [2]. This returns a list of matching analysis issues, or an error if the analysis could not be completed.
[1] bazelbuid/rules_go/tools/builders/nogo_main.go [2] golang.org/x/tools/go/checker/internal/checker
func CheckStdlib ¶
func CheckStdlib(config *StdlibConfig, analyzers []*analysis.Analyzer) (allFindings []Finding, facts []byte, err error)
CheckStdlib checks the standard library.
This constructs a synthetic package configuration for each library in the standard library sources, and call CheckPackage repeatedly.
Note that not all parts of the source are expected to build. We skip obvious test files, and cmd files, which should not be dependencies.
func ExtractFindingsFromBytes ¶
ExtractFindingsFromBytes loads findings from bytes.
func ExtractFindingsFromFile ¶
ExtractFindingsFromFile loads findings from a file.
type Group ¶
type Group struct { // Name is the short name for the group. Name GroupName `yaml:"name"` // Regex matches all full paths in the group. Regex string `yaml:"regex"` // Default determines the default group behavior. // // If Default is true, all Analyzers are enabled for this // group. Otherwise, Analyzers must be individually enabled // by specifying a (possible empty) ItemConfig for the group // in the AnalyzerConfig. Default bool `yaml:"default"` // contains filtered or unexported fields }
Group represents a named collection of files.
type ItemConfig ¶
type ItemConfig struct { // Exclude are analyzer exclusions. // // Exclude is a list of regular expressions. If the corresponding // Analyzer emits a Finding for which Finding.Position.String() // matches a regular expression in Exclude, the finding will not // be reported. Exclude []string `yaml:"exclude,omitempty"` // Suppress are analyzer suppressions. // // Suppress is a list of regular expressions. If the corresponding // Analyzer emits a Finding for which Finding.Message matches a regular // expression in Suppress, the finding will not be reported. Suppress []string `yaml:"suppress,omitempty"` // contains filtered or unexported fields }
ItemConfig is an (Analyzer,Group) configuration.
type PackageConfig ¶
type PackageConfig struct { ImportPath string GoFiles []string NonGoFiles []string Tags []string GOOS string GOARCH string ImportMap map[string]string FactMap map[string]string StdlibFacts string }
PackageConfig is serialized as the configuration.
This contains everything required for single package analysis.