report

type Action struct {
	// Title is what to do, in the imperative.
	Title string `json:"title"`
	// Control the findings came from, and the worst priority among them.
	Control  string `json:"control,omitempty"`
	Priority string `json:"priority,omitempty"`
	// Clears is how many findings this one action resolves.
	Clears int `json:"clears"`
	// Upstream marks an action whose unit of work is something somebody else publishes: the fix
	// is to take a newer one, not to change anything inside it.
	Upstream bool `json:"upstream,omitempty"`
	// Where lists the distinct places this applies, capped.
	Where []string `json:"where,omitempty"`
	// RuleIDs are the rules this action resolves, capped, so a caller can look any of them up.
	RuleIDs []string `json:"ruleIds,omitempty"`
	// Key is what these findings grouped under: the identity that makes two of them one action.
	//
	// Opaque, and deliberately. Its shape is this package's business and changes when the grouping
	// does. What it is for is membership: a caller holding the findings can ask this
	// package which action each one belongs to and match on this, instead of inferring it from a
	// title. Title is written for a reader and is not an identity, an action fed by two controls
	// takes one of their names, and matching on that silently drops the other's findings.
	//
	// Not serialized. It is an identity for a caller holding this package's own output in memory,
	// and it contains a separator that has no business in a JSON document an assistant reads.
	Key string `json:"-"`
	// FixedVersions are the releases that clear this, in the order the advisories named them.
	//
	// Every one of them, not the newest: advisories disagree about which release resolves them,
	// and version ordering belongs to the ecosystem rather than here. One entry is the answer;
	// several means the reader's package manager settles it, and naming one of them as sufficient
	// would read as "do this and you are done" while leaving findings behind.
	FixedVersions []string `json:"fixedVersions,omitempty"`
}

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
	// Declared counts what the descriptor gave this component, by target kind. It is the denominator:
	// "3 images not scanned" does not say whether that is all of them or three of thirty, and those
	// are different situations. One is a component nobody looked at, the other is a gap in one that
	// was mostly covered.
	Declared map[string]int
	// Unscanned is what this component has that no scanner managed to look at.
	//
	// A component whose every image failed to pull has had nothing examined, and without this it
	// renders as passing with no findings. Which is the report asserting something no scanner
	// established. The same reasoning already keeps a component the scope excluded out of the pass
	// list; a component the scan could not reach is the same situation arrived at later.
	Unscanned []engine.Unscanned
}

type Data struct {
	// Project is which project this run belongs to, and what a platform files it under.
	Project     string
	Release     saga.Release
	Run         engine.Result
	Verdict     norn.Result
	MinPriority string
	// Scope describes what the run was narrowed to, and is nil when it was not narrowed at all.
	//
	// A pointer so that every unscoped report. Which is nearly all of them, renders and serializes
	// exactly as it did before. Its presence is the signal: an artifact carrying a scope is a partial
	// answer, and a consumer that finds one has been told so rather than having to infer it from a
	// component list that looks complete.
	Scope *Scope
	// 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
	// Evidence restores the blocks that make a run defensible, tool provenance, what each control
	// measured against, declared effects, the scanned revision, job and cache counts.
	//
	// Off by default. A developer at a terminal is asking what to fix, and answers to questions
	// they have not asked push the answer to the one they have off the screen. An auditor is a
	// real reader, just not the default one, and asks for this.
	Evidence bool
	// Descriptor is the Saga this run was produced from: the digest of the merged, effective
	// document and the files it was assembled from.
	//
	// Nil for a scan with no descriptor, which is a real case and not an error.
	Descriptor *skald.DescriptorRef
	// CI is the job the scan ran in, and nil outside one.
	//
	// It exists once, in the process doing the work, and is gone when that process exits. A
	// platform receiving this report can see a repository URL and cannot see which workflow
	// produced the scan.
	CI *ci.Context
	// Gate records the policy the verdict was produced under.
	//
	// A verdict is only as meaningful as the gate behind it, and a gate can be narrowed or turned off
	// entirely from the command line. Without this the report shows a verdict and no way to tell what
	// it was measured against, the same gap that suppression closes for findings, where the question
	// is never "did the scanner run" but "who decided this was acceptable".
	Gate GateSettings

	// View is what the report shows and how densely, one setting rather than two that have to be
	// combined. The zero value is ViewFindings.
	View View
	// Uncovered is what this descriptor declares and no enabled control examines.
	Uncovered []Gap
	// Suggestions are the things this particular run makes worth trying, decided by the caller
	// because they depend on how it was invoked rather than on what it found.
	Suggestions []Suggestion
	// Unclassified reports that no component declares exposure or criticality.
	//
	// A caveat on every band in the report: with nothing declared, each component is read as public
	// and critical, which is the most severe reading, so the bands rank severity alone. A reader
	// who does not know that is reading a ranking as though it described their application.
	Unclassified 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
	// VEX names the author and product for the "vex" format. Nil falls back to the release,
	// which is enough for a valid document and not enough for a publishable one.
	VEX *saga.VEXConfig
	// 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
	// Repositories is which repository each scan read, and at which commit. Derived from what the
	// scanners recorded rather than from the descriptor, because the descriptor usually names no
	// revision at all. And "the default branch" is not something a reader can check out.
	Repositories []RepositoryProvenance
	// Tools records the build of each external scanner the run used, and whether Draugr can
	// vouch for it. Empty when nothing external ran.
	//
	// A scan runs whatever is on PATH, which is right. An operator may have an experimental build or a
	// fork, and blocking them would be Draugr mistaking "I cannot verify this" for "this is wrong".
	// But a report that cannot say which build produced its findings cannot be reproduced, so the
	// answer is to record it.
	Tools []ToolBuild
	// 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 Gap struct {
	// Component and Surface name what was declared and went unexamined.
	Component, Surface string
	// Controls are the ones that would have looked at it, every one of them off.
	Controls []string
}

type GateSettings struct {
	// Threshold is the severity band that fails a control by default.
	Threshold sarif.Severity
	// PerControl overrides Threshold for named controls, on a severity gate.
	PerControl map[string]sarif.Severity
	// FailOnPriority additionally fails on a priority band, when set.
	FailOnPriority string
	// PerControlBand overrides the band for named controls, on a band gate. The other half of
	// PerControl: a threshold only applies in the vocabulary its gate asks in, so exactly one of
	// these is ever populated.
	PerControlBand map[string]string
	// Disabled is --no-gate: the verdict is reported and the command still exits 0.
	Disabled bool
}

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

type RepositoryProvenance = sarif.RepositoryRef

type Scope struct {
	// Components and Controls are what the caller asked for; an empty list means that axis was
	// not restricted.
	Components []string `json:"components,omitempty"`
	Controls   []string `json:"controls,omitempty"`
	// SkippedComponents are declared components this run did not scan.
	//
	// Named rather than counted: "10 not scanned" tells a reader they are missing something and
	// not which thing, and the answer is one they already have.
	SkippedComponents []string `json:"skippedComponents,omitempty"`
}

type Suggestion struct {
	// What to type, or the key to add to the descriptor.
	What string
	// Why, in a clause. Not an instruction: none of this is required, and a reader who already has
	// their answer should be able to pass over the whole block.
	Why string
}

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

type TemplateView struct {
	// Project is what the run is about. Exposed beside the release because a release carries only
	// a version now, and a template with nothing but that renders "1.4.0" over and over with no
	// statement about what is at 1.4.0.
	Project    string
	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
}

type ToolBuild struct {
	// Name is the executable, e.g. "trivy".
	Name string
	// Version is what it reports, or what Draugr recorded when it installed it.
	Version string
	// Level is how strongly Draugr can vouch for this build: pinned, signed, checksum, unverified, or
	// external. Not a boolean, because those are genuinely different claims, an unsigned checksum
	// proves the download was not corrupted without proving upstream published it, and collapsing that
	// into "unattested" discards a difference a reader may care about.
	Level string
	// Reason renders the level for someone who has not read its definition.
	Reason string
}

type View string