Documentation
¶
Overview ¶
Package query turns store calls into compact, agent-friendly results.
Token-efficiency principle: every result is a small struct (name + file + line + label), NEVER source code. The agent asks for Snippet only when it actually needs to read code. That selectivity is where the 10x token saving comes from — see docs/ARCHITECTURE.md.
Index ¶
- func CompactRefs(refs []Ref) string
- func RenderArchitecture(a Architecture) string
- func StripProjectPrefix(qn string) string
- type Architecture
- type Engine
- func (e *Engine) Architecture(topN int) (Architecture, error)
- func (e *Engine) Callees(qualifiedName string, limit int) ([]Ref, error)
- func (e *Engine) Callers(qualifiedName string, limit int) ([]Ref, error)
- func (e *Engine) DeadCode(limit int) ([]Ref, error)
- func (e *Engine) DetectChanges() (index.Changes, error)
- func (e *Engine) Neighbors(qualifiedName string, limit int) ([]Ref, error)
- func (e *Engine) Search(q, label string, limit int) ([]Ref, error)
- func (e *Engine) Similar(qualifiedName string, limit int) ([]Ref, error)
- func (e *Engine) Snippet(filePath string, start, end int) (string, error)
- type Hot
- type PackageStat
- type Ref
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CompactRefs ¶
CompactRefs renders refs as the token-efficient wire format: one tab-separated line per ref — `label<TAB>name<TAB>file:line<TAB>qn`. No repeated JSON keys, and the project prefix is stripped from the qualified name (the engine re-adds it on input, so a returned qn can be passed straight back to callers/callees). This is the format the MCP/CLI tools return AND the format the benchmark meters, so the reported token win reflects the real product, not a measurement trick.
func RenderArchitecture ¶
func RenderArchitecture(a Architecture) string
RenderArchitecture renders the map as a compact, token-frugal digest — counts on one line each, hotspots as `name<TAB>file:line<TAB>metric`.
func StripProjectPrefix ¶
StripProjectPrefix drops the `project:` prefix from a qualified name. The rest is still globally unambiguous within a project, so it round-trips through normalizeQN on the next query.
Types ¶
type Architecture ¶
type Architecture struct {
Languages map[string]int
NodeCounts map[string]int
EdgeCounts map[string]int
Packages []PackageStat
ComplexityHotspots []Hot
CallHubs []Hot
}
Architecture is the compact repo map get_architecture returns.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine wraps a store + repo root for a single project.
func (*Engine) Architecture ¶
func (e *Engine) Architecture(topN int) (Architecture, error)
Architecture aggregates the graph into a one-shot repo overview: languages, node/ edge counts, top packages by symbol count, and the complexity/call-hub hotspots. All from stored data — no re-scan — so an agent gets direction in a single call instead of grepping its way in. Hotspots read the M4 cyclomatic complexity.
func (*Engine) DeadCode ¶
DeadCode lists private Function/Method nodes the graph sees no caller for: zero inbound CALLS, minus the entry points whose callers can't be in-graph by design — exported symbols (public API), decorated members (framework-invoked), main/init, and test functions.
It is a candidate list to investigate, NOT a delete list. Precision is bounded by CALLS recall: a real caller the resolver missed, or an indirect reference (function value, interface dispatch, reflection), makes a live function look dead. On cobra, the top results were mostly such false positives — but it did surface `appendIfNotPresent`, which cobra's own source marks unused. The agent must confirm each (e.g. grep the name) before acting.
func (*Engine) DetectChanges ¶
DetectChanges reports which source files changed since the last index — the staleness check behind the detect_changes tool. The agent can tell whether the graph is fresh for a region, and re-index if not (cheap now: scope-gated).
func (*Engine) Search ¶
Search: ranked symbol search (BM25). label optional ("Function", "Class"...).
type Hot ¶
Hot is a hotspot: a symbol plus its ranking metric (cyclomatic complexity, or inbound caller count).
type PackageStat ¶
PackageStat is one directory and how many symbols it holds.
Source Files