index

type Config struct {
	Index struct {
		// Generated indexes files carrying a "Code generated … DO NOT
		// EDIT." header. Default false: such files (protoc, stringer,
		// mockgen output) are boilerplate that inflates the graph and
		// pollutes most-called, and are not meant to be hand-navigated.
		Generated bool `yaml:"generated"`
		// Exclude is a list of gitignore-ish globs skipped on top of
		// .gitignore and the built-in skip dirs. Forms: a bare glob
		// (`*.pb.go`, `*_test.go`) matches any basename; a `**/`-prefixed
		// glob matches the basename in any directory; a trailing-slash
		// entry (`internal/gen/`) matches a directory prefix.
		Exclude []string `yaml:"exclude"`
	} `yaml:"index"`

	Reviews struct {
		// WindowDays bounds how old a mined review comment may be:
		// absent means the 730-day default, 0 means unlimited. The
		// newest 200 comments always survive the window, so a slow
		// repository keeps a working corpus with no tuning.
		WindowDays *int `yaml:"window_days"`
	} `yaml:"reviews"`
}

type Options struct {
	// Root is the workspace directory. When inside a git repository it is
	// widened to the repository toplevel so paths are repo-relative.
	Root string
	// DBPath overrides the index location (default: <root>/.seamark/index.db).
	DBPath string
	// History tunes the git mining pass.
	History history.Options
	// Force rebuilds even when the workspace fingerprint says the index
	// is already current.
	Force bool
	// Logf receives progress and warnings; nil discards them.
	Logf func(format string, args ...any)
	// Progress receives phase events for interactive surfaces: a phase
	// name with units done/total (0 total = indeterminate, reported
	// again as 1/1 when the phase ends). Nil discards — piped and agent
	// surfaces stay on Logf's plain lines.
	Progress func(phase string, done, total int)
}

type RefreshEvent struct {
	Phase  RefreshPhase
	Source string
	// Repository is the "owner/name" slug for the review phases.
	Repository string
	// Bytes is the fetched byte count for PhaseFetchBytes.
	Bytes int
	// Comments and Kept carry the counts for PhaseFetched.
	Comments int
	Kept     int
	// State is the source state for PhaseSourceDone.
	State SourceState
}

type RefreshPhase int

type RefreshRequest struct {
	// Root is the workspace directory; it widens to the git top level.
	Root string
	// DBPath overrides the index location (default: <root>/.seamark/index.db).
	DBPath string
	// Mode selects the sources.
	Mode SourceMode
	// WindowDays is the review window for reviews.Options. The caller
	// resolves it, because the CLI falls back to the default on a bad
	// config file and the console blocks instead.
	WindowDays int
	// Fetch is the review fetcher; nil means gh.
	Fetch reviews.FetchFunc
	// Logf receives the CLI progress lines; nil discards them.
	Logf func(format string, args ...any)
	// Progress receives typed events; nil discards them.
	Progress func(RefreshEvent)
	// BeforePersist runs before each source opens the store, with the
	// source name. The console re-probes the database there. It runs
	// before the open and not only before the write, because store.Open
	// creates a missing database and migrates an older one. The fix
	// source runs it for an unmined result too, because its store also
	// opens then. An error aborts the source before the open: the source
	// reads stopped for a context error and failed otherwise, and the
	// refresh returns the error.
	BeforePersist func(source string) error
}

type RefreshResult struct {
	Fixes   SourceOutcome
	Reviews SourceOutcome
	// Review is the raw review mining result. The CLI prints from it.
	Review reviews.Result
	// FixCount is the fix finding count that the CLI prints.
	FixCount int
}

type SourceCause int

type SourceMode int

type SourceOutcome struct {
	State SourceState
	// Cause is the typed cause of a state other than refreshed and
	// successful-empty; CauseNone otherwise.
	Cause SourceCause
	// Stored counts the findings that this refresh stored for the source.
	Stored int
	// Lessons counts the stored review lessons; it is 0 for fixes.
	Lessons int
	// MinedAt is the mine stamp that this refresh wrote, in Unix
	// seconds; 0 when it wrote none.
	MinedAt int64
	// Reason explains a state other than refreshed in one safe line:
	// control characters are removed and secrets are redacted.
	Reason string
	// Err is the cause, or nil. It is for errors.Is, not for display.
	Err error
}

type SourceState string

type Summary struct {
	Root   string
	DBPath string
	// Skipped is true when the workspace fingerprint matched the index
	// and nothing was rebuilt.
	Skipped bool
	// FilesSeen counts the listed files that exist in the working tree.
	// A deleted path and a path outside a sparse checkout are not in it,
	// because no file exists to see.
	FilesSeen   int
	FilesParsed int // files a language extractor handled
	// FilesReparsed counts files actually run through tree-sitter this
	// pass; the rest were served from the parse cache. Equals FilesParsed
	// on a --force or first index.
	FilesReparsed int
	// FilesSkipped counts supported files dropped by config — generated
	// (default) or an exclude glob.
	FilesSkipped int
	// FilesDeleted counts the tracked paths that git status shows as
	// deleted and not staged, also a file that a directory replaces.
	// They are not parse errors, because no bytes exist to parse. A path
	// outside a sparse checkout is not deleted, as in git status. Outside
	// git it is always 0.
	FilesDeleted int
	ParseErrors  int
	HistoryMined bool
	// HistorySkipNote says why the history layer is absent when
	// HistoryMined is false: "not a git repository" and "mining failed"
	// are different situations and must not be conflated in output.
	HistorySkipNote string
	Stats           store.Stats
	Duration        time.Duration
}