checker

package
v0.0.0-...-d8a8f93 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 2, 2019 License: Apache-2.0 Imports: 7 Imported by: 0

README

Checker

Checker is an extensible go-file analyzer. It processes source codes in the following steps:

  • Take a list of directory paths and recursively scan for go files
  • Build abstract syntax trees for the relevant go files
  • Apply Rule-based analysis
  • Generate a report

The design is pluggable, as different applications can implement different Rules for different analytic requirements.

Check

The Check() function is the main entry point, which takes a list of file path (if empty, current directory is implied), a RulesFactory, a Whitelist , and a Report.

The RulesFactory and the Whitelist are extension points which allow the caller (i.e. application) to configure what Rules should apply to what files.

func Check(paths []string, factory RulesFactory, whitelist *Whitelist, report *Report) error
Rule

Application implements the Rule interface, and provides the actual logic to produce diagnostic information, using an abstract syntax tree built from a go file. Each Rule is expected to run one specific check (potentially using information from external systems) against the given syntax tree, and multiple Rules can be implemented for different checks against the same tree (i.e. go file). This allows custom semantic analysis.

type Rule interface {
	// GetID returns ID of the rule in string
	GetID() string
	// Check conditions using the given node and produce report if needed.
	Check(aNode ast.Node, fs *token.FileSet, lrp *Report)
}
RulesFactory

Application implements the RulesFactory interface to provide a mapping from file paths to their corresponding rules. This allows fine grained control over what Rules should apply to what files. For example, “_test.go” files can use a different set of rules from regular go files, or “mixer” files can have different rules from “pilot” files.

type RulesFactory interface {
	// GetRules returns a list of rules used to check against the files.
	GetRules(absp string, info os.FileInfo) []Rule
}
Whitelist

In addition to RulesFactory, application can provide a Whitelist to opt out selected files from certain rules. This allows temporary rule disablement until the file is updated to comply with the rules, or an exception mechanism to allow approved files break some rules.

A Whitelist object is backed by a map from string to a string slice, where the keys are file paths, and the values are slices of rule IDs, as identified by return value of the GetID() method, in the Rule interface.

func NewWhitelist(ruleWhitelist map[string][]string) *Whitelist {
	return Whitelist{ruleWhitelist: ruleWhitelist}
}
Report

Report is a utility used to accumulate rule diagnostic information for final consumption. When a Rule runs a check, it can add information to the Report using the AddItem() function to provide file location information, and a diagnostic message.

After all checks are done, the Items() function can be used to retrieve the formatted text based report as a string slice.

func (lr *Report) AddItem(pos token.Position, is string, msg string)

func (lt *Report) Items() []string

Example Use Cases

  • The Checker can go through all Test* functions in _test.go files, and create a warning if a test is being skipped without having a github issue assigned (i.e. in the testing.T.skip() message). This allows us to properly track all skipped tests, and make sure they are restored when the underlying issues are fixed.

  • The Checker can go through all _test.go files and validate if the test is being run in CI. It can then find all the dead tests for developers to either remove, or to hook them back up in the automatic tests.

Information like these are valuable but are currently opaque to us (even codecov report cannot reveal these). The extensible Checker design opens up opportunities to add more code analysis, so we have better insight into the Istio code base and maintain better code health.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check

func Check(paths []string, factory RulesFactory, whitelist *Whitelist, report *Report) error

Check checks the list of files, and write to the given Report.

Types

type FileVisitor

type FileVisitor struct {
	// contains filtered or unexported fields
}

FileVisitor visits the go file syntax tree and applies the given rules.

func (*FileVisitor) Visit

func (fv *FileVisitor) Visit(node ast.Node) ast.Visitor

Visit checks each node and runs the applicable checks.

type Report

type Report struct {
	// contains filtered or unexported fields
}

Report populates lint report.

func NewLintReport

func NewLintReport() *Report

NewLintReport creates and returns a Report object.

func (*Report) AddItem

func (lr *Report) AddItem(pos token.Position, id string, msg string)

AddItem creates a new lint error report.

func (*Report) AddString

func (lr *Report) AddString(msg string)

AddString creates a new string line in report.

func (*Report) Items

func (lr *Report) Items() []string

Items returns formatted report as a string slice.

type Rule

type Rule interface {
	// GetID returns ID of the rule in string, ID is equal to the file name of that rule.
	GetID() string
	// Check verifies if aNode passes rule check. If verification fails lrp creates a report.
	Check(aNode ast.Node, fs *token.FileSet, lrp *Report)
}

Rule is interface for defining lint rules.

type RulesFactory

type RulesFactory interface {
	// GetRules returns a list of rules used to check against the files.
	GetRules(absp string, info os.FileInfo) []Rule
}

RulesFactory is interface to get Rules from a file path.

type Whitelist

type Whitelist struct {
	// contains filtered or unexported fields
}

Whitelist determines if rules are whitelisted for the given paths.

func NewWhitelist

func NewWhitelist(ruleWhitelist map[string][]string) *Whitelist

NewWhitelist creates and returns a Whitelist object.

func (*Whitelist) Apply

func (wl *Whitelist) Apply(path string, rule Rule) bool

Apply returns true if the given rule is whitelisted for the given path.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL