report

type CoverageRow struct {
	ControlID string
	// Assurance is "automated", "manual" or "none" — the strongest check
	// behind this control. Where a run recorded its own evidence mode,
	// that wins over the framework's declaration, so a project override
	// is reflected rather than papered over.
	Assurance string
	// AutomatedPolicies and ManualPolicies give the mix the single
	// Assurance label hides: one automated check plus four documents is
	// "automated", and a reader deciding where to spend the next month
	// deserves to see the four.
	AutomatedPolicies int
	ManualPolicies    int
	// Evaluated is how many of this control's policies produced a result
	// in this period; Policies is how many exist.
	Evaluated int
	Policies  int
	// ManagementSystem marks a row as a management-system requirement
	// rather than a selectable catalog control.
	ManagementSystem bool
	// Status is the roll-up over this period's results — the worst of
	// them, or "not evaluated" when there are none.
	Status string
	// Overridden marks a control whose evidence mode the project changed.
	Overridden bool
	// Note explains a row that needs it: why nothing ran, or what an
	// error said.
	Note string
}

type CoverageView struct {
	// Controls/Automated/Manual/Uncovered describe the framework's
	// selectable control catalog and do not vary by period.
	Controls  int
	Automated int
	Manual    int
	Uncovered int

	// ManagementSystem counts the framework's management-system
	// requirements — ISO 27001's clauses 4-10 — and
	// ManagementSystemOnFile how many have their document for this
	// period. They are counted apart from the catalog because blending
	// them flatters the headline exactly as the gap closes: adding
	// sixteen clause requirements that nobody has uploaded yet would
	// otherwise turn "93 of 93 covered" into "109 of 109 covered".
	ManagementSystem       int
	ManagementSystemOnFile int

	// Evaluated counts controls with at least one policy result in this
	// period. NotEvaluated is the rest — see the type doc for why that
	// is routine rather than alarming for a supra-period cadence.
	Evaluated    int
	NotEvaluated int

	// ManualOnFile and ManualMissing split the manual-assurance controls
	// by whether their document actually exists for this period.
	ManualOnFile  int
	ManualMissing int

	// Overridden counts controls a project reconfigured away from the
	// framework's declared evidence mode — nearly always an automated
	// check downgraded to a document upload.
	Overridden int

	// Rows is one entry per declared control, sorted by control ID.
	Rows []CoverageRow
}

type ExceptionEntry struct {
	PolicyID       string
	State          string
	Scope          string // resource_id, resource_pattern, or "policy"
	ApprovedBy     string
	ApprovedAt     string
	ExpiresAt      string
	Reason         string
	FirstSeenRunID string
	LastSeenRunID  string
}

type ExceptionsView struct {
	Exceptions []ExceptionEntry
}

type Input struct {
	Vault     core.Vault
	Framework string
	PeriodID  string
	View      View

	// Controls and Policies are the framework's catalog, resolved by the
	// command layer and passed in so this package never imports
	// internal/frameworks — Build stays a reader of vault bytes plus
	// whatever its caller hands it. Required by the coverage view, which
	// must name controls that produced no result at all; ignored by
	// every other view.
	Controls []core.Control
	Policies []core.Policy

	// ControlConfigs carries the project's per-control applicability
	// decisions, keyed by control ID — the half of a Statement of
	// Applicability that lives in .sigcomply.yaml rather than in the
	// vault or the framework. Only the soa view reads it.
	//
	// This is the package's one import of internal/spec, and a
	// deliberate exception to its "pure reader of vault bytes"
	// property: an applicability decision is authored, not observed, so
	// there is nowhere in the vault to read it from. spec is a
	// dependency-free leaf, so the coupling is narrow and acyclic —
	// unlike internal/frameworks, which this package still must not
	// import.
	ControlConfigs map[string]spec.ControlConfig
}

type IntegrityRow struct {
	RunPath           string
	RunID             string
	CompletedAt       time.Time
	SignatureValid    bool
	FilesVerified     int
	FilesTotal        int
	FirstMismatchPath string
	Error             string // populated when SignatureValid is false or a file is missing
}

type IntegrityView struct {
	Runs []IntegrityRow
}

type LatestPolicy struct {
	PolicyID      string
	ControlID     string
	Status        string
	Severity      string
	Category      string
	LastEvaluated time.Time
	RunID         string
	// ExceptionID, when non-empty, points at the policy_id of the
	// exception that suppressed this result (waived/na). The free-CLI
	// design uses the policy_id as the exception's primary key — the
	// exceptions view is the place to look up details.
	ExceptionID string
	// Reason is the one-line explanation for a fail or error, the same
	// projection `check` prints inline. Empty for a plain pass. Without
	// it this view showed a bare "error" with the diagnostic stranded in
	// the vault's result.json, which is the least useful place for it.
	// Full detail still lives there.
	Reason string
}

type LatestView struct {
	Policies []LatestPolicy
}

type ScopeSource struct {
	SourceID string
	State    string
}

type ScopeView struct {
	// Declared reports whether the run carried an estate declaration.
	// False for runs written before scope existed, and for projects that
	// have not opted in.
	Declared bool
	// Status is the run-level verdict: complete, incomplete, or empty
	// when nothing was declared.
	Status string
	// DeclaredBy/DeclaredAt are the operator's audit trail.
	DeclaredBy string
	DeclaredAt string
	// RunID is the run this verdict came from — the latest in the period.
	RunID string

	// Sources is one row per declared source, sorted by ID.
	Sources []ScopeSource
	// Skipped is one row per unevaluated control, sorted by policy ID.
	Skipped []SkippedPolicy
}

type SkippedPolicy struct {
	PolicyID string
	Status   string
	Reason   string
}

type Snapshot struct {
	View      View
	Framework string
	PeriodID  string

	Latest     *LatestView     `json:",omitempty"`
	Exceptions *ExceptionsView `json:",omitempty"`
	Integrity  *IntegrityView  `json:",omitempty"`
	Scope      *ScopeView      `json:",omitempty"`
	Coverage   *CoverageView   `json:",omitempty"`
	SoA        *SoAView        `json:",omitempty"`
}

type SoARow struct {
	ControlID string
	Name      string

	// Applicable is false only where the project declared the control
	// not_applicable.
	Applicable bool

	// Justification is the organization's reason for including the
	// control, or — for an excluded one — its reason for leaving it out.
	// JustificationDerived says SigComply wrote it rather than the
	// operator.
	Justification        string
	JustificationDerived bool

	// Status is "implemented", "partially implemented", "not
	// implemented", "not evaluated" or "excluded". It is derived from
	// this period's results and never from the catalog: a control whose
	// checks did not run is reported as unevaluated, not as passing.
	Status string

	// Assurance is "automated", "manual" or "none" — the strongest check
	// behind the control. An implemented control evidenced only by a
	// document on file is a weaker claim than one where infrastructure
	// was inspected, and the SoA should not flatten the two.
	Assurance string

	// Evaluated is how many of this control's policies produced a result
	// in this period; Policies names them all.
	Evaluated int
	Policies  []string

	// ApprovedBy carries the project config's approver for the
	// applicability decision, where one is recorded.
	ApprovedBy string
}

type SoAView struct {
	// Controls is the number of catalog controls — the rows below.
	// ManagementSystem is what was deliberately left out.
	Controls         int
	ManagementSystem int

	// Applicable and Excluded split the catalog by the project's
	// applicability decisions.
	Applicable int
	Excluded   int

	// Implemented, Partial, NotImplemented and NotEvaluated split the
	// applicable controls by what this period's results showed. They sum
	// to Applicable.
	Implemented    int
	Partial        int
	NotImplemented int
	NotEvaluated   int

	// Derived counts applicable controls whose inclusion justification
	// SigComply wrote rather than the organization. Surfaced because the
	// difference matters to a reader: a derived justification is
	// accurate but says nothing about why this organization kept the
	// control.
	Derived int

	// Rows is one entry per catalog control, sorted by control ID.
	Rows []SoARow

	// Note names what the table omits and what its statuses do not mean.
	Note string
}

type View string