Documentation
¶
Overview ¶
Package yze is the analyzer catalog for the yze family: it aggregates every yze-<name> analyzer's registration and filters the set by category. The cmd/yze binary drives this catalog through the go-yze runner.
Package yze's source-analyzer catalog: which non-Go languages the suite judges, and how each decides which files it reads.
Index ¶
- Constants
- func ApplySourceConfig(analyzers []SourceAnalyzer, settings goyze.Settings) error
- func Catalog(regs []goyze.Registration, sourceAnalyzers []SourceAnalyzer) []goyze.RuleID
- func Emit(w io.Writer, format Format, report goyze.Report) error
- func EmitRules(w io.Writer, format RuleFormat, rules []Rule) error
- func Filter(regs []goyze.Registration, categories []goyze.Category) []goyze.Registration
- func GitCheckIgnore(files []string) (map[string]bool, error)
- func HasGoModule(read goyze.FileReader, walk WalkDir, roots []WalkRoot) bool
- func LoadConfig(read goyze.FileReader, path ConfigPath) (goyze.Settings, error)
- func Registrations() []goyze.Registration
- func RunSource(read goyze.FileReader, walk WalkDir, ignore CheckIgnore, ...) (goyze.Report, error)
- type CheckIgnore
- type ConfigPath
- type Format
- type Rule
- type RuleFormat
- type SourceAnalyzer
- type WalkDir
- type WalkRoot
Constants ¶
const ( // ErrConfig reports a yze configuration file that cannot be read or parsed. ErrConfig errs.Const = "cannot load yze config" // ErrSourceSetting reports a config setting supplied for a bundled SOURCE // analyzer, none of which defines any settings. The name said SQL until the // suite grew markdown, shell and workflow analyzers, and an error naming the // wrong language is an error an author reads twice before believing. ErrSourceSetting errs.Const = "source analyzer settings are not supported" )
Configuration errors.
const ( // ErrSourceWalk reports that walking a root for source files failed. ErrSourceWalk errs.Const = "cannot walk for source files" // ErrSourceRead reports that a source file could not be read. ErrSourceRead errs.Const = "cannot read source file" // ErrNoSuchRoot reports a filesystem pattern naming a directory that is not // there. A typo used to walk nothing and report a clean run. ErrNoSuchRoot errs.Const = "no such directory to analyze" )
Source run errors.
const ErrUnknownFormat errs.Const = "unknown output format"
ErrUnknownFormat reports an output format the aggregator does not support.
const ErrUnknownRuleFormat errs.Const = "unknown rule-export format"
ErrUnknownRuleFormat reports a rule-export format the aggregator does not support.
Variables ¶
This section is empty.
Functions ¶
func ApplySourceConfig ¶
func ApplySourceConfig(analyzers []SourceAnalyzer, settings goyze.Settings) error
ApplySourceConfig checks settings against the suite's source analyzers, mirroring goyze.ApplyConfig's semantics: a rule id it does not have is left to goyze.CheckAnalyzerNames, but a setting supplied for one it does have must be one that analyzer defines — and the source analyzers define none, so any setting targeting one is ErrSourceSetting rather than a silent no-op.
func Catalog ¶ added in v0.35.0
func Catalog(regs []goyze.Registration, sourceAnalyzers []SourceAnalyzer) []goyze.RuleID
Catalog is every RULE ID this binary can run: the Go registrations and the bundled source analyzers, in one list. It is what makes a name check total — a config key that matches nothing here matches nothing anywhere, so the only remaining explanation is a misspelling.
func EmitRules ¶
func EmitRules(w io.Writer, format RuleFormat, rules []Rule) error
EmitRules writes the rule catalog to w in the named format.
func Filter ¶
func Filter(regs []goyze.Registration, categories []goyze.Category) []goyze.Registration
Filter selects the registrations matching the given categories. An empty category set matches every analyzer; otherwise a registration matches when it carries any of the categories.
func GitCheckIgnore ¶
GitCheckIgnore is the default CheckIgnore: one `git check-ignore` over all files at once, run from the process working directory — which during a lint pass is inside the repository — reading the ignored subset from its NUL-delimited output.
func HasGoModule ¶ added in v0.35.0
func HasGoModule(read goyze.FileReader, walk WalkDir, roots []WalkRoot) bool
HasGoModule reports whether a root the run was pointed at has Go for the Go driver to analyze: a go.mod at the root or above it, AND a .go file inside the root itself.
It is the discriminator between "this tree has no Go" and "this tree's Go does not load", which the Go driver reports identically and which mean opposite things: the first is a docs repository the source analyzers still have work in, the second is a module that must not be allowed to pass by failing to compile.
BOTH halves are needed, and each rules out a different way of being wrong.
The module lookup walks to the filesystem root rather than stopping at a repository boundary, because a nested module's package can be analyzed from a directory that holds no go.mod of its own. That walk can also leave the tree being judged entirely, and then the answer it gives is about somebody else's module: a directory of markdown sitting anywhere inside a Go repository was declared to have Go, and the run died on `no packages matched patterns: ./...` instead of reporting the markdown. This corpus found it -- every source analyzer's case is a directory with no Go in it, and the corpus itself is a Go module.
Requiring a .go file INSIDE the root is what closes that, and it does not weaken the second half: a tree that holds Go and fails to load still runs and still fails. Loose .go files with no module anywhere are still skipped, by the first half, because the driver cannot load those either.
func LoadConfig ¶
func LoadConfig(read goyze.FileReader, path ConfigPath) (goyze.Settings, error)
func Registrations ¶
func Registrations() []goyze.Registration
Registrations returns every analyzer in the suite, in stable rule-id order, each carrying the test-file scope its rule warrants.
func RunSource ¶
func RunSource( read goyze.FileReader, walk WalkDir, ignore CheckIgnore, analyzers []SourceAnalyzer, roots []WalkRoot, ) (goyze.Report, error)
RunSource finds every file under the roots, drops the ones git ignores (an ignored file is not the repository's owned surface — the same policy the Go-package side applies, failing open when git cannot answer), and runs each analyzer over the files it claims, returning the merged diagnostics. A file no analyzer claims is never even read. A walk or read failure aborts the run.
Types ¶
type CheckIgnore ¶
CheckIgnore reports which of the given files git ignores. It is the seam a test replaces to drive the filter without a real repository; the command wires GitCheckIgnore.
type ConfigPath ¶
type ConfigPath string
LoadConfig reads and parses a yze config file into per-analyzer settings keyed by analyzer name then setting name, ready for go-yze's ApplyConfig. The reader is injected so callers control filesystem access. ConfigPath is the path to a yze per-analyzer config file.
type Rule ¶
type Rule struct {
ID goyze.RuleID
Name string
Doc string
URL string
Precision goyze.Precision
Categories []goyze.Category
}
Rule is one catalog entry: the language-neutral metadata a rule export carries. Both the Go analyzer registrations (via GoRules) and the source analyzers (via SQLRules) reduce to this shape, so the exported catalog always describes the whole suite — every rule id a diagnostic can carry has a catalog entry.
func CatalogRules ¶
func CatalogRules(regs []goyze.Registration, analyzers []SourceAnalyzer) []Rule
CatalogRules merges the Go and source analyzers' rules into the one catalog `--emit-rules` exports, sorted by rule id so the export order is deterministic regardless of which language contributed an entry.
func GoRules ¶
func GoRules(regs []goyze.Registration) []Rule
GoRules maps the Go analyzer registrations onto their catalog rules.
func SQLRules ¶
func SQLRules(analyzers []SourceAnalyzer) []Rule
SQLRules maps the source analyzers onto their catalog rules, under the same "yze/<name>" rule-id scheme their diagnostics carry.
type RuleFormat ¶
type RuleFormat string
RuleFormat names a way the suite's rule catalog is exported. The catalog is built from catalog metadata (id, name, doc, url, categories) — never from analyzer logic — so it carries no per-analyzer machinery.
const ( // RuleFormatSARIF exports a SARIF 2.1.0 tool.driver.rules catalog for code // scanning / editor rule registration. RuleFormatSARIF RuleFormat = "sarif" // RuleFormatGrit exports a GritQL-style markdown registry. The analyzers are // AST-based, not pattern rewrites, so this is a documentation catalog (rule id, // description, docs link, categories) — not executable rewrite patterns. RuleFormatGrit RuleFormat = "grit" )
The rule-export formats `yze --emit-rules` supports.
type SourceAnalyzer ¶
type SourceAnalyzer struct {
// Analyze reports the findings in one file's contents.
Analyze func(path, source string) ([]goyze.Diagnostic, error)
// Claims reports whether this analyzer reads a given path at all. Each
// analyzer owns the rule for what it reads, because only it knows: SQL is
// an extension, a workflow is a directory, a shell script may be
// extensionless. A single suffix baked into the runner made the suite able
// to host exactly one language.
Claims func(path string) bool
Name goyze.AnalyzerName
Doc string
URL goyze.HelpURL
// Precision is declared, never inherited from silence — see
// [goyze.Precision]. A source analyzer reaches the catalog through
// [SQLRules] rather than through [goyze.Registration.Validate], so nothing
// refuses an undeclared one here; the suite test is what holds it.
Precision goyze.Precision
Categories []goyze.Category
}
SourceAnalyzer is a source analyzer the suite runs over .sql files, as opposed to the go/analysis analyzers it runs over Go packages. Its diagnostics already use the shared go-yze contract, so they merge into the same report; Doc and URL are the catalog metadata mirroring goyze.Registration, so the rule exports list SQL rules alongside the Go ones.
func FilterSource ¶
func FilterSource(analyzers []SourceAnalyzer, categories []goyze.Category) []SourceAnalyzer
FilterSource selects the source analyzers matching the given categories, mirroring Filter. An empty category set matches every analyzer.
func SourceAnalyzers ¶
func SourceAnalyzers() []SourceAnalyzer
SourceAnalyzers returns every source analyzer bundled into the suite, in stable rule-id order.
A source analyzer judges a FILE rather than a Go package, so the suite hosts more than one language: SQL by extension, markdown documents by name, shell scripts, and GitHub workflows by their directory. Each analyzer owns the rule for what it reads, because only it knows — which is why SourceAnalyzer.Claims is a function here rather than a suffix baked into the runner.
CLAIM ONLY WHAT CAN BE REPORTED. The runner reads a claimed file before analysing it, so a claim wider than the verdict costs a read per file and, worse, lets one unreadable file fail a whole run. `markup` therefore claims exactly the names it convicts rather than every path it could be asked about.
func (SourceAnalyzer) RuleID ¶
func (a SourceAnalyzer) RuleID() goyze.RuleID
RuleID returns the stable rule identifier carried by every diagnostic the analyzer emits. It is goyze.RuleIDFor, not a second spelling of the prefix, so both halves of the suite share one id scheme by construction rather than by agreement.
type WalkDir ¶
type WalkDir func(root string, fn fs.WalkDirFunc) error
WalkDir is fs.WalkDir's signature. It's injected so a test can drive the file walk without a real directory tree.
type WalkRoot ¶ added in v0.35.0
type WalkRoot string
WalkRoot is a directory the run was pointed at: the pattern with its recursive suffix removed, which is what both the source walk and the module probe are given. It is exported because RootsOf returns it and both callers live outside this package.
Source Files