Documentation
¶
Overview ¶
Package audit defines the wire types every detector emits and the shared serializer that renders them as JSON or text.
Finding is the per-smell record. Report is the top-level envelope. Severity ranks findings from CRITICAL down to LOW; Emit sorts and writes a Report to stdout.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Emit ¶
Emit serializes a report in the requested format ("json" or "text"). Findings are sorted by severity, smell ID, then location for stable output across runs. A nil Findings slice is normalized to an empty array so JSON consumers always see an array.
func ResolvedTags ¶
ResolvedTags splits a comma-separated --tags flag value into the slice that goes into the report envelope. Returns nil when no tags were supplied.
func ValidateFormat ¶ added in v0.2.0
ValidateFormat rejects unknown --format values. The CLI calls this before loading any packages so a typo fails in milliseconds instead of after a full typecheck of the target module.
func ValidateSuppressions ¶ added in v0.2.2
ValidateSuppressions checks --suppress selectors without applying them. A selector is SMELL_ID to suppress that detector everywhere, or SMELL_ID@LOCATION to suppress only findings whose stable location starts with LOCATION.
Types ¶
type Finding ¶
type Finding struct {
Smell string `json:"smell"`
SmellID string `json:"smell_id"`
Severity Severity `json:"severity"`
Location string `json:"location"`
Message string `json:"message"`
Evidence map[string]any `json:"evidence,omitempty"`
Suggestion string `json:"suggestion,omitempty"`
}
Finding is one entry in a lagotto audit. Every detector emits zero or more findings; the JSON shape is the stable downstream contract.
Field semantics:
- Smell: human-readable name ("Receiver Monolith")
- SmellID: short stable ID ("G1") — use this in tooling
- Severity: CRITICAL | HIGH | MEDIUM | LOW
- Location: stable import path plus file/type/symbol where applicable
- Message: one-line summary suitable for a terminal
- Evidence: structured per-detector data (method counts, file lists, package paths) for tooling that wants to drill in
- Suggestion: concrete imperative remediation guidance
type FindingsError ¶ added in v0.2.0
FindingsError signals that findings met the --fail-on threshold. The run itself succeeded — the report was emitted — so main translates this into exit code 2, distinguishing "findings found" (2) from "run failed" (1).
func (*FindingsError) Error ¶ added in v0.2.0
func (e *FindingsError) Error() string
type IncompleteLoadError ¶ added in v0.2.2
type IncompleteLoadError struct {
Count int
}
IncompleteLoadError means the report was emitted, but one or more packages did not load or type-check completely. Callers must treat this as a failed audit rather than a clean result.
func (*IncompleteLoadError) Error ¶ added in v0.2.2
func (e *IncompleteLoadError) Error() string
type Report ¶
type Report struct {
Root string `json:"root"`
Tags []string `json:"tags,omitempty"`
LoadErrors []string `json:"load_errors,omitempty"`
SuppressedFindings int `json:"suppressed_findings,omitempty"`
Findings []Finding `json:"findings"`
}
Report is the top-level audit envelope written to stdout. Root is the path the audit was run against, Tags echoes the build tags the loader used, and Findings is severity-sorted (CRITICAL first). LoadErrors carries per-package load/type errors so JSON consumers can tell a clean audit from a degraded one; when it is non-empty, detectors may have skipped the affected packages.
type Severity ¶
type Severity string
Severity ranks findings from CRITICAL (always investigate) down to LOW (worth knowing about, low blast radius). Severity is a string so the JSON output is human-readable.
const ( SevCritical Severity = "CRITICAL" SevHigh Severity = "HIGH" SevMedium Severity = "MEDIUM" SevLow Severity = "LOW" )
Severity values; ranking is CRITICAL < HIGH < MEDIUM < LOW (lower is worse), matched by sevRank.
func ParseSeverity ¶ added in v0.2.0
ParseSeverity converts a case-insensitive severity name ("high", "HIGH") to its Severity value. ok is false for unknown names.
Source Files