audit

type BoundaryDiscoveryResult struct {
	// Boundaries is the parsed boundary list. Nil when loaded from
	// cache (caller already holds the cached value).
	Boundaries []state.Boundary

	// InputHash is a SHA-256 hash of the inputs used to generate the
	// inventory. Used for cache invalidation.
	InputHash string

	// FromCache indicates the cached hash matched; Boundaries is
	// nil in that case.
	FromCache bool
}

type CollectStats struct {
	// TotalListed is the count of paths returned by `git ls-files`
	// (tracked + untracked-non-ignored) before any filter ran.
	TotalListed int

	// Included is the count of paths that survived all filters.
	// Equal to len(files) returned by CollectFiles.
	Included int

	// Tracked / Untracked break Included down by git origin.
	Tracked   int
	Untracked int

	// Exclusion counts, ordered by the precedence applied in
	// partitionFiles. Each path increments exactly one of these (or
	// makes it into Included).
	ExcludedReview int // standard review exclusions (lock/vendor/generated/etc.)
	ExcludedAudit  int // audit-specific exclusions (docs/build/IDE/etc.)
	ExcludedCustom int // user-provided --exclude patterns

	// ForceIncluded counts paths that matched --include and bypassed
	// exclusion. Subset of Included.
	ForceIncluded int

	// UntrackedTransients lists untracked files that survived
	// filtering AND look like locally generated artifacts (logs,
	// debug dumps, state snapshots). The caller surfaces a warning
	// suggesting .gitignore updates — we do NOT auto-exclude because
	// a legitimately-named file could match these patterns.
	UntrackedTransients []string
}

type CompareResult struct {
	New        []state.DeepFinding // findings in current but not previous
	Resolved   []state.DeepFinding // findings in previous but not current
	Persistent []state.DeepFinding // findings in both (may have changed severity etc)
}

type ConcurrencyConfig struct {
	// Classify caps Phase 1b classification calls.
	Classify int
	// AOIScan caps Phase 2 AOI batch calls.
	AOIScan int
	// DeepReview caps Phase 3 review calls.
	DeepReview int
	// Recheck caps Phase 3b recheck batch calls.
	Recheck int
	// HierarchicalSynth caps Phase 4 per-category synthesis calls.
	HierarchicalSynth int
}

type CostEstimate struct {
	TotalCalls      int
	IndividualCalls int
	GroupedCalls    int
	EstInputTokens  int // rough estimate of total input tokens
	EstOutputTokens int // rough estimate of total output tokens
	EstCostUSD      float64
	SkippedCalls    int // calls that would be skipped by --max-reviews
}

type ModelPricing struct {
	InputPerMTok  float64
	OutputPerMTok float64
	ModelName     string
}

type OnProgress func(phase string, message string)

type Options struct {
	// RepoRoot is the absolute path to the repository root.
	RepoRoot string

	// Focus is a list of dimension slugs to focus on. Empty = all.
	Focus []string

	// ExcludePatterns are additional globs to exclude (from --exclude and .prr/audit-exclude).
	ExcludePatterns []string

	// IncludePatterns are globs to force-include (from --include).
	IncludePatterns []string

	// MaxReviews caps the number of Phase 3 review calls. 0 = no limit.
	MaxReviews int

	// NoCache disables incremental caching — re-audit everything.
	NoCache bool

	// AOIContextLines is the number of context lines for AOI generation.
	AOIContextLines int

	// Debug enables verbose output of all LLM prompts and responses.
	Debug bool

	// DebugFile restricts the audit to a single file (path relative to repo root).
	DebugFile string

	// AuditRecent restricts the audit to files touched in the last
	// N commits (and only those — cold files are dropped entirely).
	// Zero = no restriction; the audit covers every file that passes
	// filtering. Either way, files touched recently are sorted to
	// the front so --max-reviews truncates AOIs in cold files first.
	AuditRecent int

	// SiblingClustering enables Phase 2.5: after Phase 2 AOI
	// generation, run an LLM call (or per-category calls when the
	// AOI set is large) that groups AOIs by shape and surfaces
	// outliers — handlers/call-sites whose pattern disagrees with
	// the majority of their siblings. Each outlier becomes an
	// individual-urgency AOI for Phase 3.
	//
	// Gated behind a flag for the first release so precision can be
	// measured on real audits before making it default.
	SiblingClustering bool

	// LargeFileThreshold is the file count above which a warning is
	// displayed. Defaults to 200 when zero.
	LargeFileThreshold int

	// MaxFileBytes caps per-file size during Phase 1 ingestion. Files
	// exceeding the cap are skipped with a warning (not loaded into
	// prompts). Zero falls back to MaxAuditFileBytes.
	MaxFileBytes int

	// Concurrency tunes per-phase concurrency caps. Each zero field falls
	// back to the package default (currently 5).
	Concurrency ConcurrencyConfig
}

type PhaseUsage struct {
	AOI     ai.TokenUsage // Phase 2: AOI pre-scan
	Review  ai.TokenUsage // Phase 3: deep review
	Recheck ai.TokenUsage // Phase 3b: recheck/dedup
	Synth   ai.TokenUsage // Phase 4: synthesis
}

type ReportJSON struct {
	FilesScanned             int                     `json:"files_scanned"`
	AOIsGenerated            int                     `json:"aois_generated"`
	ReviewCalls              int                     `json:"review_calls"`
	IndividualReviews        int                     `json:"individual_reviews"`
	GroupedReviews           int                     `json:"grouped_reviews"`
	FailedReviews            int                     `json:"failed_reviews,omitempty"`
	Findings                 []state.DeepFinding     `json:"findings"`
	Dismissals               int                     `json:"dismissals"`
	RecheckDismissals        []state.DismissedRecord `json:"recheck_dismissals,omitempty"`
	CrossCuttingObservations []string                `json:"cross_cutting_observations,omitempty"`
	SkippedSubcategories     []string                `json:"skipped_subcategories,omitempty"`
	Synthesis                *SynthesisResult        `json:"synthesis,omitempty"`
}

type Result struct {
	// FilesScanned is the number of files that passed Phase 1 filtering.
	FilesScanned int

	// AOIsGenerated is the total number of AOIs from Phase 2.
	AOIsGenerated int

	// ReviewCalls is the number of Phase 3 LLM calls made.
	ReviewCalls int

	// IndividualReviews is the count of individual review calls.
	IndividualReviews int

	// GroupedReviews is the count of grouped review calls.
	GroupedReviews int

	// FailedReviews is the count of Phase 3 review calls that errored and
	// produced no findings. The user should know about these — silently
	// dropping them means the audit's recall is lower than it appears.
	FailedReviews int

	// FailedAOIIDs is the list of AOI IDs whose Phase 3 review call
	// failed (and therefore produced no finding or dismissal). Carries
	// the per-call FailedAOIIDs from review.ExecuteResult so synthesis
	// can mention recall gaps in the executive summary and the reporter
	// can name exactly which areas of the codebase didn't get reviewed.
	FailedAOIIDs []string

	// Findings is all confirmed findings from Phase 3.
	Findings []state.DeepFinding

	// Dismissals is all dismissed AOIs from Phase 3.
	Dismissals int

	// RecheckDismissals is the Phase 3b dismissal log — every finding
	// the recheck pass removed, with the rationale the model gave.
	// Separate from Dismissals (which counts Phase 3 AOI-level
	// dismissals before any finding was emitted); these are findings
	// that survived Phase 3 and were then dropped by recheck.
	RecheckDismissals []state.DismissedRecord

	// CrossCuttingObservations from grouped reviews.
	CrossCuttingObservations []string

	// SkippedSubcategories lists subcategories skipped due to --max-reviews.
	SkippedSubcategories []string

	// Routing is the Phase 3 routing result (for summary display).
	Routing *review.RouteResult

	// ProjectContext is the Phase 0 project briefing. Captured here so the
	// caller can plumb it into Phase 4 synthesis (otherwise the work done in
	// Phase 0 would not reach the executive summary).
	ProjectContext string

	// TokenUsage tracks actual token consumption per phase.
	Usage PhaseUsage
}

type SiblingClusterResult struct {
	// Outliers is the list of synthesized outlier AOIs (urgency
	// "individual", SiblingDeviation populated) ready to merge into
	// the per-file scan results.
	Outliers []security.AreaOfInterest

	// InputHash is a SHA-256 hash of the AOI inputs + runtime model.
	InputHash string

	// FromCache indicates the cached hash matched; Outliers is nil
	// in that case (caller uses the cached value it already holds).
	FromCache bool
}

type SynthesisResult struct {
	// ExecutiveSummary is a 2-3 paragraph overview of audit findings.
	ExecutiveSummary string `json:"executive_summary"`

	// TopRisks are the most critical issues identified, ranked.
	TopRisks []string `json:"top_risks"`

	// SystemicPatterns are recurring issues across the codebase.
	SystemicPatterns []string `json:"systemic_patterns"`

	// Recommendations are prioritized action items.
	Recommendations []string `json:"recommendations"`

	// RawOutput is the full LLM response.
	RawOutput string `json:"-"`
}