analyzers

package
v0.28.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 4, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package analyzers holds the house rules that are about the shape of code rather than about a resolved name: a lookup followed by an insert, a package URL pasted together from a literal, a detection result built without its attribution, a name the export layer may not mention even inside a string. No linter expresses those, so each is a go/analysis analyzer run by the guardcheck command through go vet.

Each analyzer keys on where the decision is made and asks the type checker which package a method, literal or constant belongs to, so an alias, a wrapper, a hoisted constant or a local type with the same method names does not evade it (ADR-0044 rules 1 and 6). Each has a fixture under testdata with a `// want` comment on every forbidden shape and a passing shape beside it; the fixture runs in `make test`, which is the rule "a guard must be able to fail" made permanent rather than proved once by hand.

Only shipped code is policed: files ending in _test.go are skipped, because a test spells the forbidden shape on purpose. Generated files are not skipped: a generator's output is shipped code.

gocritic's ruleguard DSL was considered for these rules and declined. The two-statement lookup-then-insert shape is awkward in a single-expression DSL, the rule file would need the go-ruleguard/dsl module, and the fixture-driven proof above is native to analysistest, not to a DSL run inside golangci-lint.

Index

Constants

This section is empty.

Variables

View Source
var Attributed = &analysis.Analyzer{
	Name: "attributed",
	Doc:  "reports a detection result built with graphs outside detectors.Attributed or a reasoned detectors.Unattributed",
	Run:  runAttributed,
}

Attributed reports a detection result that carries graphs and is built anywhere but as the argument of detectors.Attributed or detectors.Unattributed.

A result that carries graphs but skips Attributed ships locations with nothing to join reachability evidence to: the module root is the join key ADR-0037 defines, and a detector that forgets it leaves every site unattributed for the whole pipeline. Wrapping the literal is one line, which is exactly the kind of rule that gets forgotten.

The rule keys on the literal, not on the return statement (ADR-0044 rule 1): a result held in a variable and returned later is reported where it is built, and so is one wrapped only later, because the wrap belongs at the construction site. There is no data flow to reason about and nothing for a variable to hide behind.

The exemption is typed, not listed: a detector with no module root to name builds its result inside Unattributed with its reason as an argument, and this analyzer checks that the reason is present and that the wrapped literal actually names Graphs, so an exemption cannot be empty or stale (ADR-0044 rule 5).

View Source
var NodeInsert = &analysis.Analyzer{
	Name: "nodeinsert",
	Doc:  "reports a graph lookup followed by a hand-written insert; call detectorkit.EnsureNode instead",
	Run:  runNodeInsert,
}

NodeInsert reports a lookup on a graph followed, in the same function, by an insert on the same graph.

A hand-written "is it already there?" check before an insert is how a dozen detectors independently decided what happens to a duplicate record, and the answer was usually to drop it, origin and all. Node insertion goes through detectorkit.EnsureNode so the behavior is decided once and a detector written later inherits it (ADR-0033).

The two calls are paired by which graph they act on, not by how the receiver is spelled: a receiver that is a variable is compared as the type checker's object, so a shadowing name is a different graph; any other receiver expression (a field, a call) is compared as source text; and an assignment of one graph to another inside the function -- `alias := g`, `alias := h.graph` -- folds the two identities together. The lookup's argument is not inspected at all: the regex this replaced matched only an identifier there and walked past `g.Node(pkg.NodeID())` for as long as it existed. Both calls must resolve to methods of the SDK's Graph; a local type with the same method names is not the hazard, and a lookup on one graph followed by an insert into another is not either.

Order is source order, except inside a closure: a closure's body runs when it is called, not where it is written, so an insert inside one pairs with a lookup on the same graph anywhere in the enclosing function. That errs toward reporting a closure that is defined early and never called after the lookup, which is the direction that gets looked at (ADR-0044).

Taking either method as a value -- `lookup := g.Node`, `(*model.Graph).AddNode` -- is reported on its own. A call through such a value names no graph, so pairing it would need value tracking; the method value buys nothing a direct call or detectorkit.EnsureNode does not, so the capability is removed rather than followed (ADR-0044).

View Source
var PURLString = &analysis.Analyzer{
	Name:      "purlstring",
	Doc:       "reports a package URL built by concatenating or formatting a \"pkg:\" value; build it with the SDK",
	Run:       runPURLString,
	FactTypes: []analysis.Fact{new(returnsPURLPrefix)},
}

PURLString reports a package URL built from a "pkg:" string.

A package URL pasted together from a literal and some escaping is the shape that produced a real defect: the SBOM export built its synthesized project root with url.PathEscape, which leaves '@' alone, so a project named "app@2" exported an identity that read back as "app" at version "2". The separators are the specification's to escape, so the parts go into the kit and the string comes out (ADR-0038).

Construction is a "pkg:"-prefixed value on either side of +, appended with +=, or handed to a printf-style call. The value need not be a literal at the site: the type checker's constant folding answers for a literal, a named constant, or a constant expression; and a variable, package-level or local, that is ever defined or assigned such a value is found before any expression is checked, whatever order the code comes in -- Go lets a function name a variable declared below it, and a closure runs after an assignment written below it. A call answers too when the function it calls can return such a value: a function declared in the package, a function literal held in a variable, or -- through an analysis fact -- a function in a package this one imports. Hoisting the prefix into a const, a variable, or a helper therefore renames the defect rather than removing it. A bare literal is data, and a prefix check against one is decomposition, not construction; neither is reported.

Functions

This section is empty.

Types

This section is empty.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL