ruleguard

Documentation

Index

• type Engine
  • func NewEngine() *Engine
  • func (e *Engine) InferBuildContext()
  • func (e *Engine) Load(ctx *LoadContext, filename string, r io.Reader) error
  • func (e *Engine) LoadFromIR(ctx *LoadContext, filename string, f *ir.File) error
  • func (e *Engine) LoadedGroups() []GoRuleGroup
  • func (e *Engine) Run(ctx *RunContext, f *ast.File) error
• type GoRuleGroup
• type GoRuleInfo
• type GoVersion
  • func ParseGoVersion(version string) (GoVersion, error)
  • func (ver GoVersion) IsAny() bool
• type ImportError
  • func (e *ImportError) Error() string
  • func (e *ImportError) Unwrap() error
• type LoadContext
• type ReportData
• type RunContext
• type RunnerState
  • func NewRunnerState(e *Engine) *RunnerState
  • func (state *RunnerState) Reset()
• type Suggestion

Types

type Engine

type Engine struct {

	// BuildContext can be used as an override for build.Default context.
	// Used during the Go packages resolving.
	//
	// Use Engine.InferBuildContext() to create a sensible default
	// for this field that is better than build.Default.
	// We're not using this by default to avoid the excessive work
	// if you already have a properly initialized build.Context object.
	//
	// nil will result in build.Default usage.
	BuildContext *build.Context
	// contains filtered or unexported fields
}

Engine is the main ruleguard package API object.

First, load some ruleguard files with Load() to build a rule set. Then use Run() to execute the rules.

It's advised to have only 1 engine per application as it does a lot of caching. The Run() method is synchronized, so it can be used concurrently.

An Engine must be created with NewEngine() function.

func NewEngine

func NewEngine() *Engine

NewEngine creates an engine with empty rule set.

func (*Engine) InferBuildContext

func (e *Engine) InferBuildContext()

func (*Engine) Load

func (e *Engine) Load(ctx *LoadContext, filename string, r io.Reader) error

Load reads a ruleguard file from r and adds it to the engine rule set.

Load() is not thread-safe, especially if used concurrently with Run() method. It's advised to Load() all ruleguard files under a critical section (like sync.Once) and then use Run() to execute all of them.

func (*Engine) LoadFromIR

func (e *Engine) LoadFromIR(ctx *LoadContext, filename string, f *ir.File) error

LoadFromIR is like Load(), but it takes already parsed IR file as an input.

This method can be useful if you're trying to embed a precompiled rules file into your binary.

func (*Engine) LoadedGroups

func (e *Engine) LoadedGroups() []GoRuleGroup

LoadedGroups returns information about all currently loaded rule groups.

func (*Engine) Run

func (e *Engine) Run(ctx *RunContext, f *ast.File) error

Run executes all loaded rules on a given file. Matched rules invoke `RunContext.Report()` method.

Run() is thread-safe, unless used in parallel with Load(), which modifies the engine state.

type GoRuleGroup

type GoRuleGroup struct {
	// Name is a function name associated with this rule group.
	Name string

	// Pos is a location where this rule group was defined.
	Pos token.Position

	// Line is a source code line number inside associated file.
	// A pair of Filename:Line form a conventional location string.
	Line int

	// Filename is a file that defined this rule group.
	Filename string

	// DocTags contains a list of keys from the `gorules:tags` comment.
	DocTags []string

	// DocSummary is a short one sentence description.
	// Filled from the `doc:summary` pragma content.
	DocSummary string

	// DocBefore is a code snippet of code that will violate rule.
	// Filled from the `doc:before` pragma content.
	DocBefore string

	// DocAfter is a code snippet of fixed code that complies to the rule.
	// Filled from the `doc:after` pragma content.
	DocAfter string

	// DocNote is an optional caution message or advice.
	// Usually, it's used to reference some external resource, like
	// issue on the GitHub.
	// Filled from the `doc:note` pragma content.
	DocNote string
}

type GoRuleInfo

type GoRuleInfo struct {
	// Line is a line inside a file that defined this rule.
	Line int

	// Group is a function that contains this rule.
	Group *GoRuleGroup
}

type GoVersion

type GoVersion struct {
	Major int
	Minor int
}

func ParseGoVersion

func ParseGoVersion(version string) (GoVersion, error)

func (GoVersion) IsAny

func (ver GoVersion) IsAny() bool

type ImportError

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

ImportError is returned when a ruleguard file references a package that cannot be imported.

func (*ImportError) Error

func (e *ImportError) Error() string

func (*ImportError) Unwrap

func (e *ImportError) Unwrap() error

type LoadContext

type LoadContext struct {
	DebugFunc    string
	DebugImports bool
	DebugPrint   func(string)

	// GroupFilter is called for every rule group being parsed.
	// If function returns false, that group will not be included
	// in the resulting rules set.
	// Nil filter accepts all rule groups.
	GroupFilter func(*GoRuleGroup) bool

	Fset *token.FileSet
}

type ReportData

type ReportData struct {
	RuleInfo   GoRuleInfo
	Node       ast.Node
	Message    string
	Suggestion *Suggestion

	Func *ast.FuncDecl
}

type RunContext

type RunContext struct {
	Debug        string
	DebugImports bool
	DebugPrint   func(string)

	Types *types.Info
	Sizes types.Sizes
	Fset  *token.FileSet
	Pkg   *types.Package

	// Report is a function that is called for every successful ruleguard match.
	// The pointer to ReportData is reused, it should not be kept.
	// If you want to keep it after Report() returns, make a copy.
	Report func(*ReportData)

	GoVersion GoVersion

	// TruncateLen is a length threshold (in bytes) for interpolated vars in Report() templates.
	//
	// Truncation removes the part of the string in the middle and replaces it with <...>
	// so it meets the max length constraint.
	//
	// The default value is 60 (implied if value is 0).
	//
	// Note that this value is ignored for Suggest templates.
	// Ruleguard doesn't truncate suggested replacement candidates.
	TruncateLen int

	// State is an object that contains reusable resources needed for the rules to be executed.
	//
	// If nil, a new state will be allocated.
	//
	// The State object access is not synchronized.
	// State should not be shared between multiple goroutines.
	// There are 3 patterns that are safe:
	// 1. For single-threaded programs, you can use a single state.
	// 2. For controlled concurrency with workers, you can use a per-worker state.
	// 3. For uncontrolled concurrency you can use a sync.Pool of states.
	//
	// Reusing the state properly can increase the performance significantly.
	State *RunnerState
}

type RunnerState

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

func NewRunnerState

func NewRunnerState(e *Engine) *RunnerState

NewRunnerState creates a state object that can be used with RunContext.

func (*RunnerState) Reset

func (state *RunnerState) Reset()

type Suggestion

type Suggestion struct {
	From        token.Pos
	To          token.Pos
	Replacement []byte
}