contracts

type Analyzer struct {
	// Name is the stable identifier used by `--analyzer` and in timings.
	Name string
	// Doc is one line describing what the analyzer looks at.
	Doc string
	// Rules are the IDs this analyzer may emit. [Run] rejects a
	// diagnostic naming any other rule — an analyzer cannot smuggle in an
	// undocumented finding, which is what keeps the catalog honest.
	Rules []string
	// Run inspects the pass. Returning an error aborts only this
	// analyzer; the rest of the run continues and the error is reported.
	Run func(*Pass) ([]Diagnostic, error)
}

type AnalyzerTiming struct {
	Name        string        `json:"name"`
	Duration    time.Duration `json:"-"`
	Millis      float64       `json:"ms"`
	Diagnostics int           `json:"diagnostics"`
	Error       string        `json:"error,omitempty"`
}

type ArchitectureConfig struct {
	Layers []LayerRule
	Forbid []ForbidRule
}

type Baseline struct {
	Schema int `json:"schema"`
	// Generated is when the baseline was recorded, for the report's "this
	// is N months old" nudge.
	Generated string `json:"generated"`
	// Note is free text explaining why this debt is accepted.
	Note string `json:"note,omitempty"`
	// Counts maps rule ID → file → number of accepted findings.
	Counts map[string]map[string]int `json:"counts"`
}

type BaselineDelta struct {
	RuleID   string
	File     string
	Baseline int
	Current  int
}

type BaselineResult struct {
	// Accepted is how many findings the baseline absorbed.
	Accepted int
	// Fixed lists (rule, file) pairs where fewer findings occur now than
	// the baseline records — debt that was paid down. Reported so the
	// baseline visibly shrinks instead of quietly over-accepting forever.
	Fixed []BaselineDelta
}

type Capability string

type CapabilitySummary struct {
	Capability Capability `json:"capability"`
	Errors     int        `json:"errors"`
	Warnings   int        `json:"warnings"`
	Infos      int        `json:"infos"`
}

type Config struct {
	// Path is the file this came from, "" when defaults.
	Path string
	// Exempt are path globs no analyzer looks at.
	Exempt []string
	// FailOn is the severity floor that makes a run fail. Default
	// SeverityError; `strict: true` lowers it to SeverityWarn.
	FailOn Severity

	Coverage     CoverageConfig
	Architecture ArchitectureConfig
	// contains filtered or unexported fields
}

type CoverageConfig struct {
	// Minimum is the line-coverage percentage floor. Zero disables the
	// check; the generated config comments this in at 90.
	Minimum float64
	// MinimumSet distinguishes "not configured" from "configured to 0".
	MinimumSet bool
	// Routes demands every discovered route be exercised by a test.
	Routes bool
	// Permissions demands every declared permission be exercised.
	Permissions bool
	// Entities demands every entity's CRUD surface be exercised.
	Entities bool
	// Profile is the path to the `go test -coverprofile` output, relative
	// to the project root. Empty means the default location.
	Profile string
}

type Diagnostic struct {
	// RuleID identifies the catalog entry. Analyzers set this; Slug,
	// Capability, and Severity are filled in from the catalog during
	// [Run], so an analyzer cannot claim a severity its rule did not
	// declare.
	RuleID string `json:"rule"`
	// Slug mirrors Rule.Slug for readability.
	Slug string `json:"slug,omitempty"`
	// Capability mirrors Rule.Capability.
	Capability Capability `json:"capability,omitempty"`
	// Severity is the *effective* severity after config relaxation.
	Severity Severity `json:"severity,omitempty"`

	// File is relative to the pass root, slash-separated.
	File string `json:"file"`
	// Line is 1-indexed. Zero means the finding is about the project as a
	// whole rather than a location (a missing manifest, say).
	Line int `json:"line,omitempty"`
	// Column is 1-indexed, zero when unknown.
	Column int `json:"column,omitempty"`
	// EndLine bounds a multi-line finding. Zero means single-line.
	EndLine int `json:"endLine,omitempty"`

	// Message is the instance-specific statement — it names the actual
	// route, field, or import, where Rule.Summary states the class.
	Message string `json:"message"`
	// Suggestion is the instance-specific remedy, naming the concrete
	// file to create or call to add. Falls back to Rule.Fix when empty.
	Suggestion string `json:"suggestion,omitempty"`
	// Snippet is the offending source line, trimmed.
	Snippet string `json:"snippet,omitempty"`
	// RedactSnippet stops [Run] from filling Snippet in from the source.
	// Set by rules whose whole subject is a value that must not be echoed
	// — a report that prints the committed credential back into a
	// terminal, a CI log, and a SARIF artifact has made things worse.
	RedactSnippet bool `json:"-"`
	// Evidence carries analyzer-specific structured detail — the route
	// pattern, the two conflicting registrations, the import edge. Agents
	// read this; the text reporter ignores it.
	Evidence map[string]string `json:"evidence,omitempty"`
	// Fix is the mechanical edit, when the analyzer can produce one.
	Fix *SuggestedFix `json:"fix,omitempty"`

	// Rule is the catalog entry, attached during [Run]. Present in JSON
	// output so a consumer needs no second lookup.
	Rule *Rule `json:"ruleDoc,omitempty"`
}

type Example struct {
	// Caption is the one-line framing ("a POST route with no access
	// declaration"). Optional.
	Caption string `json:"caption,omitempty"`
	// Bad is the code that trips the rule.
	Bad string `json:"bad"`
	// Good is the code that satisfies it.
	Good string `json:"good"`
}

type FixedDiagnostic struct {
	Rule string `json:"rule"`
	File string `json:"file"`
	Line int    `json:"line"`
}

type ForbidRule struct {
	From   string
	To     string
	Reason string
}

type LayerRule struct {
	// Name identifies the layer in diagnostics ("core", "domain", "ui").
	Name string
	// Packages are import-path globs, matched against the *suffix* of an
	// import path so `core/**` matches
	// `github.com/you/app/core/render` without repeating the module path.
	Packages []string
}

type Pass struct {
	// Root is the absolute directory being analysed.
	Root string
	// ModulePath is the go.mod module path, empty when there is none.
	ModulePath string
	// Config is the resolved configuration for this run.
	Config *Config
	// contains filtered or unexported fields
}

type Report struct {
	// Vet records the `go vet` stage, when the caller ran one.
	Vet *VetResult `json:"vet,omitempty"`
	// Root is the absolute directory analysed.
	Root string `json:"root"`
	// ConfigPath is the config file used, "" when defaults applied.
	ConfigPath string `json:"config,omitempty"`
	// Capabilities is the requested filter, empty when everything ran.
	Capabilities []Capability `json:"capabilities,omitempty"`
	// Diagnostics is every surviving finding, worst first.
	Diagnostics []Diagnostic `json:"diagnostics"`
	// Suppressed counts findings silenced by a `//gofastr:allow`
	// directive. Reported so a clean run still admits what it skipped.
	Suppressed int `json:"suppressed"`

	// Baselined counts findings absorbed by a recorded baseline —
	// pre-existing debt the project agreed to carry.
	Baselined int `json:"baselined,omitempty"`
	// BaselineFixed counts (rule, file) buckets whose baseline allowance
	// is now larger than the findings that remain. Debt that was paid
	// down and should be re-recorded so the baseline keeps shrinking.
	BaselineFixed int `json:"baselineFixed,omitempty"`
	// Notices are human-facing remarks the CLI would otherwise print to
	// stdout — "this rule has no autofix", "not a git repository". In text
	// mode they are printed; in JSON they belong here, because anything
	// printed alongside the document corrupts it, and dropping them
	// silently would lose the run's own account of what it did.
	Notices []string `json:"notices,omitempty"`
	// Fixed lists the diagnostics --fix resolved, so a JSON consumer
	// driving verify → fix → verify can see what changed.
	Fixed []FixedDiagnostic `json:"fixed,omitempty"`
	// Unparsed counts files the parser rejected. Those files produced no
	// findings from any analyzer, so without this a mid-edit tree reads as
	// clean for exactly the files nobody could read.
	Unparsed int `json:"unparsed,omitempty"`
	// OutsideChange counts findings dropped by --changed because they sit
	// in files this change did not touch. Reported so a narrowed run
	// never reads as a whole-repository all-clear.
	OutsideChange int `json:"outsideChange,omitempty"`
	// Errors are analyzer failures — a broken analyzer, not a broken app.
	Errors []string `json:"analyzerErrors,omitempty"`
	// Timings is per-analyzer wall time, slowest first.
	Timings []AnalyzerTiming `json:"timings,omitempty"`
	// Relaxations lists every configured downgrade, so `verify` cannot
	// pass quietly on a config that turned the interesting half off.
	Relaxations []string `json:"relaxations,omitempty"`
	// FailOn is the severity floor that decides the exit code.
	FailOn Severity `json:"failOn"`
	// Duration is the whole run's wall time.
	Duration time.Duration `json:"-"`

	// Summary is the per-capability tally, in capability order.
	Summary []CapabilitySummary `json:"summary"`
	// Counts are the run-wide totals.
	Counts struct {
		Errors   int `json:"errors"`
		Warnings int `json:"warnings"`
		Infos    int `json:"infos"`
	} `json:"counts"`
	// contains filtered or unexported fields
}

type Rule struct {
	// ID is the stable identifier — "GOFASTR1002". Assigned from the
	// capability's number block (see catalog.go) and never reused, so a
	// suppression written today keeps meaning the same thing.
	ID string `json:"id"`
	// Slug is the human-readable name — "routing/missing-auth". Accepted
	// anywhere an ID is, because `//gofastr:allow(routing/missing-auth)`
	// reads better in a diff than a number.
	Slug string `json:"slug"`
	// Title is the short noun phrase shown as the finding's headline.
	Title string `json:"title"`
	// Capability is the area this rule belongs to.
	Capability Capability `json:"capability"`
	// Severity is the default severity. Config may lower it; nothing
	// raises it.
	Severity Severity `json:"severity"`
	// Summary is one sentence stating what was detected.
	Summary string `json:"summary"`
	// Why explains the consequence — what breaks, for whom, when. This is
	// the field that turns a lint error into a lesson.
	Why string `json:"why"`
	// Fix is the concrete remedy, in imperative voice, naming the exact
	// API or file to reach for.
	Fix string `json:"fix"`
	// Examples are bad/good pairs. Optional but strongly encouraged.
	Examples []Example `json:"examples,omitempty"`
	// Doc is the `gofastr docs` topic that covers this rule in depth
	// (e.g. "reactivity"). Rendered as a URL by DocURL.
	Doc string `json:"doc"`
	// Autofix reports whether an analyzer can produce a mechanical edit
	// for this rule. Advisory: a rule may be marked autofixable and still
	// decline to fix a particular instance it cannot rewrite safely.
	Autofix bool `json:"autofix"`
}

type RunOptions struct {
	// Capabilities restricts the run to analyzers covering at least one
	// of these. Empty runs them all.
	Capabilities []Capability
	// Analyzers restricts the run by analyzer name. Empty runs them all.
	Analyzers []string
	// Parallel caps concurrent analyzers. Zero uses GOMAXPROCS.
	Parallel int
}

type Severity int

type SourceFile struct {
	// Rel is the slash-separated path from the pass root.
	Rel string
	// Abs is the absolute path on disk.
	Abs string
	// IsTest is true for _test.go files.
	IsTest bool
	// IsGenerated is true when the file carries a `Code generated … DO NOT
	// EDIT` header. Analyzers skip these by default: the developer cannot
	// fix a finding there, only the generator can.
	IsGenerated bool
	// Package is the Go import path of the file's directory, derived from
	// the module path. Empty when the root has no go.mod.
	Package string
}

type SuggestedFix struct {
	// Description says what the edit does, in imperative voice.
	Description string `json:"description"`
	// Edits are applied together or not at all.
	Edits []TextEdit `json:"edits"`
}

type TextEdit struct {
	File  string `json:"file"`
	Start int    `json:"start"`
	End   int    `json:"end"`
	New   string `json:"new"`
	// Old is the text this edit expects to find at [Start, End). When
	// set, [Report.Apply] refuses the edit if the file no longer carries
	// it — a file edited since analysis can pass every bounds check and
	// still put the offsets in the middle of something else entirely.
	// Leave it empty only for pure insertions (Start == End), where there
	// is nothing to expect.
	Old string `json:"old,omitempty"`
}

type TextOptions struct {
	// Color emits ANSI escapes. Callers set this from a TTY check.
	Color bool
	// Verbose prints the rule's Why and an example under every finding
	// rather than only under the first of each rule. The compact default
	// exists because twenty instances of one rule should teach the lesson
	// once, not twenty times.
	Verbose bool
	// Timings appends the per-analyzer wall times.
	Timings bool
}

type VetResult struct {
	// Ran is false when the stage was skipped.
	Ran bool `json:"ran"`
	// Passed is meaningful only when Ran, and the wire format enforces
	// that: see MarshalJSON.
	Passed bool `json:"passed"`
	// Skipped explains why the stage did not run, e.g. "--no-vet".
	Skipped string `json:"skipped,omitempty"`
	// Output is vet's diagnostic text when it failed.
	Output string `json:"output,omitempty"`
}