assay

type Config struct {
	// ModelTier is a semantic label describing the desired model strength
	// (e.g. "default", "fast"). It is recorded for observability and may be
	// surfaced to operators; the concrete model identifiers are always the
	// TriageModel/ReviewModel hints below, never a literal baked into the code.
	ModelTier string

	// TriageProvider and ReviewProvider are provider specs (the same syntax as
	// settings.providers, e.g. "claude", "gemini/gemini-2.5-pro"). Empty
	// defaults to the Claude provider. TriageProvider drives the cheap scoping
	// pass; ReviewProvider drives the five deep passes.
	TriageProvider string
	ReviewProvider string

	// TriageModel and ReviewModel are model hints (provider-specific model
	// identifiers) used for the triage pass and the deep passes respectively.
	// Empty means "let the provider pick its default model".
	TriageModel string
	ReviewModel string

	// NitCap caps the number of Nit-severity findings retained after
	// aggregation. Values <= 0 mean "no cap".
	NitCap int

	// ShadowMode, when true, signals that the review must not produce public
	// side effects: Review still writes findings to pr_findings, but the caller
	// must not post them. Defaults to the safe value (true) via FromAssayConfig.
	ShadowMode bool

	// MaxDiffBytes caps the size of the diff embedded in pass prompts. Values
	// <= 0 fall back to diff.MaxBytes.
	MaxDiffBytes int

	// SkipPaths are doublestar globs whose files are excluded from review
	// (their hunks are dropped before the diff reaches any pass).
	SkipPaths []string

	// AutoGeneratedPatterns are doublestar globs whose hunks are filtered out
	// before review (machine-generated snapshots, etc.). Empty uses
	// diff.AutoGeneratedPatterns.
	AutoGeneratedPatterns []string
	// contains filtered or unexported fields
}

type ExistingFinding struct {
	Anchor string
	Body   string
}

type Finding struct {
	// File is the affected file path (b-side path from the diff).
	File string `json:"file"`
	// Anchor locates the finding within the file (e.g. "path/to/file.go:42").
	Anchor string `json:"anchor"`
	// Category is a short machine label for the kind of issue (defaults to the
	// emitting pass name when the model omits it).
	Category string `json:"category"`
	// Severity is the triaged seriousness of the finding.
	Severity Severity `json:"severity"`
	// Title is a one-line summary.
	Title string `json:"title"`
	// Body is the full explanation.
	Body string `json:"body"`
	// Evidence is an optional supporting snippet (diff lines, etc.).
	Evidence string `json:"evidence"`
	// SourcePass records which pass produced the finding.
	SourcePass string `json:"-"`
	// Hash is the dedup key: sha256(anchor + category + canonical(body)).
	// Computed by the engine, not the model.
	Hash string `json:"-"`
}

type PassOutput struct {
	// Text is the model's textual response (parsed for JSON downstream).
	Text string
	// CostUSD is the estimated cost of the invocation.
	CostUSD float64
}

type PassProvider struct {
	// Pass is the pass identifier ("triage", "logic", "security", …).
	Pass string
	// Provider is the resolved provider (Kind/Cmd/Model) for the pass, derived
	// from the Config's per-tier provider/model hints.
	Provider provider.Provider
}

type PassReport struct {
	// Name is the pass identifier (e.g. "logic").
	Name string
	// Findings is the number of findings the pass contributed before
	// aggregation.
	Findings int
	// CostUSD is the model cost attributed to the pass.
	CostUSD float64
}

type PassRunner func(ctx context.Context, pass, tier, prompt string) (PassOutput, error)

type PostRequest struct {
	// Anvil is the repository (anvil) name; keys the persisted rows.
	Anvil string
	// PRNumber is the pull request to comment on.
	PRNumber int
	// HeadSHA is the commit the inline comments are anchored to (commit_id).
	HeadSHA string
	// WorktreePath is the directory gh commands run in (the PR worktree). gh
	// resolves the {owner}/{repo} API placeholders from this checkout.
	WorktreePath string
	// SummaryLine is the one-line verdict shown above the severity table in the
	// top-level review comment. When empty (and there are no findings) the
	// summary review is skipped.
	SummaryLine string
	// Findings is the aggregated set to post (already deduped/suppressed/capped
	// by Review).
	Findings []Finding
}

type PostResult struct {
	// SummaryPosted reports whether the top-level review comment was posted.
	SummaryPosted bool
	// Posted is the number of inline comments successfully posted.
	Posted int
	// Failed is the number of inline comments whose gh call failed (left with
	// posted=0 so they retry on the next head).
	Failed int
	// Resolved is the number of stale findings whose threads were resolved
	// after crossing the consecutive-miss threshold.
	Resolved int
}

type Poster struct {
	// contains filtered or unexported fields
}

type ReviewRequest struct {
	// Anvil is the repository (anvil) name; used to key persisted rows.
	Anvil string
	// AnvilPath is the local checkout path, used to read repo-level context
	// (REVIEW.md, AGENTS.md, etc.). Optional — may be empty. When set and
	// RepoGuidance is empty, Review() reads <AnvilPath>/REVIEW.md into
	// RepoGuidance once per run so every pass sees the same trusted guidance.
	AnvilPath string
	// RepoGuidance carries the repository's REVIEW.md content (or any
	// equivalent trusted instructions) injected into every pass prompt at
	// highest priority. Optional — empty means the engine uses default
	// calibration only. Pre-populated by Review() from AnvilPath when unset.
	RepoGuidance string
	// PRNumber is the pull request number under review.
	PRNumber int
	// HeadSHA is the PR head commit OID. It is the idempotency key: findings are
	// recorded against this SHA and a repeat review of the same SHA is a no-op.
	HeadSHA string
	// Diff is the unified git diff to review.
	Diff string
	// BeadID is the originating bead, used for context/logging. Optional.
	BeadID string
	// Title is the PR/bead title, supplied to passes as scope context. Optional.
	Title string
	// Description is the PR/bead body, supplied as scope context. Optional.
	Description string
	// WorkDir is the directory the default Smith-based runner executes in
	// (typically the PR worktree). Ignored when a custom runner is installed.
	WorkDir string
}

type ReviewResult struct {
	// Findings is the final, aggregated set (deduped, suppressed, capped).
	Findings []Finding
	// HeadSHA echoes the reviewed head SHA.
	HeadSHA string
	// ShadowMode reports whether the review ran in shadow mode (no posting).
	ShadowMode bool
	// CostUSD is the total model cost across all passes.
	CostUSD float64
	// Duration is the wall-clock time spent in Review.
	Duration time.Duration
	// Passes holds per-pass metadata.
	Passes []PassReport
	// NitsCapped is the number of Nit findings dropped by the Nit cap.
	NitsCapped int
	// NitsSuppressed is the number of Nit findings dropped because they were
	// already posted on a prior review of this PR.
	NitsSuppressed int
	// PassErrors lists per-pass error strings (formatted "<pass>: <reason>")
	// for any deep pass that failed. A non-empty PassErrors with a non-nil
	// result means at least one pass produced findings; aggregation only
	// fails hard when every deep pass errored.
	PassErrors []string
}

type Severity string

type ThreadResolver interface {
	// ThreadIDByBodyHeader returns the platform thread ID whose top comment
	// body contains header, or "" when none matches.
	ThreadIDByBodyHeader(ctx context.Context, worktreePath string, prNumber int, header string) (string, error)
	// ResolveThread marks the identified review thread as resolved.
	ResolveThread(ctx context.Context, worktreePath string, threadID string) error
}