Documentation
¶
Overview ¶
Package search provides zero-dependency code intelligence: symbol extraction (function/struct/class maps per file) and BM25 relevance search over file contents. Hand-rolled and dependency-free on purpose — these give the agent a structural map of the codebase without reading every file into context, and a relevance-ranked search that beats plain regex grep.
Index ¶
- func Cosine(a, b []float32) float64
- func FormatResults(results []bm25Result, query string) string
- func FormatSymbolSummary(files []string) string
- func ReRank(ctx context.Context, root, query string, results []bm25Result, e *Embedder, ...) []bm25Result
- type BM25
- type Document
- type Embedder
- type GlobalIndex
- func (g *GlobalIndex) AllSymbols() map[string]map[string]bool
- func (g *GlobalIndex) FileCount() int
- func (g *GlobalIndex) Files() []string
- func (g *GlobalIndex) FormatLookup(name string) string
- func (g *GlobalIndex) Importers(file string) []string
- func (g *GlobalIndex) Lookup(name string) []IndexedSymbol
- func (g *GlobalIndex) Referencers(name string) []string
- func (g *GlobalIndex) RefreshFile(path string)
- func (g *GlobalIndex) ResolveSymbol(name string) (string, bool)
- func (g *GlobalIndex) SymbolCount() int
- type IndexedSymbol
- type ProjectContext
- type SemanticCache
- type SymbolItem
- type SymbolRAG
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Cosine ¶
Cosine returns the cosine similarity of two vectors (0 when either is empty), used to score how well a file matches the query semantically.
func FormatResults ¶
FormatResults renders top search results with a snippet around the first query term match.
func FormatSymbolSummary ¶
FormatSymbolSummary returns a compact symbol map string for a file list — the agent's "structure preview" of a file without reading its body.
func ReRank ¶
func ReRank(ctx context.Context, root, query string, results []bm25Result, e *Embedder, limit int) []bm25Result
ReRank re-ranks BM25 results by embedding cosine similarity: the query and each candidate file are embedded (with a persistent per-file cache), and the top `limit` most similar files are returned. On any embedding failure (no endpoint, bad key, unsupported model) it returns the BM25 candidates untouched, truncated to limit — search_code never breaks because of it.
Types ¶
type BM25 ¶
type BM25 struct {
// contains filtered or unexported fields
}
BM25 indexes a set of documents and answers relevance queries.
type Document ¶
type Document struct {
ID string // file path
Title string // short name (basename)
Body string // full or partial content
Snippet string // optional preview ("" = derive)
}
Document is a searchable item: a file with its content as the body.
type Embedder ¶
type Embedder struct {
BaseURL string
APIKey string
Model string
// contains filtered or unexported fields
}
Embedder calls an OpenAI-compatible /embeddings endpoint — the same shape as OpenAI's text-embedding-3-small — so semantic re-ranking works with any compatible gateway the user configures. Nil-safe: when an Embedder is not wired, search_code stays BM25-only.
func NewEmbedder ¶
NewEmbedder builds an embedder for an OpenAI-compatible base URL.
type GlobalIndex ¶
type GlobalIndex struct {
// contains filtered or unexported fields
}
GlobalIndex is a codebase-wide symbol + reference index built ONCE per session and reused across turns. Unlike per-call LSP queries it answers repo-wide questions instantly and for free: where a symbol is defined, which files reference it, and which files import a given module — no server spawn, no full-file reads into context.
func BuildGlobalIndex ¶
func BuildGlobalIndex(root string) *GlobalIndex
BuildGlobalIndex walks root (skipping heavy/vendor dirs) and indexes every supported source file's symbols and import references.
func (*GlobalIndex) AllSymbols ¶
func (g *GlobalIndex) AllSymbols() map[string]map[string]bool
AllSymbols returns a map of file path -> set of defined symbols across the index.
func (*GlobalIndex) FileCount ¶
func (g *GlobalIndex) FileCount() int
FileCount returns the number of indexed files (used by the tool's output header and /lsp-style status).
func (*GlobalIndex) Files ¶
func (g *GlobalIndex) Files() []string
Files returns a copy of all indexed file paths.
func (*GlobalIndex) FormatLookup ¶
func (g *GlobalIndex) FormatLookup(name string) string
FormatLookup renders a compact human-readable code_locate report.
func (*GlobalIndex) Importers ¶
func (g *GlobalIndex) Importers(file string) []string
Importers returns the files whose import specifiers reference the given file (matched by the module name's last path segment, e.g. ConversationService.js is imported by files that `import ... from '.../ConversationService'`).
func (*GlobalIndex) Lookup ¶
func (g *GlobalIndex) Lookup(name string) []IndexedSymbol
Lookup returns every indexed occurrence of a symbol name (definitions and declarations), sorted by file then line.
func (*GlobalIndex) Referencers ¶
func (g *GlobalIndex) Referencers(name string) []string
Referencers returns the files that reference the symbol name (single quick pass over the indexed file list, capped), excluding its definition files.
func (*GlobalIndex) RefreshFile ¶
func (g *GlobalIndex) RefreshFile(path string)
RefreshFile re-indexes a single changed file so the session-wide index stays current after edits — the index is no longer frozen at session start. Stale symbol entries for the file are dropped, then fresh symbols are indexed.
func (*GlobalIndex) ResolveSymbol ¶
func (g *GlobalIndex) ResolveSymbol(name string) (string, bool)
ResolveSymbol returns the file that defines the given symbol using the instant (<5ms) symbol index, or "" when unknown.
func (*GlobalIndex) SymbolCount ¶
func (g *GlobalIndex) SymbolCount() int
SymbolCount reports how many unique symbols the RAG index knows about.
type IndexedSymbol ¶
type IndexedSymbol struct {
Name string // symbol name
Kind string // func / method / struct / class / interface / ...
File string // absolute path
Line int // 1-based line
}
IndexedSymbol is one symbol occurrence: where a name is defined in the repo.
type ProjectContext ¶
type ProjectContext struct {
Root string
Tree string // 2-level directory tree (names only)
Docs string // concatenated contents of AGENTS/CLAUDE/README (capped)
EntryFiles []string
}
ProjectContext is a compact structural overview of the project plus any instruction docs, injected into the system prompt so the agent starts with orientation instead of blind grep/glob exploration.
func BuildProjectContext ¶
func BuildProjectContext(root string) *ProjectContext
BuildProjectContext scans the working directory and produces the context. Shallow and fast: tree listing uses ReadDir one level at a time (no deep walk), docs are read with a size cap.
func (*ProjectContext) String ¶
func (pc *ProjectContext) String() string
String renders the project context for injection into the system prompt. Kept compact: tree + entry files, docs only if present.
type SemanticCache ¶
type SemanticCache struct {
// contains filtered or unexported fields
}
SemanticCache persists per-file embeddings under .brocode/index so repeated queries don't re-pay embedding cost for unchanged files.
func NewSemanticCache ¶
func NewSemanticCache(root string) *SemanticCache
NewSemanticCache loads (or initializes) the cache file for root.
func (*SemanticCache) EmbedWithCache ¶
func (c *SemanticCache) EmbedWithCache(ctx context.Context, e *Embedder, path string, maxBytes int) ([]float32, error)
EmbedWithCache returns the vector for path, embedding + caching on miss.
type SymbolItem ¶
type SymbolItem struct {
Name string // Symbol name (e.g. "EvaluateComplexity", "UserModel")
Kind string // Kind (e.g. "func", "method", "struct", "class", "interface")
Line int // Line number in file
}
SymbolItem represents an extracted code symbol (function, struct, type, class, etc.).
func ExtractSymbols ¶
func ExtractSymbols(path string) ([]SymbolItem, error)
ExtractSymbols parses a file and returns its structural symbols without reading the full file body into LLM context. Uses Go's native go/ast parser for Go files, and lightweight regex matching for other languages.
func SortedSymbols ¶
func SortedSymbols(syms []SymbolItem) []SymbolItem
SortedSymbols returns symbols ordered by line.
type SymbolRAG ¶
type SymbolRAG struct {
// contains filtered or unexported fields
}
SymbolRAG provides instant (<5ms) local zero-dependency symbol resolution.
func NewSymbolRAG ¶
func NewSymbolRAG() *SymbolRAG
NewSymbolRAG creates a new local symbol RAG index.
func (*SymbolRAG) IndexSymbol ¶
IndexSymbol records a symbol mapping (e.g. function/type/struct -> file).
func (*SymbolRAG) RemoveFile ¶
RemoveFile drops every symbol that pointed at the given file — used when a file changes (or is deleted) so the RAG never resolves a stale symbol.