rules

Documentation

Overview

Package rules implements the built-in pedagogical rules for go-idiomatic.

Every rule is a value exposing the Rule interface and also exposes an *analysis.Analyzer via Analyzer / Analyzers so it can be plugged into singlechecker, multichecker, or analysistest.Run.

Index

• Variables
• func Analyzers() map[string]*analysis.Analyzer
• type Finding
  • func Run(rule Rule, src []byte) ([]Finding, error)
• type Fix
• type Rule
  • func All() []Rule
• type Severity
  • func (s Severity) String() string
• type TextEdit

Variables

var Analyzer = newAnalyzer("goidiomatic", "pedagogical Go-idiom checks beyond golangci-lint", All())

Analyzer wraps every built-in rule as a single Analyzer suitable for singlechecker / multichecker.

Functions

func Analyzers

func Analyzers() map[string]*analysis.Analyzer

Analyzers returns one analyzer per rule, keyed by rule ID. Useful when a caller wants to surface findings per-rule or run analysistest on a single rule.

Types

type Finding

type Finding struct {
	RuleID   string
	Message  string
	Pos      token.Position
	Severity Severity
	Fix      *Fix
}

Finding is one hit on a Rule.

func Run

func Run(rule Rule, src []byte) ([]Finding, error)

Run parses src as a single Go file in a synthetic package and runs the given rule against it. It is a test-oriented helper that does not require module resolution or GOPATH.

type Fix

type Fix struct {
	Description string
	TextEdits   []TextEdit
}

Fix is an optional suggested edit attached to a Finding.

type Rule

type Rule interface {
	ID() string
	Name() string
	Description() string
	Severity() Severity
	Check(pass *analysis.Pass) ([]Finding, error)
}

Rule is a single pedagogical check.

var AnyOverEmptyInterface Rule = anyOverEmptyInterface{}

AnyOverEmptyInterface flags uses of interface{} and suggests any, but only when the build context's language version is Go 1.18 or newer. On older targets the suggestion would be a compile error, so the rule stays silent.

var ContextFirstArg Rule = contextFirstArg{}

ContextFirstArg flags functions that take context.Context as any parameter other than the first. The Go convention is that Context is always the first parameter, named ctx.

var ErrorsIsAs Rule = errorsIsAs{}

ErrorsIsAs flags two common anti-patterns:

1. comparing err.Error() to a literal string
2. comparing an error value to a sentinel with ==

Both should use errors.Is (or errors.As for type switches) so wrapped errors still match. The check is structural, augmented with type info when it is available.

var NoSleepForCoordination Rule = noSleepForCoordination{}

NoSleepForCoordination flags time.Sleep calls inside a function that also uses a channel operation or a context.Context. Sleeping as a way to wait for "the other thing" to happen is almost always a race.

var PreferRangeInt Rule = preferRangeInt{}

PreferRangeInt flags classic indexed loops that could be rewritten with range, for example for i := 0; i < len(xs); i++. It ignores countdowns and steps other than i++.

func All

func All() []Rule

All returns every built-in rule in a stable order.

type Severity

type Severity int

Severity grades how strong a finding is.

const (
	// Info is a stylistic nudge.
	Info Severity = iota + 1
	// Warn is a likely issue worth addressing.
	Warn
	// Error is almost certainly a bug or anti-pattern.
	Error
)

Severity levels, ordered from weakest to strongest.

func (Severity) String

func (s Severity) String() string

String returns the human label for a severity.

type TextEdit

type TextEdit struct {
	Start, End token.Position
	NewText    string
}

TextEdit is a single replacement in source.