review

type Category string

type ChatFocus struct {
	File string // new path, repo-relative, as shown in the diff headers
	Line LineRef
}

type ChatReply struct {
	// Text is the model's answer, GitLab-flavoured markdown.
	Text string
	// SessionID identifies the backend conversation; pass it back in the
	// next ChatRequest to continue with full context.
	SessionID string
	CostUSD   float64
}

type ChatRequest struct {
	// RepoPath is the checkout the chat runs in (the subprocess cwd). It must
	// stay the same across the turns of one conversation: the backend session
	// is resumed from there.
	RepoPath string
	// MR carries metadata shown to the model (title, description, branches).
	MR gitlabx.MRDetail
	// Diffs is the MR's diff set; the prompt builder bounds what is inlined.
	// Only consulted on the first turn.
	Diffs []gitlabx.FileDiff
	// Focus narrows the conversation to one diff line; nil chats about the
	// whole MR.
	Focus *ChatFocus
	// MaxDiffKB bounds the diff inlined into the first turn's prompt; <= 0
	// falls back to a conservative default.
	MaxDiffKB int
	// Message is the user's message for this turn.
	Message string
	// SessionID resumes an earlier conversation; empty starts a new one.
	SessionID string
	// Timeout bounds one turn, not the whole conversation.
	Timeout time.Duration
}

type Chatter interface {
	Chat(ctx context.Context, req ChatRequest, onEvent func(Event)) (*ChatReply, error)
}

type DiffFile struct {
	Path     string // the changed file
	DiffPath string // the file containing its full diff
}

type Event struct {
	Kind EventKind
	Text string
	// Agent is the review agent the event belongs to; empty for run-level
	// events.
	Agent string
}

type EventKind int

type Finding struct {
	ID       string   `json:"id"`
	File     string   `json:"file,omitempty"`     // new path, repo-relative; empty on MR-level manual comments
	OldFile  string   `json:"old_file,omitempty"` // as reported by the model for renames; advisory only
	Line     LineRef  `json:"line,omitzero"`
	Severity Severity `json:"severity,omitempty"`
	Category Category `json:"category,omitempty"`
	// Agent names the review agent that produced the finding. Stamped by the
	// runner, never reported by the model; empty on records from before
	// agents existed and on manual comments.
	Agent      string       `json:"agent,omitempty"`
	Title      string       `json:"title,omitempty"`
	Body       string       `json:"body"`                 // markdown, user-editable
	Suggestion string       `json:"suggestion,omitempty"` // optional replacement for the flagged line
	State      FindingState `json:"state"`
	// Manual marks a comment written by the reviewer in the TUI rather than
	// produced by the model: it publishes verbatim, without the body
	// template or the attribution footer.
	Manual bool `json:"manual,omitempty"`
}

type FindingState int

type LineRef struct {
	OldLine *int `json:"old_line,omitempty"`
	NewLine *int `json:"new_line,omitempty"`
}

type Request struct {
	// RepoPath is the checkout the review runs in (the subprocess cwd).
	RepoPath string
	// MR carries metadata shown to the model (title, description, branches).
	MR gitlabx.MRDetail
	// Diffs is the bounded, pre-filtered set of file diffs to review.
	Diffs []gitlabx.FileDiff
	// Commits are the MR's commits, shown to the model as context (and for
	// commit-message hygiene checks driven via Instructions).
	Commits []gitlabx.Commit
	// Template is the project's default MR description template, shown to the
	// model so instructions can drive a description-vs-template hygiene
	// check. Empty when the project has no template.
	Template string
	// Excluded lists changed files dropped from review by configuration
	// (exclude globs, generated files); shown to the model as context only.
	Excluded []string
	// DiffFiles lists changed files whose diffs were too large to inline;
	// each full diff was written into the checkout for the model to Read.
	DiffFiles []DiffFile
	// Unavailable lists changed files GitLab returned no diff for; the model
	// can only read their state at the head commit.
	Unavailable []string
	// Instructions is extra prompt text: global then per-project.
	Instructions string
	// Categories the running agent may label findings with.
	Categories []Category
	// AgentName identifies the review agent this request runs as; it is set
	// by the runner when specialising a chunk request per selected agent.
	AgentName string
	// AgentPrompt is the agent's persona/focus text, appended to the shared
	// system prompt by the backend.
	AgentPrompt string
	// Incremental marks a delta review: Diffs holds only the changes pushed
	// since LastReviewedSHA (the previous review's head commit) instead of
	// the whole MR diff.
	Incremental     bool
	LastReviewedSHA string

	Model        string
	Timeout      time.Duration
	MaxBudgetUSD float64

	// AllowedDomains grants WebFetch scoped to these domains only, for this
	// request; empty means WebFetch stays fully denied. Mirrors Model's
	// per-request-with-Backend-fallback shape.
	AllowedDomains []string
	// AllowedCommands grants Bash scoped to these command patterns only,
	// for this request; empty means Bash stays fully denied.
	AllowedCommands []string
}

type Result struct {
	Summary   string
	Findings  []Finding
	Warnings  []string // dropped findings, truncation notes
	SessionID string
	CostUSD   float64
	Raw       []byte // raw output for drift debugging; persisted by the caller
	// Agent names the review agent that produced this result, before merging.
	Agent string
}

type Reviewer interface {
	Name() string
	// CheckAvailable verifies the backend can run (binary present, version
	// supported) and returns a user-actionable error otherwise.
	CheckAvailable(ctx context.Context) error
	Review(ctx context.Context, req Request, onEvent func(Event)) (*Result, error)
}

type Severity string

type SkipReason int

type SkippedDiff struct {
	Path    string
	OldPath string
	Reason  SkipReason
	Diff    string // populated for SkipOverBudget so the diff can go on disk
}