search

package
v0.1.47 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 21 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Cosine 

func Cosine(a, b []float32) float64

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 

func FormatResults(results []bm25Result, query string) string

FormatResults renders top search results with a snippet around the first query term match.

func FormatSymbolSummary 

func FormatSymbolSummary(files []string) string

FormatSymbolSummary returns a compact symbol map string for a file list — the agent's "structure preview" of a file without reading its body.

func IsBinaryExt added in v0.1.1 

func IsBinaryExt(ext string) bool

IsBinaryExt reports whether a file extension belongs to a binary or generated file.

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.

func ReRankDocs added in v0.1.1 

func ReRankDocs(ctx context.Context, query string, results []bm25Result, e *Embedder, limit int) []bm25Result

ReRankDocs re-ranks in-memory BM25 results (e.g. project-memory facts) by embedding cosine similarity. Unlike ReRank — which persists a per-file embedding cache keyed by path — docs here are short texts embedded directly, so the candidate set must already be small (the caller limits it, typically top-8 from BM25). The query and each candidate are embedded in one batch; on ANY embedding failure it returns the BM25 order untouched — hybrid retrieval never breaks BM25-only operation.

Types

type BM25 

type BM25 struct {
	// contains filtered or unexported fields
}

BM25 indexes a set of documents and answers relevance queries.

func NewBM25 

func NewBM25(docs []Document) *BM25

NewBM25 builds an index from documents.

func (*BM25) Search 

func (b *BM25) Search(query string, n int) []bm25Result

Search ranks documents by BM25 relevance to the query, returning top n.

type BlastRadiusReport added in v0.1.32 

type BlastRadiusReport struct {
	Target       string   `json:"target"`
	IsFile       bool     `json:"is_file"`
	Risk         string   `json:"risk"` // LOW, MEDIUM, HIGH, CRITICAL
	CallersCount int      `json:"callers_count"`
	Callers      []string `json:"callers,omitempty"`
	Importers    []string `json:"importers,omitempty"`
	Definitions  []string `json:"definitions,omitempty"`
}

BlastRadiusReport summarizes the ripple impact of changing a symbol or file.

func (*BlastRadiusReport) Format added in v0.1.32 

func (r *BlastRadiusReport) Format() string

Format renders a clean, developer-friendly blast radius card.

type CallerLocation added in v0.1.16 

type CallerLocation struct {
	File    string `json:"file"`
	Line    int    `json:"line"`
	Snippet string `json:"snippet"`
}

CallerLocation points to a call site in the workspace.

type ClusterGroup added in v0.1.16 

type ClusterGroup struct {
	ID            int      `json:"cluster_id"`
	SuggestedFile string   `json:"suggested_file"`
	PrimaryTheme  string   `json:"primary_theme"`
	Symbols       []string `json:"symbols"`
	TotalLines    int      `json:"total_lines"`
	InternalCalls int      `json:"internal_calls"` // high = strong cohesion
	ExternalCalls int      `json:"external_calls"` // low = clean boundary
}

ClusterGroup represents a cohesive cluster of functions that belong together.

func ClusterFileSymbols added in v0.1.16 

func ClusterFileSymbols(path string) ([]ClusterGroup, error)

ClusterFileSymbols performs modularity clustering on a monolithic file. It groups functions that call each other into self-contained modular candidates.

type DetailedSymbol added in v0.1.16 

type DetailedSymbol struct {
	Name      string   `json:"name"`
	Kind      string   `json:"kind"` // "func", "method", "struct", "interface", "class", "type"
	StartLine int      `json:"start_line"`
	EndLine   int      `json:"end_line"`
	Lines     int      `json:"lines"`
	Receiver  string   `json:"receiver,omitempty"`
	Signature string   `json:"signature,omitempty"`
	Doc       string   `json:"doc,omitempty"`
	Calls     []string `json:"calls,omitempty"` // names of functions/methods called inside this symbol
}

DetailedSymbol represents a code symbol with exact start/end lines and call information.

func OutlineFile added in v0.1.16 

func OutlineFile(path string) ([]DetailedSymbol, error)

OutlineFile extracts the structural symbol outline of a file without reading the full body into LLM context. Ideal for 1,000 to 20,000+ line files.

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.

func IndexDir 

func IndexDir(dir string) ([]Document, error)

IndexDir builds a BM25 index over all text files under dir (skipping heavy dirs). Reading whole files into memory is bounded: skip files over 2MB.

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 

func NewEmbedder(baseURL, apiKey, model string) *Embedder

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 in the background to ensure instant (<50ms) startup time even on massive 50k+ file projects. All accessors are thread-safe and non-blocking.

func BuildGlobalIndex 

func BuildGlobalIndex(root string) *GlobalIndex

BuildGlobalIndex spawns an asynchronous background worker pool to index the workspace without blocking the TUI startup, returning a live index immediately.

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) BlastRadius added in v0.1.32 

func (g *GlobalIndex) BlastRadius(target string) *BlastRadiusReport

BlastRadius computes the blast radius of modifying a given symbol or file path.

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) IsReady added in v0.1.42 

func (g *GlobalIndex) IsReady() bool

IsReady reports whether the initial background indexing pass has finished.

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 symbol index, or "" when unknown.

func (*GlobalIndex) SymbolCount 

func (g *GlobalIndex) SymbolCount() int

SymbolCount reports how many unique symbols the RAG index knows about.

func (*GlobalIndex) WaitReady added in v0.1.42 

func (g *GlobalIndex) WaitReady(ctx context.Context)

WaitReady blocks until the initial background indexing pass completes or ctx is done.

type ImpactReport added in v0.1.16 

type ImpactReport struct {
	Symbol      string           `json:"symbol"`
	File        string           `json:"file"`
	Kind        string           `json:"kind"`
	StartLine   int              `json:"start_line"`
	EndLine     int              `json:"end_line"`
	FanIn       int              `json:"fan_in"`       // count of callers
	FanOut      int              `json:"fan_out"`      // count of callees
	BlastRadius string           `json:"blast_radius"` // "LOW" | "MEDIUM" | "HIGH"
	Callers     []CallerLocation `json:"callers"`
	Callees     []string         `json:"callees"`
	Extraction  string           `json:"safe_extraction_order"`
}

ImpactReport details the blast radius of modifying a symbol.

func AnalyzeImpact added in v0.1.16 

func AnalyzeImpact(rootPath, targetSymbol, targetFile string) (*ImpactReport, error)

AnalyzeImpact scans the workspace to compute the blast radius of a symbol.

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 (<1ms) local zero-dependency symbol resolution using an interned path table to minimize memory overhead across massive codebases.

func NewSymbolRAG 

func NewSymbolRAG() *SymbolRAG

NewSymbolRAG creates a new local symbol RAG index.

func (*SymbolRAG) IndexSymbol 

func (sr *SymbolRAG) IndexSymbol(symbol, filePath string)

IndexSymbol records a symbol mapping with interned path storage.

func (*SymbolRAG) RemoveFile 

func (sr *SymbolRAG) RemoveFile(filePath string)

RemoveFile drops every symbol pointing at the given file.

func (*SymbolRAG) Resolve 

func (sr *SymbolRAG) Resolve(symbol string) (string, bool)

Resolve looks up exact symbol matches.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.