detect

Documentation

Overview

Package detect holds the finding model and the deterministic detectors.

Index

• type Finding
  • func ApplySuppressions(findings []Finding) (kept []Finding, suppressed int)
  • func RunBugDetectors(pkgs []*packages.Package) ([]Finding, error)
  • func RunMissingCode(pkgs []*packages.Package) ([]Finding, error)
  • func RunMissingHandlers(ctx context.Context, g graph.Graph) ([]Finding, error)
  • func RunMisspell(pkgs []*packages.Package) ([]Finding, error)
  • func RunModernize(dir string) ([]Finding, error)
  • func RunOverEngineering(ctx context.Context, g graph.Graph, scope string, ...) ([]Finding, error)
  • func RunStaleSwagger(ctx context.Context, g graph.Graph, dir string) ([]Finding, error)
  • func RunStaticcheck(pkgs []*packages.Package) ([]Finding, error)
  • func RunUntestedExports(ctx context.Context, g graph.Graph, scope string) ([]Finding, error)
  • func RunVuln(roots []string) ([]Finding, error)
• type TextEdit
  • func SuggestedEdits(pkgs []*packages.Package, target Finding) (edits []TextEdit, ok bool)

Types

type Finding

type Finding struct {
	Category string `json:"category"` // "bug", "over-engineered", "stale-doc", "missing", "modernize"
	Detector string `json:"detector"` // analyzer that produced it, e.g. "nilness"
	Severity string `json:"severity"` // "high" | "medium" | "low" — how bad if real

	// Confidence is how sure we are the finding is real (independent of severity). SSA/type-checked
	// analyzers are "high"; heuristic AST/marker checks are "medium" or "low". Useful for triage.
	Confidence string `json:"confidence,omitempty"` // "high" | "medium" | "low"
	File       string `json:"file"`
	Line       int    `json:"line"`
	Col        int    `json:"col"`
	Message    string `json:"message"`
	Package    string `json:"package"`
	// Fingerprint is a stable identity for the finding (detector + relative path + message),
	// deliberately independent of line number so it survives edits that shift lines. Used to match
	// findings across runs (baseline mode) and to dedupe in SARIF. Set by the scan layer.
	Fingerprint string `json:"fingerprint,omitempty"`
}

Finding is one reported issue. It is intentionally flat and JSON-friendly: the MCP is report-first, so a finding carries evidence, never a fix.

func ApplySuppressions

func ApplySuppressions(findings []Finding) (kept []Finding, suppressed int)

ApplySuppressions drops findings the author marked intentional with a //gospect:ignore comment on (or directly above) the flagged line. It returns the surviving findings and how many were suppressed. Files are read once and cached; an unreadable file leaves its findings untouched.

func RunBugDetectors

func RunBugDetectors(pkgs []*packages.Package) ([]Finding, error)

RunBugDetectors runs the analyzer set over already-loaded packages and maps each diagnostic to a Finding. It reports; it never edits.

func RunMissingCode

func RunMissingCode(pkgs []*packages.Package) ([]Finding, error)

RunMissingCode walks the root packages' syntax for "missing" signals that are self-contained (no graph needed): unimplemented stubs, TODO/FIXME markers, and unchecked error returns. Route-with-no-handler and untested-exports come later via codebase-memory composition.

func RunMissingHandlers

func RunMissingHandlers(ctx context.Context, g graph.Graph) ([]Finding, error)

RunMissingHandlers asks the graph for HTTP routes with no handler and maps them to findings. Graph-wide (routes carry no file path). Requires a configured graph.

func RunMisspell

func RunMisspell(pkgs []*packages.Package) ([]Finding, error)

RunMisspell flags common English misspellings in comments and in function/type names. It uses the curated misspell dictionary — a list of KNOWN common typos, not a "is this a real word" check — so Go jargon (ctx, mux, unmarshal, cfg) is never flagged. Report-only: it never renames identifiers (that would break callers). Comments cover godoc and swagger/swaggo annotations. Opinionated hygiene, so it runs only under -pedantic.

func RunModernize

func RunModernize(dir string) ([]Finding, error)

RunModernize inspects the module's go.mod for an outdated go directive. It is deliberately deterministic and dependency-light; deeper modernization (deprecated APIs, unadopted features) comes later. A missing/unparseable go.mod is not an error — we just have nothing to report.

func RunOverEngineering

func RunOverEngineering(ctx context.Context, g graph.Graph, scope string, minCyclomatic, minCognitive int) ([]Finding, error)

RunOverEngineering asks the graph for functions/methods under scope whose complexity exceeds the thresholds and maps them to findings. Requires a configured graph.

func RunStaleSwagger

func RunStaleSwagger(ctx context.Context, g graph.Graph, dir string) ([]Finding, error)

RunStaleSwagger finds OpenAPI/Swagger specs under dir and reports documented endpoints that have no matching registered route (a likely stale doc). Requires a configured graph for the route set. If no spec is present it returns nothing.

Path matching is heuristic: path params ({id}/:id) are normalized and base-path differences are tolerated via suffix matching, so this is report-first (a human/agent confirms).

func RunStaticcheck

func RunStaticcheck(pkgs []*packages.Package) ([]Finding, error)

RunStaticcheck runs the staticcheck SA analyzers over already-loaded packages and maps each diagnostic to a Finding. Report-only, like every other detector.

func RunUntestedExports

func RunUntestedExports(ctx context.Context, g graph.Graph, scope string) ([]Finding, error)

RunUntestedExports asks the graph for exported functions under scope that have no test, and maps them to findings. This detector requires a configured graph; callers skip it when the graph is nil (gospect still works standalone without one).

func RunVuln

func RunVuln(roots []string) ([]Finding, error)

RunVuln reports known-vulnerability findings by shelling out to govulncheck (golang.org/x/vuln) in each module root. It is opt-in: govulncheck is slow and needs the vulnerability database (usually a network call), so the scan enables it only on request. If govulncheck isn't installed, it returns a single low-severity note rather than failing — the rest of the scan is unaffected.

Only *reachable* vulnerabilities (those govulncheck traces to a called function) are reported — the high-signal subset — one finding per (OSV id, module).

type TextEdit

type TextEdit struct {
	File    string
	Start   int
	End     int
	NewText string
}

TextEdit is a resolved edit (byte offsets into a file) from an analyzer's SuggestedFix.

func SuggestedEdits

func SuggestedEdits(pkgs []*packages.Package, target Finding) (edits []TextEdit, ok bool)

SuggestedEdits runs the analyzer that could have produced target and returns the edits of its suggested fix — but ONLY when the analyzer offers exactly ONE fix. Multiple fixes are ambiguous alternatives (e.g. SA4013 offers both "!b" and "b" for "!!b"), and picking one blindly can change behavior in a way the verify harness can't catch, so those are left to a human or an AI agent. This is why deterministic coverage is intentionally conservative: ok is false for ambiguous or fixless findings.