sarif

type Counts struct {
	Error   int
	Warning int
	Note    int
	None    int
}

type Field struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type Level string

type Location struct {
	URI       string `json:"uri,omitempty"`
	StartLine int    `json:"startLine,omitempty"`
}

type MarshalOptions struct {
	// Compact drops what only a human reads — indentation, and the rule prose relayed from
	// the scanner — while keeping the report valid SARIF.
	//
	// It exists for a consumer that is going to *act* on the report rather than read it,
	// typically an agent paying for every byte of context. Rule descriptions and remediation
	// text are the bulk of a Draugr report (61% of it, measured on this repo), and a reader
	// that can follow a link doesn't need them inlined. So helpUri survives compaction and the
	// prose doesn't: keep the pointer, drop the paragraphs.
	Compact bool
}

type Provenance struct {
	// Tool is the scanner that produced this account.
	Tool string `json:"tool"`
	// Version is the scanner's version as the engine resolved it — the same value that goes into
	// its cache key, so the evidence and the cache cannot disagree about what ran. Empty when the
	// scanner does not report one.
	Version string `json:"version,omitempty"`
	// Fields are the scanner's own statements about the run, in the order it considers useful.
	//
	// Untyped, because the interesting ones are domain knowledge — "benchmark", "coverage",
	// "scope" — and this package is the finding currency for every scanner Draugr will ever
	// have. It should not learn what a CIS benchmark is to carry the fact that one was applied.
	Fields []Field `json:"fields,omitempty"`
}

type Report struct {
	Tool    string   `json:"tool,omitempty"`
	Results []Result `json:"results"`
	// Rules is the metadata the scanner published about the rules it applied, keyed by rule id.
	// A result names its rule; the rule is what explains it. Carrying this through is what lets
	// a reader — in a terminal, an editor, or a pull request — find out what "DS-0002" means.
	// Not every scanner publishes it, so entries may be missing.
	Rules map[string]Rule `json:"rules,omitempty"`
	// Provenance is what the scanners said about the run itself, as opposed to what they found:
	// which standard was applied, how much of it could be decided, what the scan was scoped to.
	//
	// A finding answers "what is wrong". Evidence also has to answer "what was measured, and
	// against what" — and that was not recorded anywhere, so a compliance report could not say
	// which benchmark produced it. One entry per tool run; see Provenance.
	Provenance []Provenance `json:"provenance,omitempty"`
}

type Result struct {
	// Tool is the scanner that produced the finding.
	Tool     string   `json:"tool,omitempty"`
	RuleID   string   `json:"ruleId"`
	Level    Level    `json:"level"`
	Message  string   `json:"message"`
	Location Location `json:"location,omitempty"`
	// Score is the finding's numeric CVSS-style severity (0–10), sourced from the SARIF
	// "security-severity" property. HasScore reports whether a score was present; without
	// one, normalized Severity falls back to Level.
	Score    float64 `json:"score,omitempty"`
	HasScore bool    `json:"-"`
	// Priority is the computed action band (P1–P4) for this finding, stamped by the engine
	// from the component's risk classification. Empty when prioritization is not configured.
	Priority string `json:"priority,omitempty"`
	// Component names the part of the application this finding belongs to, stamped by the engine
	// from the component whose scan produced it. Empty for a project-scoped control, which has
	// no one component to attribute to.
	//
	// A location alone is ambiguous the moment a descriptor has two components: three components
	// have three go.mod files, and two can carry the same path. It is also what makes the
	// priority checkable — the band is computed from the component's declared exposure and
	// criticality, so a report showing the band without naming the component states a conclusion
	// and withholds its premise.
	Component string `json:"component,omitempty"`
	// Suppression is set when a Saga exclusion matched this finding. A suppressed result is
	// reported but not counted: it does not reach Counts, the verdict, or the fix-first list.
	// Nil for an active finding.
	Suppression *Suppression `json:"suppression,omitempty"`
}

type Rule struct {
	// Name is a human-readable identifier (SARIF reportingDescriptor.name), where the id
	// itself is opaque.
	Name string `json:"name,omitempty"`
	// ShortDescription is a single sentence; FullDescription is a paragraph.
	ShortDescription string `json:"shortDescription,omitempty"`
	FullDescription  string `json:"fullDescription,omitempty"`
	// Help is remediation guidance, often Markdown.
	Help string `json:"help,omitempty"`
	// HelpURI points at the rule's documentation or advisory.
	HelpURI string `json:"helpUri,omitempty"`
}

type Severity string

type Suppression struct {
	// Kind is the SARIF suppression kind. Draugr writes "external": the decision came from the
	// Saga, not from an annotation in the source.
	Kind string `json:"kind"`
	// Justification is the reason the Saga gave. Required by Draugr even though SARIF allows
	// it to be absent.
	Justification string `json:"justification"`
	// AcceptedBy is who decided this was acceptable, when the exclusion said. Empty means the
	// suppression is unattributed — reported as such, because "who decided" is half the question
	// an auditor is asking and a blank is an answer worth seeing.
	AcceptedBy string `json:"acceptedBy,omitempty"`
	// Expires is when the acceptance lapses, as YYYY-MM-DD. Empty means it does not.
	Expires string `json:"expires,omitempty"`
}