snapshot

type BackfillEvent struct {
	Kind      string
	CommitSHA string
	Error     error
	Duration  time.Duration
}

type BackfillOptions struct {
	RepoRoot    string
	Branch      string
	Since       time.Duration
	MaxCommits  int
	Workers     int
	Force       bool
	KritVersion string
	Reporter    func(BackfillEvent)
}

type BackfillResult struct {
	Captured int
	Skipped  int
	Failed   int
}

type Blob struct {
	SchemaVersion int
	KritVersion   string
	CommitSHA     string
	CapturedAt    int64
	RepoRoot      string

	Modules []Module
	Files   []File
	Symbols []Symbol

	// Redacted is true when the blob's symbol names, owner/package
	// strings, signatures, and file paths have been replaced with
	// stable one-way hashes via Redact. Snapshots captured with
	// CaptureOptions.Redact = true (or post-processed through
	// RedactBlob) flip this flag. Diff guards against comparing
	// redacted vs non-redacted blobs because the join keys
	// (FQN / Signature / Path) live in different namespaces.
	Redacted bool
}

type CaptureOptions struct {
	RepoRoot    string
	CommitSHA   string
	KritVersion string
	Workers     int
	// Now allows tests to inject a deterministic capture time.
	Now func() time.Time
	// WithFindings, when true, runs krit's rule pipeline against the
	// worktree and attaches a per-rule findings rollup to Result. The
	// scan dominates capture wall-time, so this is opt-in.
	WithFindings bool
	// Redact, when true, post-processes the captured blob (and the
	// findings rollup, if WithFindings) through RedactBlob /
	// RedactFindings before returning. Use this for repos with
	// strict-secrecy requirements: snapshots persist Symbol.FQN /
	// Owner / Package / Signature plus File.Path, all of which can
	// embed proprietary identifiers. Redact replaces them with
	// stable one-way hashes so the snapshot still supports diff /
	// timeline / metrics but cannot be reverse-engineered to a
	// source identifier. The flag is captured into Blob.Redacted /
	// Findings.Redacted / Manifest.Redacted so Diff can guard
	// against comparing redacted vs raw.
	Redact bool
}

type DiffResult struct {
	From DiffSide `json:"from"`
	To   DiffSide `json:"to"`

	AddedFiles   []FileRef `json:"added_files,omitempty"`
	RemovedFiles []FileRef `json:"removed_files,omitempty"`

	AddedSymbols   []SymbolRef `json:"added_symbols,omitempty"`
	RemovedSymbols []SymbolRef `json:"removed_symbols,omitempty"`

	AddedModules   []string `json:"added_modules,omitempty"`
	RemovedModules []string `json:"removed_modules,omitempty"`

	AddedEdges   []ModuleEdge `json:"added_edges,omitempty"`
	RemovedEdges []ModuleEdge `json:"removed_edges,omitempty"`

	RepoMetrics   map[string]MetricDelta            `json:"repo_metrics,omitempty"`
	ModuleMetrics map[string]map[string]MetricDelta `json:"module_metrics,omitempty"`

	// FindingsByRule is populated only when both snapshots carry a
	// findings sidecar AND share a RuleSetHash. Cross-rule-set
	// comparisons stay nil so callers don't mistake an apples-to-oranges
	// delta for a real drift signal.
	FindingsByRule map[string]MetricDelta `json:"findings_by_rule,omitempty"`
	// FindingsRuleSetMismatch is set when both sides have findings
	// sidecars whose RuleSetHash differs. Consumers should refuse to
	// report a findings delta in that case.
	FindingsRuleSetMismatch bool `json:"findings_rule_set_mismatch,omitempty"`
}

type DiffSide struct {
	CommitSHA     string `json:"commit_sha"`
	CapturedAt    int64  `json:"captured_at"`
	KritVersion   string `json:"krit_version,omitempty"`
	BlobSchema    int    `json:"blob_schema"`
	MetricsSchema int    `json:"metrics_schema"`
}

type Entry struct {
	CommitSHA string
	Path      string
	Bytes     int64
}

type File struct {
	Path     string
	Module   string
	Language string
	Lines    int
	Bytes    int
}

type FileMetrics struct {
	Path          string
	Module        string
	Language      string
	LOC           int
	Bytes         int
	Symbols       int
	PublicSymbols int
	Cyclomatic    int
}

type FileRef struct {
	Path     string `json:"path"`
	Module   string `json:"module,omitempty"`
	Language string `json:"language,omitempty"`
}

type Findings struct {
	SchemaVersion int
	CommitSHA     string
	RuleSetHash   string
	// ByRule maps rule ID -> total finding count across the snapshot.
	ByRule map[string]int
	// ByRuleFile maps rule ID -> (repo-relative file path -> count).
	// Optional; consumers that only need per-rule totals can ignore it.
	ByRuleFile map[string]map[string]int
	// Redacted is true when ByRuleFile's path keys have been replaced
	// with stable one-way hashes by RedactFindings. Rule IDs stay in
	// clear text because they are public krit identifiers. Mirrors
	// Blob.Redacted so a snapshot is wholly redacted or wholly raw.
	Redacted bool
}

type FindingsRunOptions struct {
	// Config is the resolved krit.yml; nil falls back to defaults.
	Config *config.Config
	// ActiveRules is the rule set dispatched against the worktree. When
	// empty, RunFindings selects the default active set.
	ActiveRules []*api.Rule
	// Workers overrides per-phase worker counts.
	Workers int
	// IncludeGenerated forwards through to ParsePhase.
	IncludeGenerated bool
	// RepoRelativeTo, when non-empty, rewrites the absolute file paths
	// returned in ByRuleFile to be repo-relative. Empty leaves paths
	// untouched.
	RepoRelativeTo string
}

type GateConstraint string

type GateOptions struct {
	Root       string
	FromSHA    string
	ToSHA      string
	Thresholds []GateThreshold
}

type GateResult struct {
	From       string          `json:"from"`
	To         string          `json:"to"`
	Violations []GateViolation `json:"violations,omitempty"`
}

type GateThreshold struct {
	Module         string
	Metric         string
	MaxAbsolute    *float64
	MaxIncrease    *float64
	MaxIncreasePct *float64
}

type GateViolation struct {
	// Module is empty for repo-scope thresholds; otherwise the module
	// path the violation applies to (e.g. ":feature:checkout").
	Module     string         `json:"module,omitempty"`
	Metric     string         `json:"metric"`
	Constraint GateConstraint `json:"constraint"`
	Limit      float64        `json:"limit"`
	Got        float64        `json:"got"`
	From       float64        `json:"from"`
	To         float64        `json:"to"`
}

type Index struct {
	SchemaVersion int        `json:"schema_version"`
	Entries       []Manifest `json:"entries"`
}

type Manifest struct {
	SchemaVersion int      `json:"schema_version"`
	CommitSHA     string   `json:"commit_sha"`
	ParentSHAs    []string `json:"parent_shas,omitempty"`
	CapturedAt    int64    `json:"captured_at"`
	KritVersion   string   `json:"krit_version"`
	BlobSchema    int      `json:"blob_schema"`
	MetricsSchema int      `json:"metrics_schema"`
	// Files / Symbols / Modules are kept at the top level for v1
	// reader compatibility. Prefer Counts in new code; the two move
	// in lockstep.
	Files       int            `json:"files"`
	Symbols     int            `json:"symbols"`
	Modules     int            `json:"modules"`
	Counts      ManifestCounts `json:"counts"`
	RuleSetHash string         `json:"rule_set_hash,omitempty"`
	// Redacted mirrors Blob.Redacted (and Findings.Redacted, which
	// must agree). When true the snapshot's symbol names, FQNs,
	// owners, packages, signatures, and file paths are one-way
	// hashes rather than source identifiers. Diff refuses to compare
	// a redacted manifest against a raw one.
	Redacted bool `json:"redacted,omitempty"`
}

type ManifestCounts struct {
	Files   int `json:"files"`
	Symbols int `json:"symbols"`
	Modules int `json:"modules"`
}

type MetricDelta struct {
	From  float64 `json:"from"`
	To    float64 `json:"to"`
	Delta float64 `json:"delta"`
}

type Metrics struct {
	SchemaVersion int
	CommitSHA     string
	CapturedAt    int64
	Files         []FileMetrics
	Modules       []ModuleMetrics
}

type Module struct {
	Path         string
	Dir          string
	Dependencies []ModuleDep
	Consumers    []string
}

type ModuleDep struct {
	Path          string
	Configuration string
}

type ModuleEdge struct {
	From          string `json:"from"`
	To            string `json:"to"`
	Configuration string `json:"configuration"`
}

type ModuleMetrics struct {
	Path          string
	Files         int
	LOC           int
	Symbols       int
	PublicSymbols int
	Cyclomatic    int
	FanIn         int
	FanOut        int
}

type PruneEntry struct {
	CommitSHA  string
	CapturedAt time.Time
	Reach      Reachability
	// Pruned is true when Prune deleted (or, in DryRun, would have
	// deleted) this snapshot.
	Pruned bool
	// Reason is a short human-readable note: "kept (permanent)",
	// "kept (feature, age 12d < 30d)", "pruned (orphan, age 9d > 7d)".
	Reason string
}

type PruneOptions struct {
	// Root is the snapshots directory (i.e. SnapshotsDir(repoRoot)).
	Root string
	// RepoRoot is the working-tree root passed to git.
	RepoRoot string
	// PermanentBranches lists the branch names treated as
	// always-keep. Empty means use DefaultPermanentBranches.
	PermanentBranches []string
	// KeepFeatureAge is the retention window for feature-branch-only
	// snapshots. Zero means use DefaultKeepFeatureAge.
	KeepFeatureAge time.Duration
	// KeepOrphanAge is the retention window for unreachable
	// snapshots. Zero means use DefaultKeepOrphanAge.
	KeepOrphanAge time.Duration
	// DryRun reports what would be pruned without removing anything.
	DryRun bool
	// Now is the reference clock for age comparisons. Zero means
	// time.Now(). Test seam.
	Now time.Time
	// ReachableSHAs returns the set of commit shas reachable from any
	// of the given refs. Nil means "use the production git-backed
	// implementation". Test seam.
	ReachableSHAs func(repoRoot string, refs []string) (map[string]bool, error)
	// AllRefSHAs returns the set of commit shas reachable from any
	// ref in the repository. Nil means "use the production git-backed
	// implementation". Test seam.
	AllRefSHAs func(repoRoot string) (map[string]bool, error)
}

type PruneResult struct {
	Entries []PruneEntry
	// Pruned counts entries actually removed (or, in DryRun, that
	// would have been removed).
	Pruned int
	// Errors collects per-sha removal failures so the caller can
	// surface them; the run continues past individual errors.
	Errors []error
}

type Reachability string

type Result struct {
	Blob     *Blob
	Metrics  *Metrics
	Findings *Findings
}

type SimulateEvent struct {
	Kind      string
	CommitSHA string
	Findings  int
	Duration  time.Duration
	Error     error
}

type SimulateOptions struct {
	RepoRoot   string
	Rule       string
	Branch     string
	Since      time.Duration
	MaxCommits int
	Workers    int
	// KritBin is the krit executable to invoke against each captured
	// worktree. Empty defaults to argv[0]; tests inject a path.
	KritBin string
	// NoSidecar forces the shell-out path even when persisted findings
	// sidecars are available. Tests use this to exercise the legacy
	// path explicitly; production callers should leave it false.
	NoSidecar bool
	Reporter  func(SimulateEvent)
}

type SimulatePoint struct {
	CommitSHA   string         `json:"commit_sha"`
	CommittedAt int64          `json:"committed_at"`
	Findings    int            `json:"findings"`
	Source      SimulateSource `json:"source,omitempty"`
}

type SimulateResult struct {
	Rule   string          `json:"rule"`
	Points []SimulatePoint `json:"points"`
	Failed []string        `json:"failed,omitempty"`
}

type SimulateSource string

type Symbol struct {
	Name       string
	Kind       string
	Visibility string
	File       string
	Line       int
	Language   string
	Package    string
	FQN        string
	Owner      string
	Signature  string
	IsOverride bool
	IsTest     bool
}

type SymbolRef struct {
	FQN       string `json:"fqn"`
	Signature string `json:"signature,omitempty"`
	Kind      string `json:"kind,omitempty"`
	File      string `json:"file,omitempty"`
}

type TimelinePoint struct {
	CommitSHA  string
	CapturedAt int64
	Value      float64
}

type TimelineQuery struct {
	Scope  TimelineScope
	Target string // module path (":app") or repo-relative file path; ignored for ScopeRepo
	Metric string // see metricByName
}

type TimelineScope string