analyze

type AnalyzedFile struct {
	RelPath    string           // path relative to repo root
	Language   string           // detected language
	Size       int64            // file size in bytes
	Lines      int              // line count (from symbol EndLine heuristic)
	Symbols    []*parser.Symbol // all symbols in this file
	Imports    []string         // imports declared in this file
	Relevance  float64          // BM25F+PageRank combined score
	ImportedBy int              // how many packages import this file's package
}

type ContextData struct {
	RankedFiles  []*ingest.File     // files ordered by relevance
	FileScores   map[string]float64 // relPath → BM25F+PageRank combined score
	ImportGraph  importGraph        // package-level import adjacency
	ImportedBy   map[string]int     // relPath → imported-by count
	SymbolCounts map[string]int     // relPath → symbol count
	FileTree     string             // rendered directory tree
	QueryTerms   []string           // extracted search terms
	Languages    map[string]int     // language → file count
}

type DepGraphInput struct {
	// Root is the local path to the repository.
	Root string

	// Type selects the graph type.
	// TODO: reserved for future use; currently only "imports" is supported.
	Type string

	// Format controls output format: json, dot, mermaid.
	Format string

	// Focus limits the graph to a specific package.
	Focus string

	// MaxDepth limits traversal depth from the focus node.
	MaxDepth int

	// IncludeStdlib includes standard library imports. Default false.
	IncludeStdlib bool

	// CrossLanguage includes cross-language API route connections between layers.
	// Currently a schema-only field: cross-language dependencies are stored in
	// Apache AGE and queried via code_graph polyglot_overview and layer_deps templates.
	CrossLanguage bool
}

type Deps struct {
	// LLM is the client used for natural-language queries.
	// Always non-nil: either a real *llm.Client or llm.NoOp{}.
	// Check LLMHasKey before invoking tools that require an actual LLM.
	LLM llm.Completer

	// LLMHasKey is true when LLM_API_KEY is set and LLM is a real client.
	// False means LLM is llm.NoOp{} and calls will return ErrLLMUnavailable.
	LLMHasKey bool

	// MaxFileBytes is the max file size to parse. 0 uses the default.
	MaxFileBytes int64

	// GithubToken is the optional GitHub token for cloning private repos.
	// Deprecated: prefer CloneTokenFunc for dynamic tokens (e.g. GitHub App installation tokens).
	// Kept for backwards-compat; CloneTokenFunc takes precedence when set.
	GithubToken string

	// CloneTokenFunc returns a token for authenticated git clones.
	// When set, it overrides GithubToken. Use forge.AppTokenSource.Token for
	// GitHub App installation tokens (ghs_), or a static closure for PATs.
	CloneTokenFunc func(ctx context.Context) (string, error)

	// WorkspaceDir is the directory used for temporary clones.
	WorkspaceDir string

	// PathMappings translates external paths to container-internal paths.
	PathMappings []PathMapping

	// LocalRepoDirs are directories holding local checkouts (e.g. /host/src).
	// resolveRoot prefers a matching local checkout over cloning when a remote
	// slug resolves to one of these — avoids a redundant (and, for private
	// repos without a GitHub App, auth-failing) clone.
	LocalRepoDirs []string

	// ParseCache caches parsed AST results per file. Optional.
	ParseCache *cache.ParseCache

	// LLMCache caches LLM responses. Optional.
	LLMCache *cache.LLMCache

	// Forges is the multi-forge registry for search operations.
	Forges *forge.Registry

	// WebSearch is the go-search client for web-based repo discovery. Optional.
	WebSearch *websearch.Client

	// ToolCache is a generic cache for tool results (search, etc.).
	ToolCache *kitcache.Cache

	// OxCodes is the optional ox-codes search backend client.
	// When set, code_search uses ox-codes for grep, scoped, and structural search.
	OxCodes *oxcodes.Client

	// Learnings is the optional store for prior review findings.
	// When set, review tools persist and surface past verdicts.
	Learnings *learnings.Store

	// Graph returns persistent-graph-computed signals (pagerank, community, surprise)
	// for a symbol. Always non-nil; use graphx.Noop{} when no snapshot is available.
	Graph graphx.Analytics

	// Refs surfaces graph edges not carried in callgraph (HANDLES, FETCHES, TESTED_BY).
	// Always non-nil; use graphx.Noop{} when no snapshot is available.
	Refs graphx.CrossRefs

	// SymbolBooster is the optional pg_trgm symbol name searcher used to boost
	// file scores when symbols match query keywords. Optional — nil disables boosting.
	SymbolBooster SymbolNameSearcher

	// RepoKeyFunc derives the embedding store repo key from a local root path.
	// Must be set when SymbolBooster is non-nil. If nil, boosting is skipped.
	RepoKeyFunc func(root string) string

	// IndexedSHAFunc, when set, returns the last-indexed commit SHA for a repo
	// key (or "" when unknown). Injected at construction to avoid an
	// analyze→embeddings import cycle. nil → IndexedSHA always returns "".
	IndexedSHAFunc func(ctx context.Context, repoKey string) string
}

type FusionConfig struct {
	Mode           FusionMode
	WeightBM25     float64
	WeightPageRank float64
	WeightSeed     float64
}

type FusionMode string

type PathMapping struct {
	External string
	Internal string
}

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

	// Query is the search query for ranking files by relevance.
	Query string

	// Focus limits analysis to a subdirectory or glob pattern.
	Focus string

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

	// Depth controls analysis depth: overview, module (default), deep.
	Depth string
}

type RepoAnalysisResult struct {
	// RepoName is the detected repository name.
	RepoName string

	// Language is the dominant programming language.
	Language string

	// FileCount is the number of files analyzed.
	FileCount int

	// Symbols is a sample of key symbols found (backward compat).
	Symbols []*parser.Symbol

	// Packages is the list of top-level package names.
	Packages []string

	// Files is per-file metadata ordered by relevance.
	Files []AnalyzedFile

	// ImportGraph maps pkg → []imported_pkgs (non-stdlib).
	ImportGraph map[string][]string

	// FileTree is the rendered directory tree.
	FileTree string

	// Languages maps language → file count.
	Languages map[string]int

	// TotalBytes is the total size of all ingested files.
	TotalBytes int64

	// Skipped is the number of files skipped during ingestion.
	Skipped int
}

type ResearchData struct {
	// Root is the resolved repository root path.
	Root string

	// Files is the full list of ingested files.
	Files []*ingest.File

	// FileSymbols maps relPath → symbols for each file.
	FileSymbols map[string][]*parser.Symbol

	// FileImports maps relPath → relPaths of local files it imports.
	// Built from the package-level import graph lifted to file level.
	FileImports map[string][]string

	// PkgFiles maps package dir → relPaths of files in that package.
	PkgFiles map[string][]string

	// FusedScores maps relPath → multi-signal fused score
	// (BM25F 0.5 + Personalized PageRank 0.3 + exact-match 0.2)
	// produced by prioritizeFilesWithScores. NOT raw BM25.
	FusedScores map[string]float64

	// QueryTerms are the extracted terms used for BM25F matching.
	QueryTerms []string
}

type SymbolHit struct {
	FilePath string
}

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

type SymbolSearchInput struct {
	// Root is the local path to the repository.
	Root string

	// Query is the symbol name or wildcard pattern.
	Query string

	// Kind limits results to this symbol kind.
	Kind parser.NodeKind

	// Language limits results to files of this language.
	Language string

	// IncludeBody includes the full source body in results.
	IncludeBody bool

	// Limit caps the number of results returned. Default 100, max 500.
	Limit int
}