query

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 NewEngine(store *graph.Store, project, repoRoot string) *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) Close() 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) Reopen(dbPath string) 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)
  • func (e *Engine) TopByInboundCalls(limit int) ([]graph.Node, error)
• type Hot
• type PackageStat
• type Ref

Functions

func CompactRefs

func CompactRefs(refs []Ref) string

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

func StripProjectPrefix(qn string) string

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 NewEngine

func NewEngine(store *graph.Store, project, repoRoot string) *Engine

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) Callees

func (e *Engine) Callees(qualifiedName string, limit int) ([]Ref, error)

Callees: what this symbol calls (outbound CALLS edges only).

func (*Engine) Callers

func (e *Engine) Callers(qualifiedName string, limit int) ([]Ref, error)

Callers: who calls this symbol (inbound CALLS edges only).

func (*Engine) Close

func (e *Engine) Close() error

Close releases the underlying store. Safe to call multiple times.

func (*Engine) DeadCode

func (e *Engine) DeadCode(limit int) ([]Ref, error)

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

func (e *Engine) DetectChanges() (index.Changes, error)

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) Neighbors

func (e *Engine) Neighbors(qualifiedName string, limit int) ([]Ref, error)

Neighbors: all related nodes, any edge type, both directions.

func (*Engine) Reopen

func (e *Engine) Reopen(dbPath string) error

Reopen closes the current store and opens dbPath. Used after RunAtomic replaces the on-disk graph file while the MCP server is running.

func (*Engine) Search

func (e *Engine) Search(q, label string, limit int) ([]Ref, error)

Search: ranked symbol search (BM25). label optional ("Function", "Class"...).

func (*Engine) Similar

func (e *Engine) Similar(qualifiedName string, limit int) ([]Ref, error)

Similar: near-clone symbols (SIMILAR_TO edges) of this one. The edge is stored once as smaller-QN -> larger-QN, so a clone may sit on either side — hence both directions, filtered to SIMILAR_TO so call/define neighbors don't leak in.

func (*Engine) Snippet

func (e *Engine) Snippet(filePath string, start, end int) (string, error)

Snippet: the actual source for a node (only when the agent needs to read).

func (*Engine) TopByInboundCalls

func (e *Engine) TopByInboundCalls(limit int) ([]graph.Node, error)

TopByInboundCalls returns call-graph hubs for benchmarking and quality tooling.

type Hot

type Hot struct {
	Ref    Ref
	Metric int
}

Hot is a hotspot: a symbol plus its ranking metric (cyclomatic complexity, or inbound caller count).

type PackageStat

type PackageStat struct {
	Dir     string
	Symbols int
}

PackageStat is one directory and how many symbols it holds.

type Ref

type Ref struct {
	Name          string `json:"name"`
	QualifiedName string `json:"qualified_name"`
	Label         string `json:"label"`
	File          string `json:"file"`
	StartLine     int    `json:"start_line"`
	EndLine       int    `json:"end_line"`
}

Ref is the compact reference returned for every symbol.