finding

type Action ¶ added in v0.16.0

type Action string

Action classifies who can close a finding. It is orthogonal to Severity, and the two must not be collapsed: Severity answers whether a finding blocks, Action answers who acts. A blocking finding may be safely automatic, and an advisory one may need a person.

const (
	// ActionAutomatic means a tool can generate the fix without asking.
	ActionAutomatic Action = "automatic"
	// ActionGuided means a tool can propose the fix but a person confirms it.
	ActionGuided Action = "guided"
	// ActionHuman means closing it needs judgment no tool here has.
	ActionHuman Action = "human"
)

func (a Action) Valid() bool

type Diagnostic ¶

type Diagnostic struct {
	Severity Severity `json:"severity"`
	Category string   `json:"category,omitempty"`
	Path     string   `json:"path,omitempty"`
	Message  string   `json:"message"`
	Action   Action   `json:"action,omitempty"`
}

Diagnostic is one finding about an artifact.

Action is optional and its zero value means *nobody classified this*, which is not the same claim as ActionHuman. That distinction is why there is no ActionUnknown constant to set: an unset field cannot be mistaken for a decision, and a named one invites being assigned deliberately. Same reason timeseries.Verdict keeps Compared separate from a zero baseline -- the absence of a judgement is not a judgement.

type Result ¶

type Result struct {
	Diagnostics []Diagnostic `json:"diagnostics"`
	Unexamined  []Unexamined `json:"unexamined,omitempty"`
}

Result accumulates diagnostics from one or more checks.

Unexamined is separate from Diagnostics rather than a kind of diagnostic: it carries no severity, cannot block, and answers a different question -- not "what is wrong" but "what was not looked at". A consumer walking Diagnostics to decide an outcome never sees it, which is the intended structural guarantee.

func (r *Result) Add(d *Diagnostic)

func (r *Result) HasBlocking() bool

type Severity ¶

type Severity string

Severity classifies a Diagnostic.

const (
	SeverityError   Severity = "error"
	SeverityWarning Severity = "warning"
)

func (s Severity) Blocking() bool

func (s Severity) Valid() bool

type Unexamined ¶ added in v0.19.0

type Unexamined struct {
	Aspect string `json:"aspect"`
	Reason string `json:"reason"`
}

Unexamined is one aspect a check or critic did not look at, and why not.

It exists because an empty findings list is ambiguous: a critic asked for three categories of defect and returning none may mean it found none or may mean it never looked, and a gate shipping on that silence cannot tell. Naming the gap converts an unknown into a recorded one.

Three properties, each of which the field is useless without.

It is advisory, always. Nothing may block because an Unexamined entry is present: a critic that can block by declaring a gap learns to declare none, which costs the gap and the finding both. Result is shaped so that holds without anyone remembering it.

It is testimony, not a derived fact. A critic saying it did not examine something is a claim about its own behaviour, unverifiable from the outside, and worth exactly what the critic is worth. This is what separates it from a skipped check, where code decided a check did not apply and can say so mechanically; a caller must not read the two alike, and they are deliberately different types for that reason.

Reason is required, and Valid is the whole point of the type. "I did not examine X" with no why is the boilerplate a required-but-unread field fills with: it satisfies the schema and records nothing.

func (u Unexamined) Valid() bool