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 the go_library and go_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.

Expand ▾ Collapse ▴

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

    Constants

    This section is empty.

    Variables

      AllAnalyzers is a list of all available analyzers.

      View Source
      var ErrSkip = errors.New("skipped")

        ErrSkip indicates the package should be skipped.

        Functions

        func WriteFindingsToBytes

        func WriteFindingsToBytes(findings []Finding) ([]byte, error)

          WriteFindingsToBytes serializes findings as bytes.

          func WriteFindingsToFile

          func WriteFindingsToFile(findings []Finding, filename string) error

            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 AnalyzerName

              type AnalyzerName string

                AnalyzerName is a named analyzer.

                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) Compile

                  func (c *Config) Compile() error

                    Compile compiles a configuration to make it useable.

                    func (*Config) Merge

                    func (c *Config) Merge(other *Config)

                      Merge merges two configurations.

                      func (*Config) ShouldReport

                      func (c *Config) ShouldReport(finding Finding) bool

                        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

                              func ExtractFindingsFromBytes(content []byte) (findings []Finding, err error)

                                ExtractFindingsFromBytes loads findings from bytes.

                                func ExtractFindingsFromFile

                                func ExtractFindingsFromFile(filename string) ([]Finding, error)

                                  ExtractFindingsFromFile loads findings from a file.

                                  func (*Finding) String

                                  func (f *Finding) String() string

                                    String implements fmt.Stringer.String.

                                    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 GroupName

                                      type GroupName string

                                        GroupName is a named group.

                                        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.

                                            type StdlibConfig

                                            type StdlibConfig struct {
                                            	Srcs   []string
                                            	GOOS   string
                                            	GOARCH string
                                            	Tags   []string
                                            }

                                              StdlibConfig is serialized as the configuration.

                                              This contains everything required for stdlib analysis.

                                              Directories

                                              Path Synopsis
                                              Binary check is the nogo entrypoint.
                                              Binary check is the nogo entrypoint.
                                              Binary check is the nogo entrypoint.
                                              Binary check is the nogo entrypoint.