report

type Artifact struct {
	Format      string // the reporter format, e.g. "sarif"
	Filename    string // default base filename, e.g. "results.sarif"
	ContentType string // MIME type, e.g. "application/sarif+json"
	Bytes       []byte // the rendered report
}

type ComponentVerdict struct {
	Name string
	// Verdict is the run's policy applied to this component's findings alone. Computed by
	// running the same norn.Policy rather than re-deciding, so the parts cannot disagree with
	// the whole about what failing means.
	Verdict norn.Verdict
	// Controls names the controls that failed for this component, in order.
	Controls []string
	// Priorities counts this component's findings by band, highest first (P1…P4).
	Priorities [4]int
	// Findings is the total, suppressed ones excluded — the same rule the counts follow.
	Findings int
}

type Data struct {
	Release     saga.Release
	Run         engine.Result
	Verdict     norn.Result
	MinPriority string
	// TopN caps how many findings the console "Fix first" table shows: 0 uses the default,
	// a negative value shows all, and a positive value shows that many. Ignored by other formats.
	TopN int
	// Compact strips what only a human reads — indentation and relayed rule prose — from the
	// machine formats (json, sarif), for a consumer that acts on the report rather than reads
	// it. The human formats ignore it: making those harder to read is the opposite of the point.
	Compact bool
	// Generated and Version stamp a report with when it ran and what produced it. A report
	// offered as evidence has to answer both; a reader who cannot tell whether they are looking
	// at today's scan or last quarter's has nothing they can rely on. Zero values are omitted,
	// so a caller that does not set them still renders a valid report.
	Generated time.Time
	Version   string
	// Components breaks the verdict down by the part of the application it belongs to, when
	// there is more than one. Optional: a caller that does not compute it renders as before.
	Components []ComponentVerdict
	// Exploitability describes the feeds that enriched this run's severities, if any. Empty
	// when no enrichment was configured, in which case nothing about it is rendered.
	//
	// A report that raised a finding to critical has to be able to say on what data, obtained
	// when. "KEV said so" is not reproducible; "on KEV as of 2026-08-01" is.
	Exploitability []FeedProvenance
	// UnattributedFindings counts findings that belong to no component — a project-scoped
	// control like `infrastructure` produces them. Reported alongside the component breakdown,
	// because a breakdown that silently omits them makes the parts look like the whole.
	UnattributedFindings int
}

type FeedProvenance struct {
	// Name is the signal: "kev" or "epss".
	Name string
	// URL is where the copy came from. Empty for a file the operator supplied, which is its own
	// useful statement — the data was brought in by hand.
	URL string
	// FetchedAt is when it was obtained. Zero for a file path, which has no fetch to record.
	FetchedAt time.Time
	// SHA256 is the digest of the bytes that were read.
	SHA256 string
	// Stale reports that the copy was older than the run's configured maxAge. Recorded here and
	// not only warned about in the logs, because the logs of the run that produced a report are
	// exactly where nobody looks six weeks later.
	Stale bool
}

type Reporter interface {
	Format() string
	Render(w io.Writer, d Data) error
}

type TemplateFinding struct {
	Priority string
	Level    string
	Score    string
	Control  string
	Tool     string
	RuleID   string
	Message  string
	Location string
}

type TemplateView struct {
	Release    saga.Release
	Verdict    string // "pass" | "fail"
	Pass       bool
	Priorities struct{ P1, P2, P3, P4 int }
	Controls   []norn.ControlOutcome
	Findings   []TemplateFinding // ranked most-urgent first
}