research

type Deps struct {
	// AnalyzeDeps provides ingest, parse, and BM25 capabilities (required).
	AnalyzeDeps analyze.Deps

	// EmbedClient enables semantic search signal. Optional.
	EmbedClient EmbedClient

	// EmbedStore provides vector similarity search. Optional.
	EmbedStore EmbedStore

	// RepoKey is the embedding store key for this repository. Required when
	// EmbedClient/EmbedStore are set.
	RepoKey string

	// BuildCallGraph is an optional hook that returns the call graph for a
	// repository root. Used when Input.IncludeCallGraph=true. Non-fatal — if
	// nil or it returns an error, import-DAG expansion still runs normally.
	BuildCallGraph func(ctx context.Context, root string) (*callgraph.CallGraph, error)

	// SymbolSearcher enables pg_trgm symbol name search.
	// Optional — nil disables symbol name augmentation.
	SymbolSearcher SymbolSearcher

	// Graph provides PageRank signals for symbol-importance file boosting.
	// Optional - nil disables PageRank file prioritization.
	Graph graphx.Analytics

	// GraphRepoKey is the repo root path passed to TopPageRank. Required when Graph is non-nil.
	GraphRepoKey string
}

type EmbedClient interface {
	EmbedQuery(ctx context.Context, query string) ([]float32, error)
}

type EmbedStore interface {
	Search(ctx context.Context, vec []float32, opts embeddings.SearchOpts) ([]embeddings.SearchResult, error)
}

type Input struct {
	// Root is the local path to the (already-cloned) repository.
	Root string

	// Query is the natural-language or keyword query.
	Query string

	// Language limits analysis to files of this language. Optional.
	Language string

	// MaxTokens is the approximate token budget for the output map.
	// 0 uses DefaultMaxTokens.
	MaxTokens int

	// ExpandHops is the number of import-graph hops from seed files.
	// 0 uses DefaultExpandHops.
	ExpandHops int

	// IncludeBody includes full symbol bodies in the output map.
	IncludeBody bool

	// FileGlob restricts analysis to files matching this glob (e.g.
	// "internal/**", "pkg/foo/*.go"). Empty = no filter.
	FileGlob string

	// IncludeTests controls whether *_test.go / test files are indexed.
	// Default false — test files are usually noise for "how does X work"
	// queries. Set true to include them.
	IncludeTests bool

	// IncludeCallGraph enables a second BFS expansion pass using call edges
	// (callers + callees) in addition to import-DAG edges. Slower but higher
	// precision for "what calls X" queries. Results are merged with the import
	// expansion, keeping the shorter distance when both reach the same file.
	IncludeCallGraph bool
}

type LinkedFile struct {
	RelPath   string           // path relative to repo root
	Distance  int              // hop distance from nearest seed (0 = seed file itself)
	WhyLinked string           // human-readable explanation, e.g. "imports seed internal/parser"
	Symbols   []*parser.Symbol // symbols in this file relevant to the query
	Score     float64          // combined relevance score after decay
}

type Result struct {
	// Seeds are symbols directly matching the query (from BM25F / embed).
	Seeds []SeedSymbol

	// Graph is the DAG-expanded set of related files, ordered by relevance.
	Graph []LinkedFile

	// Map is the Aider-style compact text representation for LLM consumption.
	Map string

	// EstimatedTokens is the estimated token count of Map.
	EstimatedTokens int

	// PrunedFiles is the number of files dropped by the token-budget pruner.
	PrunedFiles int

	// Mode describes which signals were active: "full", "no-embed", "keyword-only".
	Mode string
}

type SeedSymbol struct {
	File   string
	Name   string
	Kind   string
	Line   int
	Score  float64 // RRF or BM25F score
	Source string  // "semantic", "keyword", or "hybrid"
}

type SymbolSearcher interface {
	SearchBySymbolName(ctx context.Context, repoKey string, keywords []string, language string, limit int) ([]embeddings.SearchResult, error)
}