goyze

README

docs

Documentation

Overview

Generated-file exclusion: the gomatic standards commit generated trees (protobuf stubs, ANTLR parsers) but exempt them from every gate by the standard marker. Diagnostics in generated files are dropped, mirroring golangci-lint's default and `go vet`'s community convention: generated code is a build artifact — change the generator input, not the output.

Index

• Constants
• func ApplyConfig(regs []Registration, settings Settings) error
• func ApplyEdits(content []byte, edits []TextEdit) ([]byte, error)
• func GoFormat(src []byte) ([]byte, error)
• func MarshalReport(r Report) ([]byte, error)
• type AnalyzerName
• type AnalyzerSettings
• type Category
• type Diagnostic
  • func ToDiagnostic(fset *token.FileSet, reg Registration, d analysis.Diagnostic) Diagnostic
• type Driver
• type DriverResult
  • func CheckerDriver(regs []Registration, patterns []Pattern) (*token.FileSet, []DriverResult, error)
• type FileEdit
• type FileReader
• type FileWriter
• type Fix
• type FixResult
  • func ApplyFixes(read FileReader, write FileWriter, format Formatter, fixes []Fix) (FixResult, error)
• type Formatter
• type HelpURL
• type Pattern
• type Registration
  • func (r Registration) RuleID() string
  • func (r Registration) Validate() error
• type Report
  • func Run(driver Driver, regs []Registration, patterns []Pattern) (Report, error)
  • func UnmarshalReport(data []byte) (Report, error)
• type SettingName
• type SettingValue
• type Settings
• type Severity
• type TextEdit
• type Verifier
• type VerifyIssue
  • func (i VerifyIssue) String() string
• type VerifyResult
  • func CheckerVerifier(patterns []Pattern) (VerifyResult, error)
  • func (r VerifyResult) Clean() bool
  • func (r VerifyResult) Files() int

Constants

const (
	// ErrReadFile reports a source file that could not be read for fixing.
	ErrReadFile errs.Const = "cannot read file for fixing"
	// ErrFormat reports a fixed file that could not be reformatted.
	ErrFormat errs.Const = "cannot format fixed file"
	// ErrWriteFile reports a fixed file that could not be written back.
	ErrWriteFile errs.Const = "cannot write fixed file"
)

File-fix errors.

const (
	// ErrUnknownSetting reports a setting name an analyzer does not define.
	ErrUnknownSetting errs.Const = "analyzer setting is not supported"
	// ErrInvalidSettingValue reports a value that a known setting rejects when
	// parsed or validated. The setting exists; only the value is bad.
	ErrInvalidSettingValue errs.Const = "analyzer setting value is invalid"
)

Configuration errors.

const (
	// ErrOverlappingEdits reports two text edits whose byte ranges intersect.
	ErrOverlappingEdits errs.Const = "overlapping text edits"
	// ErrEditOutOfBounds reports a text edit whose range falls outside the
	// content, or whose start is greater than its end.
	ErrEditOutOfBounds errs.Const = "text edit out of bounds"
)

Sentinel errors emitted by the fix engine.

const (
	// ErrMissingName reports a Registration with no analyzer name.
	ErrMissingName errs.Const = "registration is missing a name"
	// ErrMissingAnalyzer reports a Registration with no underlying analyzer.
	ErrMissingAnalyzer errs.Const = "registration is missing an analyzer"
)

Registration validation errors.

const ErrAnalyzer errs.Const = "analyzer failed"

ErrAnalyzer reports an analyzer whose Run returned an error. The checker records a failed Run on its action (Action.Err) rather than failing Analyze — whose own error covers only setup — so without this gate a failed analyzer silently contributes zero diagnostics and the run degrades to a false pass, the same failure mode ErrLoadPackages guards against.

const ErrDriver errs.Const = "analysis driver failed"

ErrDriver reports that the underlying analysis driver failed to run.

const ErrInvalidReport errs.Const = "invalid diagnostic report"

ErrInvalidReport reports a payload that is not a well-formed diagnostic report.

const ErrLoadPackages errs.Const = "failed to load packages"

ErrLoadPackages reports that the package loader produced no usable packages: a non-empty pattern list that matched nothing, or packages carrying load, parse, or type errors. Without this gate the checker silently skips errored packages and the run degrades to a false pass with zero diagnostics — e.g. under an active go.work workspace that does not include the target module, packages.Load returns one placeholder package whose only content is a "directory prefix . does not contain modules listed in go.work" list error.

const ErrVerifyLoad errs.Const = "cannot reload packages for verification"

ErrVerifyLoad reports that the packages could not be reloaded for post-fix verification.

Functions

func ApplyConfig

func ApplyConfig(regs []Registration, settings Settings) error

ApplyConfig applies per-analyzer settings to the registrations' analyzer flags. settings is keyed by analyzer name, then by setting (flag) name. Unknown analyzer names are ignored (a config may target a larger suite than is present); an unknown setting name (ErrUnknownSetting) or an invalid value for a known setting (ErrInvalidSettingValue) is an error.

func ApplyEdits

func ApplyEdits(content []byte, edits []TextEdit) ([]byte, error)

ApplyEdits applies edits to content and returns the rewritten bytes. Edits may be supplied in any order; exact duplicates collapse to one edit, and the rest are applied as one atomic batch. It reports ErrEditOutOfBounds for a range outside content (or an inverted range) and ErrOverlappingEdits when two distinct ranges intersect. content is never mutated.

func GoFormat

func GoFormat(src []byte) ([]byte, error)

GoFormat is the default Formatter: gofmt-canonical Go source.

func MarshalReport

func MarshalReport(r Report) ([]byte, error)

MarshalReport serializes a Report to the native stickler-json encoding.

Types

type AnalyzerName

type AnalyzerName string

AnalyzerName is an analyzer's stable identifier, used as its rule-id suffix and as the key a Settings map targets.

type AnalyzerSettings

type AnalyzerSettings map[SettingName]SettingValue

AnalyzerSettings maps each of one analyzer's setting names to its raw value.

type Category

type Category string

Category is a many-to-many semantic tag carried as metadata. An analyzer may belong to several categories; categories drive filtering and documentation.

type Diagnostic

type Diagnostic struct {
	Tool     string   `json:"tool"`
	Rule     string   `json:"rule"`
	Path     string   `json:"path"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
	URL      string   `json:"url,omitempty"`
	Fixes    []Fix    `json:"fixes,omitempty"`
	Line     int      `json:"line"`
	Col      int      `json:"col"`
	EndLine  int      `json:"end_line,omitempty"`
	EndCol   int      `json:"end_col,omitempty"`
}

Diagnostic is the lean, normalized finding that every tool's output is mapped into. It is the single contract shared by the yze analyzers (producers) and the stickler runner (consumer).

func ToDiagnostic

func ToDiagnostic(fset *token.FileSet, reg Registration, d analysis.Diagnostic) Diagnostic

ToDiagnostic normalizes a go/analysis diagnostic into the lean Diagnostic schema, resolving token positions through fset and stamping the registration's rule id and help URL. Analyzer findings are always reported at error severity.

type Driver

type Driver func(regs []Registration, patterns []Pattern) (*token.FileSet, []DriverResult, error)

Driver runs the registered analyzers over the given package patterns and returns the shared FileSet plus per-analyzer findings. It is the seam between the framework and a concrete analysis backend (the default is CheckerDriver).

type DriverResult

type DriverResult struct {
	Registration Registration
	Diagnostics  []analysis.Diagnostic
}

DriverResult is one analyzer's findings from a driver run, paired with the registration that produced them so positions and metadata can be normalized.

func CheckerDriver

func CheckerDriver(regs []Registration, patterns []Pattern) (*token.FileSet, []DriverResult, error)

CheckerDriver is the default Driver: it loads the patterns' packages and runs the registered analyzers through the go/analysis checker.

type FileEdit

type FileEdit struct {
	Path  string     `json:"path"`
	Edits []TextEdit `json:"edits"`
}

FileEdit groups the TextEdits that apply to one file.

type FileReader

type FileReader func(path string) ([]byte, error)

FileReader returns the current bytes of a file.

type FileWriter

type FileWriter func(path string, data []byte) error

FileWriter persists the rewritten bytes of a file.

type Fix

type Fix struct {
	Description string     `json:"description"`
	Files       []FileEdit `json:"files"`
}

Fix is a named, mechanically-applicable change attached to a Diagnostic. It is present only when the analyzer can offer a safe, deterministic edit.

type FixResult

type FixResult struct {
	FilesChanged int
	EditsApplied int
}

FixResult summarizes what ApplyFixes changed.

func ApplyFixes

func ApplyFixes(read FileReader, write FileWriter, format Formatter, fixes []Fix) (FixResult, error)

ApplyFixes applies every fix's edits to disk, one file at a time: it merges all edits targeting a file, rewrites the file's bytes via ApplyEdits, reformats the result, and writes it back. Files are processed in sorted path order for determinism. Any read, overlap, format, or write failure aborts with that error.

type Formatter

type Formatter func(src []byte) ([]byte, error)

Formatter canonicalizes a file's bytes after edits are applied.

type HelpURL

type HelpURL string

HelpURL is the documentation URL stamped onto every Diagnostic an analyzer emits.

type Pattern

type Pattern string

Pattern is a package pattern (e.g. "./...") naming the packages an analyzer run targets.

type Registration

type Registration struct {
	Analyzer   *analysis.Analyzer
	Name       AnalyzerName
	URL        HelpURL
	Categories []Category
}

Registration declares one analyzer's identity and taxonomy to the framework.

func (Registration) RuleID

func (r Registration) RuleID() string

RuleID returns the stable rule identifier "yze/<name>" carried by every Diagnostic the analyzer emits.

func (Registration) Validate

func (r Registration) Validate() error

Validate reports the first way a Registration is not well-formed.

type Report

type Report struct {
	Diagnostics []Diagnostic `json:"diagnostics"`
}

Report is the envelope serialized by the native stickler-json format: the set of diagnostics a tool produced in one run.

func Run

func Run(driver Driver, regs []Registration, patterns []Pattern) (Report, error)

Run validates the registrations, executes them through the driver, and normalizes every finding into a Report (the native stickler-json model).

func UnmarshalReport

func UnmarshalReport(data []byte) (Report, error)

UnmarshalReport parses a native stickler-json payload, reporting ErrInvalidReport when the bytes are not a well-formed report.

type SettingName

type SettingName string

SettingName is the name of an analyzer flag a Settings map targets.

type SettingValue

type SettingValue string

SettingValue is the raw value assigned to a setting before the flag parses it.

type Settings

type Settings map[AnalyzerName]AnalyzerSettings

Settings is the per-analyzer configuration: each analyzer name maps to that analyzer's settings. It is the public shape ApplyConfig consumes.

type Severity

type Severity string

Severity ranks a Diagnostic. It is the normalized severity shared across every tool stickler runs.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
	SeverityInfo    Severity = "info"
)

The severity levels a Diagnostic may carry.

type TextEdit

type TextEdit struct {
	NewText string `json:"new_text"`
	Start   int    `json:"start"`
	End     int    `json:"end"`
}

TextEdit is a byte-range replacement within a single file's content. Start is inclusive and End is exclusive (both byte offsets); an edit with Start == End is a pure insertion of NewText.

type Verifier

type Verifier func(patterns []Pattern) (VerifyResult, error)

Verifier reloads the given package patterns — test files included — and returns every residual parse or type error. It is the seam between a fix applier and a concrete loader (the default is CheckerVerifier), so callers can verify a tree still compiles after edits without shelling out to a real build in their tests.

type VerifyIssue

type VerifyIssue struct {
	Pos string `json:"pos,omitempty"`
	Msg string `json:"msg"`
}

VerifyIssue is one parse or type error found when reloading the tree after fixes were applied. Pos is the loader's "file:line:col" position and may be empty (or "-") when the error carries no position.

func (VerifyIssue) String

func (i VerifyIssue) String() string

String renders the issue as "file:line:col: message", or just the message when the issue carries no position.

type VerifyResult

type VerifyResult struct {
	Issues []VerifyIssue
}

VerifyResult is the outcome of reloading the tree after fixes were applied.

func CheckerVerifier

func CheckerVerifier(patterns []Pattern) (VerifyResult, error)

CheckerVerifier is the default Verifier: it reloads the patterns through packages.Load with Tests set, so _test.go files — which analysis drivers do not load — are type-checked too, and collects every package error.

func (VerifyResult) Clean

func (r VerifyResult) Clean() bool

Clean reports whether the reloaded tree carried no parse or type errors.

func (VerifyResult) Files

func (r VerifyResult) Files() int

Files counts the distinct files the issues point at. Issues without a position share one "unknown" bucket, so the count is never zero while issues remain.