schema

type CacheMeta struct {
	// Hit is true when the review was read from the cache and no model was
	// called; false when it was produced now and stored.
	Hit bool `json:"hit"`
	// Key identifies the stored review.
	Key string `json:"key"`
	// StoredAt is when a cached review was produced.
	StoredAt string `json:"stored_at,omitempty"`
}

type Category string

type CompletionMeta struct {
	Enabled            bool   `json:"enabled"`
	Mode               string `json:"mode"`
	Template           string `json:"template"`
	GeneratedPatches   int    `json:"generated_patches"`
	SkippedSuggestions int    `json:"skipped_suggestions"`
	OpenDecisions      int    `json:"open_decisions"`
}

type ConvergenceCounts struct {
	New       int `json:"new"`
	StillOpen int `json:"still_open"`
	Resolved  int `json:"resolved"`
	Dropped   int `json:"dropped"`
	Untracked int `json:"untracked"`
}

type ConvergenceCurrentCounts struct {
	New       int `json:"new"`
	StillOpen int `json:"still_open"`
	Untracked int `json:"untracked"`
}

type ConvergenceHistoricalCounts struct {
	Resolved  int `json:"resolved"`
	Dropped   int `json:"dropped"`
	Untracked int `json:"untracked"`
}

type ConvergenceMeta struct {
	Enabled          bool                         `json:"enabled"`
	Mode             string                       `json:"mode"`
	Status           string                       `json:"status"`
	PreviousSpecHash string                       `json:"previous_spec_hash"`
	CurrentSpecHash  string                       `json:"current_spec_hash"`
	Current          ConvergenceCurrentCounts     `json:"current"`
	Previous         ConvergenceHistoricalCounts  `json:"previous"`
	BySeverity       map[string]ConvergenceCounts `json:"by_severity"`
	ByKind           map[string]ConvergenceCounts `json:"by_kind"`
	Notes            []string                     `json:"notes"`
}

type Evidence struct {
	Path      string `json:"path"`
	LineStart int    `json:"line_start"`
	LineEnd   int    `json:"line_end"`
	Quote     string `json:"quote"`
}

type IncrementalMeta struct {
	Enabled          bool    `json:"enabled"`
	PreviousSpecHash string  `json:"previous_spec_hash"`
	Mode             string  `json:"mode"`
	Fallback         bool    `json:"fallback"`
	ReviewedSections int     `json:"reviewed_sections"`
	ReusedSections   int     `json:"reused_sections"`
	ReusedIssues     int     `json:"reused_issues"`
	ReusedQuestions  int     `json:"reused_questions"`
	DroppedFindings  int     `json:"dropped_findings"`
	ChangedLineRatio float64 `json:"changed_line_ratio"`
}

type Input struct {
	SpecFile          string   `json:"spec_file"`
	SpecHash          string   `json:"spec_hash"` // SHA-256 of the original file, computed before redaction
	ContextFiles      []string `json:"context_files"`
	Profile           string   `json:"profile"`
	Strict            bool     `json:"strict"`
	SeverityThreshold string   `json:"severity_threshold"`
}

type Issue struct {
	ID             string     `json:"id"`
	Severity       Severity   `json:"severity"`
	Category       Category   `json:"category"`
	Title          string     `json:"title"`
	Description    string     `json:"description"`
	Evidence       []Evidence `json:"evidence"`
	Impact         string     `json:"impact"`
	Recommendation string     `json:"recommendation"`
	Blocking       bool       `json:"blocking"`
	Tags           []string   `json:"tags"`
}

type Meta struct {
	Model string `json:"model"`
	// Temperature appears only in reports written by older versions. Current
	// models do not accept a sampling temperature, so none is sent or recorded.
	//
	// Deprecated: never set.
	Temperature float64 `json:"temperature,omitempty"`
	// Effort is the reasoning effort requested with --effort. It is omitted
	// when the provider's default was used.
	Effort string `json:"effort,omitempty"`
	// DroppedFindings counts model findings that failed local validation and
	// were left out of the report.
	DroppedFindings int `json:"dropped_findings,omitempty"`
	// Usage totals the LLM calls behind this report. It is omitted when the
	// review made none.
	Usage *UsageMeta `json:"usage,omitempty"`
	// Synthesis records what the cross-section pass of a chunked review did
	// to the chunk findings. It is omitted when no synthesis ran.
	Synthesis *SynthesisMeta `json:"synthesis,omitempty"`
	// Cache says whether this review came from the review cache. It is
	// omitted when the cache was not used.
	Cache *CacheMeta `json:"cache,omitempty"`
	// Verification records the second look given to CRITICAL findings. It is
	// omitted when there was nothing to check or verification was off.
	Verification *VerificationMeta `json:"verification,omitempty"`
	Incremental  *IncrementalMeta  `json:"incremental,omitempty"`
	Convergence  *ConvergenceMeta  `json:"convergence,omitempty"`
	Completion   *CompletionMeta   `json:"completion,omitempty"`
}

type Patch struct {
	IssueID string `json:"issue_id"`
	Before  string `json:"before"`
	After   string `json:"after"`
}

type Question struct {
	ID        string     `json:"id"`
	Severity  Severity   `json:"severity"`
	Question  string     `json:"question"`
	WhyNeeded string     `json:"why_needed"`
	Blocks    []string   `json:"blocks"`
	Evidence  []Evidence `json:"evidence"`
}

type RemovedFinding struct {
	Title    string   `json:"title"`
	Severity Severity `json:"severity"`
	// Category is empty for a question.
	Category Category `json:"category,omitempty"`
	Reason   string   `json:"reason"`
	// AnsweredBy is the spec text that answers the finding. Its quote was
	// found in the spec before the finding was removed.
	AnsweredBy Evidence `json:"answered_by"`
}

type Report struct {
	Tool      string     `json:"tool"`
	Version   string     `json:"version"`
	Input     Input      `json:"input"`
	Summary   Summary    `json:"summary"`
	Issues    []Issue    `json:"issues"`
	Questions []Question `json:"questions"`
	Patches   []Patch    `json:"patches"`
	Meta      Meta       `json:"meta"`
}

type Severity string

type Summary struct {
	Verdict       Verdict `json:"verdict"`
	Score         int     `json:"score"`
	CriticalCount int     `json:"critical_count"`
	WarnCount     int     `json:"warn_count"`
	InfoCount     int     `json:"info_count"`
}

type SynthesisMeta struct {
	// MergedFindings counts chunk findings folded into another finding that
	// reports the same defect.
	MergedFindings int `json:"merged_findings"`
	// Retracted lists findings removed because the spec answers them.
	Retracted []RemovedFinding `json:"retracted,omitempty"`
	// IgnoredRetractions counts retractions that were not applied: the
	// finding was unknown or came from preflight, or the quoted answer is not
	// in the spec.
	IgnoredRetractions int `json:"ignored_retractions,omitempty"`
}

type UsageMeta struct {
	// Calls counts every request sent, including repair and continuation calls.
	Calls              int `json:"calls"`
	RepairCalls        int `json:"repair_calls"`
	ContinuationCalls  int `json:"continuation_calls"`
	TruncatedResponses int `json:"truncated_responses"`
	// SchemaEnforcedCalls counts calls whose response the provider constrained
	// to the output schema. Fewer than Calls means the model or the
	// --structured-output setting left some responses unconstrained.
	SchemaEnforcedCalls int `json:"schema_enforced_calls"`
	// RetriedRequests counts requests resent after a transient failure, such
	// as a rate limit or an overloaded provider.
	RetriedRequests  int `json:"retried_requests,omitempty"`
	InputTokens      int `json:"input_tokens"`
	OutputTokens     int `json:"output_tokens"`
	CacheReadTokens  int `json:"cache_read_tokens"`
	CacheWriteTokens int `json:"cache_write_tokens"`
	// CallDurationMS adds up the time spent inside calls; with concurrent
	// chunk calls it exceeds WallDurationMS, which runs from the start of the
	// first call to the end of the last.
	CallDurationMS int64 `json:"call_duration_ms"`
	WallDurationMS int64 `json:"wall_duration_ms"`
}

type Verdict string

type VerificationMeta struct {
	// Status is "complete", or "failed" when the call did not return
	// usable verdicts; the findings then stand as they were.
	Status string `json:"status"`
	// Error explains a failed verification.
	Error string `json:"error,omitempty"`
	// Checked counts the findings put to the model.
	Checked    int `json:"checked"`
	Confirmed  int `json:"confirmed"`
	Downgraded int `json:"downgraded"`
	// Rejected lists findings removed, with the spec text that shows each is
	// wrong. The quote was found in the spec before the finding was removed.
	Rejected []RemovedFinding `json:"rejected,omitempty"`
	// UnverifiedRejections counts rejections whose quote is not in the spec.
	// Those findings were kept as CRITICAL.
	UnverifiedRejections int `json:"unverified_rejections,omitempty"`
	// Unanswered counts checked findings the model returned no verdict for.
	// They keep their severity.
	Unanswered int `json:"unanswered,omitempty"`
	// Unchecked counts CRITICAL findings beyond the per-call limit, or all of
	// them when the call failed. They keep their severity.
	Unchecked int `json:"unchecked,omitempty"`
}