review

type Agent interface {
	Run(ctx context.Context, req AgentRequest) (*AgentResult, error)
}

type AgentRequest struct {
	// Name identifies the session in an error message.
	Name string
	// Prompt is the whole of what the session is told: a review session has
	// no separate system prompt, because codex takes none.
	Prompt string
	// Dir is the directory the session runs in, which is what its
	// read-only tools can reach. It must be a directory the review is
	// willing to have read: the checkout of the repository under review, or
	// an empty one.
	Dir string
	// ResumeID continues an earlier session of this agent (AgentResult.ID)
	// instead of starting one, for the triage action that asks an angle a
	// follow-up question. Claude and codex (through thread/resume) honour
	// it.
	ResumeID string
}

type AgentResult struct {
	// ID is the agent's own id for the session, which resumes it later.
	ID string
	// Text is the session's last message, which is what it was asked for.
	Text string
	// Turns is how many turns it took, and CostUSD what it cost when the
	// CLI reported one, which CostKnown says: codex reports none, so its
	// cost is unknown rather than zero.
	Turns     int
	CostUSD   float64
	CostKnown bool
	// Provider and Model are the agent that answered, when the
	// implementation says: one that fell back to another agent reports that
	// one, so the run records the session that exists and Resume knows what
	// to reopen it with. Empty keeps what the angles were configured with.
	Provider string
	Model    string
}

type AngleEvent string

type AngleRun struct {
	// Angle is the angle the session reviewed from, a name in
	// BuiltinAngles.
	Angle string `json:"angle"`
	// Provider and Model are the agent the session ran as. A session is
	// reopened by the same agent: another provider does not know its id.
	Provider string `json:"provider"`
	Model    string `json:"model,omitempty"`
	// Dir is where the session ran, retained for caller-owned resumption.
	Dir string `json:"dir"`
	// SessionID is the agent's own id for the session, which Resume gives
	// back to it. It is empty for a session that failed.
	SessionID string `json:"session_id,omitempty"`
	// Answer is what the session said last, as it said it: the findings it
	// was asked for, in the JSON shape the prompt describes. Reading them
	// into findings is the judge's job (judge.go), not this file's.
	Answer string `json:"answer,omitempty"`
	// Turns is how many turns the session took and CostUSD what it cost,
	// when the CLI reported one; CostUnknown says it reported none.
	Turns       int     `json:"turns,omitempty"`
	CostUSD     float64 `json:"cost_usd,omitempty"`
	CostUnknown bool    `json:"cost_unknown,omitempty"`
	// Error is what the session failed with, and "" for one that finished.
	// A session that answered that it could not read its input has failed
	// too, and keeps that answer beside the error. A failed angle is kept
	// with the rest so the review can say which angle nobody looked from.
	Error string `json:"error,omitempty"`
}

type Angles[R Reference] struct {
	// Agent runs the sessions; Provider and Model say which agent it is,
	// which is what every run records so it can be reopened by the same
	// one.
	Agent    Agent
	Provider string
	Model    string
	// Sized replaces the built-in angles of each size it names (sizeAngles),
	// a size it leaves out keeps the built-in list.
	Sized map[string][]string
	// Prepare optionally supplies the session directory. The caller owns any
	// acquisition; nil uses Dir or a persistent scratch directory.
	Prepare func(context.Context, string) (string, error)
	// AgentFor optionally selects an agent and recorded model per angle.
	// It is called concurrently; profile construction belongs to the caller.
	AgentFor func(angle string) (Agent, string)
	// ProviderFor optionally selects the provider recorded for an angle. Both
	// callbacks must be safe for concurrent calls; nil retains Provider.
	ProviderFor func(angle string) string
	// Dir is an existing working directory, used when Prepare is nil.
	// Core does not write the diff into this caller-owned directory.
	// With no directory, sessions use a persistent scratch directory.
	Dir string
	// Log receives angle-selection diagnostics, and is silent when nil.
	Log io.Writer
	// Rules are the reviewer notes' rules (policy.go), read by whoever runs
	// the review: the ones that name the repository under review and the
	// angle become the part of that angle's prompt saying what has been
	// dismissed from it before. A person who has dismissed nothing has
	// none, and their sessions are told nothing extra.
	Rules []Rule
	// Progress is told how each angle's session is going, for a display to
	// draw while the angles run: AngleStarted the moment before the
	// session starts, and AngleFinished or AngleFailed the moment it ends.
	// It is called from the goroutine of the angle it is about, so calls
	// arrive at once from several angles and it has to be safe to call
	// concurrently. Nil is told nothing, and costs nothing.
	Progress func(angle string, event AngleEvent)
}

type Artifact[R Reference] struct {
	// Dir is the directory.
	Dir string
	// Brief is the brief, which every artifact has: a directory without one
	// is not a review.
	Brief *Brief[R]
	// Runs are the angle runs, in BuiltinAngles order, and none for a
	// review whose angles have not run. They are the angles Brief.Size
	// called for that the project enabled (anglesFor), each one run whether
	// it finished or failed: an angle with no run is one the size did not
	// call for, or one the project turned off.
	Runs []AngleRun
	// Findings is the judge's list, and nil for a review not judged yet.
	Findings *Findings
	// Triage is what triage decided, and nil for a review not triaged yet.
	Triage *Triage
}

type Brief[R Reference] struct {
	// Ref identifies the change under review; Title and Author are supplied
	// by the caller. All three come from the bundle.
	Ref    R      `json:"ref"`
	Title  string `json:"title,omitempty"`
	Author string `json:"author,omitempty"`

	// Summary is what the change does, in the distiller's words.
	Summary string `json:"summary"`
	// Size is how large the change is, one of Sizes, as the distiller
	// judged it from the change's scope (the files and lines it touches,
	// the generated files in Excluded not among them) and its risk (which
	// parts of the project those are).
	Size string `json:"size"`
	// AcceptanceCriteria are what the change says it does: the criteria of
	// the issues it closes, the promises of its own description.
	AcceptanceCriteria []Point `json:"acceptance_criteria,omitempty"`
	// StyleRules are the rules the project's own style sources put on a
	// change like this one, the ones that apply and not the whole of what
	// the files say.
	StyleRules []Point `json:"style_rules,omitempty"`
	// TouchedAreas are the parts of the project the change touched.
	TouchedAreas []TouchedArea `json:"touched_areas,omitempty"`

	// Sources are the context sources the bundle was gathered from, and
	// NotGathered what those sources could not read (Bundle.Skipped), so a
	// session reading the brief knows what nobody looked at.
	Sources     []string `json:"sources,omitempty"`
	NotGathered []string `json:"not_gathered,omitempty"`
	// Excluded are the generated files the caller took out of the diff
	// before the distiller read it (Bundle.Excluded): what the change did
	// there is not in the size, and a finding anchored there is dropped. A
	// brief written before there were any reads back with none.
	Excluded []ExcludedFile `json:"excluded,omitempty"`
	// SessionID is the distiller session's own id, which is what a later
	// session would be resumed from, and CostUSD what that session cost
	// when the CLI reported a cost (AgentResult.CostUSD): what the factory
	// counts against its budgets, since the distiller is no session of its
	// own runner. CostUnknown says the CLI reported none.
	SessionID   string  `json:"session_id,omitempty"`
	CostUSD     float64 `json:"cost_usd,omitempty"`
	CostUnknown bool    `json:"cost_unknown,omitempty"`
}

type Bundle[R Reference] struct {
	Ref     R        `json:"ref"`
	Title   string   `json:"title,omitempty"`
	Author  string   `json:"author,omitempty"`
	Items   []Item   `json:"items"`
	Skipped []string `json:"skipped,omitempty"`
	// Excluded are the generated files the caller took out of the diff,
	// which is the diff the items hold and the sessions read.
	Excluded []ExcludedFile `json:"excluded,omitempty"`
}

type Comparator func(title, body, otherTitle, otherBody string) bool

type Decision struct {
	// Finding is the id of the finding (Finding.ID).
	Finding string `json:"finding"`
	// Action is the action taken on it.
	Action string `json:"action"`
	// Reason is why, for an action that records one.
	Reason string `json:"reason,omitempty"`
	// Comment is the text the finding is posted as, when triage edited it.
	Comment string `json:"comment,omitempty"`
	// Question and Answer are what an ask asked the angle and what the
	// angle answered, and Added the ids of the findings the answer turned
	// up that the review did not have.
	Question string   `json:"question,omitempty"`
	Answer   string   `json:"answer,omitempty"`
	Added    []string `json:"added,omitempty"`
}

type Distiller[R Reference] struct {
	// Agent runs the session.
	Agent Agent
	// Dir is the checkout of the repository under review, which the
	// session's read-only tools can reach. It is "" on a machine that has
	// none, and the session then runs in an empty
	// directory of its own: a review must not read whichever repository the
	// command happened to be run in.
	Dir string
}

type ExcludedFile struct {
	Path    string `json:"path"`
	Added   int    `json:"added"`
	Removed int    `json:"removed"`
	Reason  string `json:"reason,omitempty"`
}

type Finding struct {
	// ID names the finding in triage. It is the first eight hex digits of
	// the SHA-256 of the file, side, lines and title, so it is the same on
	// every merge of the same findings and never repeats across the
	// findings one session adds after another.
	ID string `json:"id"`
	// Angle is the angle that found it, a name in BuiltinAngles, and
	// SessionID that angle's session (AngleRun.SessionID), which is what
	// the ask action resumes with a question about it.
	Angle     string `json:"angle"`
	SessionID string `json:"session_id,omitempty"`
	// Category is the kind of problem, in the angle's own word or two,
	// lowercased: "naming", "missing test". A project pins a category's
	// severity by this name (Settings.Severity).
	Category string `json:"category"`
	// Severity is one of SeverityInfo, SeverityLow, SeverityMedium and
	// SeverityHigh, after the judge has normalised what the session said
	// and applied the project's pins. Never SeverityOff: a finding in a
	// category pinned off is dropped, not kept.
	Severity string `json:"severity"`
	// File, Lines and Side anchor the finding to the diff: the path in the
	// repository, the lines in it, and which side of the change they are
	// on. A finding about the change as a whole has none of them.
	File  string    `json:"file,omitempty"`
	Lines LineRange `json:"lines,omitzero"`
	Side  string    `json:"side,omitempty"`
	// Title is the finding in one line and Body what is wrong and why it
	// matters, in the two or three sentences prompts/angle.md asks for:
	// what is posted on the lines, where Evidence is not.
	Title string `json:"title"`
	Body  string `json:"body"`
	// Suggestion is the text that would replace the lines, when the angle
	// could write it.
	Suggestion string `json:"suggestion,omitempty"`
	// Evidence is what the angle read that shows the problem. Triage shows
	// it after the body; a posted review and a report leave it out.
	Evidence string `json:"evidence,omitempty"`
	// Sources are where the rule or the requirement the finding is about
	// was read: "#12", "CONTRIBUTING.md".
	Sources []string `json:"sources,omitempty"`
	// AlsoFrom names the other angles that reported the same finding, when
	// the judge merged theirs into this one.
	AlsoFrom []string `json:"also_from,omitempty"`
}

type Findings struct {
	// Items are the findings, deduplicated, severity-normalised, most
	// severe first. Empty for a change with nothing wrong.
	Items []Finding `json:"findings"`
	// Skipped names failed sessions and answers ParseFindings could not read,
	// each with why. Missing or null findings lists are successful empty
	// results and are not skipped.
	Skipped []string `json:"skipped,omitempty"`
	// Silenced are the findings the reviewer notes acted on (noise.go): the
	// ones a rule kept out of Items, and the ones it let through one
	// severity lower. It is what a review answers "what did my notes hide"
	// with, and empty for a review nothing was hidden from.
	Silenced []Silenced `json:"silenced,omitempty"`
}

type Item struct {
	// Source is the caller-supplied name of the source that produced the item.
	Source string `json:"source"`
	// Name says which piece it is, in whatever way the source names its
	// own: a path, a change reference, a symbol.
	Name string `json:"name"`
	// Content is the text, as it was read.
	Content string `json:"content"`
}

type LineRange struct {
	Start int `json:"start"`
	End   int `json:"end"`
}

type Point struct {
	Text string `json:"text"`
	// Source is where the statement was read, in the distiller's words:
	// "#567", "CLAUDE.md", "the pull request body". It is empty when the
	// distiller named none.
	Source string `json:"source,omitempty"`
}

type Reference interface {
	fmt.Stringer
	URL() string
	ReviewScope() string
}

type Rule struct {
	// Scope, Angle and Category are what the finding must be to match, each
	// one anyValue or empty for "whatever it is".
	Scope    string
	Angle    string
	Category string
	// Action is RuleDrop or RuleDownrank.
	Action string
	// Text is the dismissal reason the rule was made from, which a finding's
	// title is compared against. A rule with no text matches every finding
	// its repo, angle and category match: that is how a whole category is
	// silenced.
	Text string
	// Count is how many dismissals the rule was made from, refreshed by
	// every consolidation. It says how sure a person was, and nothing reads
	// it back.
	Count int
}

type Runner[R Reference] struct {
	Distiller   *Distiller[R]
	Angles      *Angles[R]
	Settings    *Settings
	Rules       []Rule
	Compare     Comparator
	Log         io.Writer
	Progress    func(string, AngleEvent)
	AnglesReady func([]string)
}

type Settings struct {
	Angles     map[string]bool
	Categories map[string]string
}

type Silenced struct {
	// ID, Title, Angle and Category are the finding's, as it was when the
	// rule matched.
	ID       string `json:"id"`
	Title    string `json:"title"`
	Angle    string `json:"angle"`
	Category string `json:"category"`
	// Action is what the rule did: RuleDrop, and the finding is not in the
	// list at all, or RuleDownrank, and it is in it one severity lower.
	Action string `json:"action"`
	// Severity is the severity the finding had before the rule acted.
	Severity string `json:"severity"`
	// Rule is the rule that matched, as the notes file writes it.
	Rule string `json:"rule"`
}

type TouchedArea struct {
	// Name is the area in the project's own terms: a package, a command, a
	// document.
	Name string `json:"name"`
	// Paths are the files the change touched in it.
	Paths []string `json:"paths,omitempty"`
	// Summary is what the change did there.
	Summary string `json:"summary,omitempty"`
}

type Triage struct {
	// Decisions are the decisions taken, in the order they were taken.
	Decisions []Decision `json:"decisions"`
}