indexer

type DiscoveredFile struct {
	// AbsPath is the absolute path on disk, for reading bytes.
	AbsPath string
	// RelPath is the slash-normalized path relative to the repo root, the
	// file_path stored on Node/File records.
	RelPath string
	// ImportPath is this file's cross-file symbol-index key, computed by
	// its language's LanguageSpec.ModuleKey (D-03/Pitfall 2). For Go this
	// is the module path joined with the file's relative directory (""
	// relative directory means the module root package) — byte-identical
	// to the pre-Phase-5 behavior. A file whose language has no resolvable
	// project descriptor still gets a value here (its LanguageSpec's
	// path-based fallback), never a dropped file.
	ImportPath string
	// Language is the registered LanguageSpec.ID this file's extension
	// resolved to ("go", "java", "python", ...) — the key extract.go's
	// worker pool uses to select the correct parser + extractor per file
	// (Pitfall 1).
	Language string

	// MtimeUnixNs and SizeBytes are the file's on-disk stat info at
	// discovery time (Phase 4 D-01a) — carried through Extract into the
	// committed File record so Sync's stat pre-filter has something cheap
	// to compare against on the next invocation, without hashing every
	// file every sync.
	MtimeUnixNs int64
	SizeBytes   int64
}

type Discovery struct {
	Files      []DiscoveredFile
	Excluded   []*schema.ExcludedFile
	ModulePath string
}

type LanguageSpec struct {
	// ID is the language's stable registry key ("go", "java", "csharp",
	// "python", "typescript", ...).
	ID string

	// Extensions are the file extensions (including the leading ".") this
	// language claims during discovery.
	Extensions []string

	// NewParser constructs a fresh parser.Parser for this language, routed
	// through the parser.Parser seam (and, for the CGo backend, the
	// MaxSourceBytes ceiling in newCGoParser/Parse — Security Domain V5).
	NewParser func() (parser.Parser, error)

	// Extract walks one file's already-parsed syntax tree into a
	// goextract.FileResult. moduleKey is this language's cross-file
	// symbol-index key for the file (Go's importPath is the first
	// instance of this concept; other languages compute a structurally
	// different key via ModuleKey below).
	Extract func(p parser.Parser, moduleKey, relPath string, src []byte) (goextract.FileResult, error)

	// ModuleKey computes this language's cross-file symbol-index key for a
	// discovered file, given the repo's resolved ProjectDescriptor (which
	// may be nil if this language's descriptor could not be resolved — a
	// file whose language has no descriptor still gets extracted with
	// path-based identity per D-03, so implementations must tolerate a
	// nil descriptor rather than panicking).
	ModuleKey func(descriptor ProjectDescriptor, relPath string) string

	// Descriptor parses this language's manifest (go.mod, pom.xml,
	// *.csproj, pyproject.toml, package.json+tsconfig.json, ...) once per
	// repo root to resolve module/namespace identity for the whole repo.
	Descriptor func(root string) (ProjectDescriptor, error)
}

type Options struct {
	// Workers bounds Pass 1's extraction worker pool. <= 0 defaults to
	// runtime.NumCPU() — Extract's own default (D-04), applied here too so
	// callers observe the same behavior whether they pass Options{} or
	// Options{Workers: runtime.NumCPU()} explicitly.
	Workers int

	// Verbose and Quiet are carried through for the CLI's summary output
	// (Stats already reports Unresolved/Skipped counts regardless of
	// these flags); Run itself does no logging.
	Verbose bool
	Quiet   bool

	// CoverageGenerationFloor (CR-01, 10-REVIEW.md iteration 3) is a lower
	// bound writeGraph must respect when it stamps the from-scratch
	// commit's Meta.CoverageGeneration. writeGraph already reads the
	// TARGET store's own prior generation via a pre-commit Snapshot — but
	// a caller that wiped storeDir (`codegraph index`'s
	// RemoveAll+MkdirAll, internal/cli/index.go) makes that read see a
	// genuinely empty store (ErrNotFound), which resets the counter to 0
	// even though a deleted store may have carried it much higher — the
	// exact value a live client's outstanding page token may still be
	// pinned to. A caller that reads the PRIOR store's generation before
	// wiping it can pass it here so writeGraph stamps
	// max(priorGeneration, CoverageGenerationFloor)+1 instead, keeping
	// the counter monotonic across the wipe. Zero (the default) is a
	// no-op — writeGraph's own store-read generation is used unchanged,
	// which is exactly right for a genuinely fresh store (`codegraph
	// init`, no prior store to alias against).
	CoverageGenerationFloor int64
}

type ProjectDescriptor interface {
	// ModulePath returns the descriptor's resolved base identity — a Go
	// module path today; a Java/C# root package/namespace, a Python
	// project root, or a TS/JS resolved package name for later languages.
	ModulePath() string
}

type Stats struct {
	Files      int
	Nodes      int
	Edges      int
	Unresolved int
	Skipped    int
	Duration   time.Duration

	// FilesReparsed, FilesPruned, NodesRemoved, EdgesRemoved, and
	// DependentsRecomputed are Sync-only summary counts (Phase 4 D-01b) —
	// zero-valued for a from-scratch Run. FilesReparsed is the size of the
	// Extract() batch (added ∪ modified ∪ dependent); FilesPruned counts
	// modified+deleted files whose subgraph was pruned via the x/ index;
	// NodesRemoved/EdgesRemoved count the individual n/e records
	// point-deleted during that prune; DependentsRecomputed counts files
	// re-extracted purely because a symbol they referenced was pruned
	// (RESEARCH Pitfall 2), not because their own content changed.
	FilesReparsed        int
	FilesPruned          int
	NodesRemoved         int
	EdgesRemoved         int
	DependentsRecomputed int
}