goyze

README

go-yze

The framework library for the yze analyzer family — the shared scaffolding that makes each gomatic/yze-<group>-<name> analyzer repo cheap and uniform to maintain.

go-yze owns the contract between the analyzers and the stickler runner:

• the normalized Diagnostic / Fix / TextEdit schema (the lean shape every tool's output is normalized into),
• analyzer Registration (identity + the group/category taxonomy),
• the Reporter that turns a go/analysis finding into a Diagnostic carrying a stable rule id, help URL, and an optional mechanical fix,
• Main, the one-line singlechecker entry point each analyzer's cmd calls,
• ApplyFixes, the single shared engine that applies TextEdits and re-gofmts (powering yze --fix and stickler --fix),
• the analysistest harness every analyzer's tests reuse.

It is a pure library: CLI-agnostic and dependency-light (go-error for sentinel errors, x/tools for go/analysis, testify for tests).

Documentation

Index

• Constants
• func ApplyEdits(content []byte, edits []TextEdit) ([]byte, error)
• func GoFormat(src []byte) ([]byte, error)
• func MarshalReport(r Report) ([]byte, error)
• type Category
• type Diagnostic
  • func ToDiagnostic(fset *token.FileSet, reg Registration, d analysis.Diagnostic) Diagnostic
• type Driver
• type DriverResult
  • func CheckerDriver(regs []Registration, patterns []string) (*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 Group
• type Registration
  • func (r Registration) RuleID() string
  • func (r Registration) Validate() error
• type Report
  • func Run(driver Driver, regs []Registration, patterns []string) (Report, error)
  • func UnmarshalReport(data []byte) (Report, error)
• type Severity
• type TextEdit

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 (
	// 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"
	// ErrMissingGroup reports a Registration with no group.
	ErrMissingGroup errs.Const = "registration is missing a group"
	// ErrMissingAnalyzer reports a Registration with no underlying analyzer.
	ErrMissingAnalyzer errs.Const = "registration is missing an analyzer"
)

Registration validation errors.

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.

Functions

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; they are applied as one atomic batch. It reports ErrEditOutOfBounds for a range outside content (or an inverted range) and ErrOverlappingEdits when two 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 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 and are deliberately decoupled from Group.

type Diagnostic

type Diagnostic struct {
	Tool     string   `json:"tool"`
	Rule     string   `json:"rule"`
	Path     string   `json:"path"`
	Line     int      `json:"line"`
	Col      int      `json:"col"`
	EndLine  int      `json:"end_line,omitempty"`
	EndCol   int      `json:"end_col,omitempty"`
	Severity Severity `json:"severity"`
	Message  string   `json:"message"`
	Fixes    []Fix    `json:"fixes,omitempty"`
	URL      string   `json:"url,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 []string) (*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 []string) (*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 Group

type Group string

Group is the single, stable name segment shared by every analyzer in a repo family — the <group> in a yze-<group>-<name> repo. It is the organizing axis embedded in the module path (the default axis is the language/target).

type Registration

type Registration struct {
	Name       string
	Group      Group
	Categories []Category
	URL        string
	Analyzer   *analysis.Analyzer
}

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/<group>/<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 []string) (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 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 {
	Start   int    `json:"start"`
	End     int    `json:"end"`
	NewText string `json:"new_text"`
}

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.