query

func (*Engine) Affected ¶

func (e *Engine) Affected(files []string, depth int) (AffectedResult, error)

Affected derives impacted test files/symbols for a set of changed files via a depth-bounded BFS over the D-04 reverse-adjacency map, bounded by clampAffectedDepth(depth) (SURF-04/D-05, CONTEXT D-05, RESEARCH Pitfall 2) — NOT the single-hop lookup this used to be. Mirrors Impact's frontier/next-frontier loop shape (traverse.go above), but with the documented test-files-as-leaves pruning rule instead of Impact's "expand everything": a dependent that passes isTestSymbol is recorded as an affected test AND is a leaf — it is never queued for further expansion, so its own dependents can never surface at any depth. A non-test dependent is queued for the next hop and is never itself recorded as an affected test. There is no golden oracle for this command (D-07a); behavior is proved structurally in traverse_test.go against seeded call chains.

RES-02 (WR-04 — 08-REVIEW.md): each frontier node's dispatch siblings (the same dispatchSiblingIDs composition Callers/Impact already apply — every OTHER concrete implementation's same-named method, reached through a shared "implements" edge) are ALSO expanded at every hop, so a changed file's dispatch-reachable test dependents are not silently excluded from affectedTests just because Affected historically only composed the direct reverse-adjacency map. When no implements edges exist in the graph (the common case), dispatch siblings are always empty and this composition is a no-op.

func (*Engine) Callees ¶

func (e *Engine) Callees(symbol string, limit int) (CalleesResult, error)

Callees returns symbol's forward call targets via a direct IterateEdges(srcID) range scan (D-04 — no reverse-adjacency scan needed for the forward direction), capped at limit (0/negative means unlimited, validated by validateLimit before any scan runs, V5).

func (*Engine) Callers ¶

func (e *Engine) Callers(symbol string, limit int) (CallersResult, error)

Callers returns symbol's reverse callers via the D-04 in-memory reverse-adjacency map (built fresh, BuildReverseAdjacency), capped at limit identically to Callees. RES-02: when symbol resolves to a method declared on a type that implements one or more interfaces, callers ALSO include callers of every OTHER implementer's same-named method — a call dispatched dynamically through the shared interface could have reached symbol, so its callers are relevant dispatch targets too (D-06's name-joined traversal, composed from BuildImplementsIndex + a "contains" index — both fresh-per-call, same discipline as BuildReverseAdjacency).

func (*Engine) Explore ¶

func (e *Engine) Explore(query string, maxFiles int) (string, error)

Explore is the flagship one-round-trip command (QRY-08, D-05a, EXPL-02): wires the full explore pipeline in the documented stage order (RESEARCH Architecture Diagram) — tokenize (H1/H2) -> hybrid gather (H3-H6) -> post-merge rerank (H7-H9) -> named-symbol seeding (H13) -> type-hierarchy expansion (H10) -> bounded BFS (H11) -> glue-node injection (H12) -> RWR graph relevance (computeGraphRelevance) -> per-file score tiers + hard exclusion + buried-rescue (H14-H16) -> central-file selection + the 5-way relevance gate + the 5-tier sort (H17-H19) -> render, with H21's adaptive output budget sizing the render. RWR output (not lexical match order) feeds groupMatchesByFile — the RESEARCH Pitfall 1 fix: this REPLACES the lexical matchNodes input construction, not a rerank layered on top of it. groupMatchesByFile/buildBlastEntry/ readSourceFile are unchanged downstream (D-05's "extend, don't replace").

"Matched" symbols shown per selected file (the header's "sym(kind), ..." list and the blast-radius bullets) are the query's actual gather+seed candidates in that file, RWR-score-ordered (not the whole bounded subgraph — showing every BFS/glue/hierarchy-expanded node would flood a file's header with symbols the query never textually or nominally matched, and would break the single-exact-match "1 symbol, 1 file" contract). A file selected purely through structural connectivity (no direct candidate landed in it) falls back to its single highest-RWR-mass subgraph node, so a structurally-selected file is never rendered with an empty symbol list.

query is rejected if empty/whitespace-only (WR-05, mirroring Query/Search) rather than falling through to a tokenizer's degenerate "matches everything" case; the tokenizers themselves also return empty for empty input (plan 03) — two layers, per the threat model's T-01-25 disposition.

func (*Engine) Files ¶

func (e *Engine) Files(opts FilesOptions) (FilesResult, error)

Files browses the indexed file structure from the graph (QRY-07): it reads e.reader.IterateFiles() only — never os.ReadDir or any other live filesystem walk — so the result reflects the frozen point-in-time graph even if the working tree has since changed underneath it. pattern narrows by glob match on the full path, filter narrows by exact Language match, dir narrows by path prefix (SURF-02, orthogonal to and composed with filter), depth bounds directory nesting, and format selects the flat-list vs. nested-tree projection. The returned set is additionally capped at MaxLimit entries (T-03-05-DoS, "cap the returned set").

func (*Engine) Impact ¶

func (e *Engine) Impact(symbol string, depth int) (ImpactResult, error)

Impact returns the depth-bounded reverse blast radius of symbol: a BFS over the D-04 reverse-adjacency map, bounded by clampDepth(depth) (T-03-04-DoS, RESEARCH Pitfall 4). NodeCount is the count of distinct visited nodes including symbol itself; EdgeCount is the count of reverse edges inspected while expanding each depth's frontier — this counting rule is cross-checked against testdata/golden/corpus/weft-go/impact.json's arithmetic in traverse_test.go's TestImpact doc comment. RES-02: at each frontier node, dispatch siblings (same composition Callers uses — every OTHER implementer's same-named method, reached via a shared "implements" edge) are ALSO expanded, so a change's blast radius includes callers reachable only through dynamic dispatch. When no implements edges exist in the graph (the common case, and every pre-existing fixture this method's tests exercise), dispatch siblings are always empty and this composition is a no-op — the arithmetic above is unchanged.

func (*Engine) Node ¶

func (e *Engine) Node(symbol, file string, line *int) (string, error)

Node renders symbol detail (QRY-02, D-05b) when symbol is non-empty, or a line-numbered verbatim file read when symbol is empty and file is given. file additionally disambiguates symbol when both are supplied. line is an optional NODE-03 narrowing hint (RESEARCH §9); a nil line with a non-empty file tries resolveNodeForDetail's existing exact-match single-winner behavior FIRST and returns immediately on success, so every pre-CR-02 exact-match caller — the CLI's `-f`/`--file` flag used without `--line`, and any existing golden fixture — gets byte-for-byte identical output (NODE-04). When symbol is given without file, or when the exact-match attempt above didn't apply/succeed, Node enumerates every exact-name definition (NODE-01) and narrows it via narrowNodeMatches (NODE-03: substring file hint + line-containment hint, never emptying the set — a pure in-memory filter, D-07, never a fresh disk read keyed on the raw hint): a single narrowed match renders via the original single-def RenderNode path unchanged (NODE-04's no-hints case is a no-op through narrowNodeMatches), while multiple narrowed matches render via NODE-02's multi-def budget/overflow path (RenderNodeMultiDef).

func (*Engine) Query ¶

func (e *Engine) Query(term, kind string, limit int) ([]*schema.Node, error)

Query returns full node records whose name or qualifiedName matches term (D-06), optionally filtered by kind and capped at limit. term is validated non-empty (WR-05 — an empty/whitespace-only term would otherwise match every node via lexicalMatchTier's degenerate strings.HasPrefix(field, "") == true case, a "dump the whole graph" footgun compounding CR-01), kind is validated via ValidateKind, and limit via validateLimit, all before any scan runs (V5, T-03-03-Kind, T-03-03-DoS) — an empty term, unknown kind, or out-of-range limit returns an error without touching the store.

func (*Engine) Search ¶

func (e *Engine) Search(term, kind string, limit int) ([]Location, error)

Search returns the same matches as Query, but projected to the lightweight Location shape (D-06) — no source body, no signature. term/kind/limit are validated identically to Query, before any scan.

func (*Engine) Status ¶

func (e *Engine) Status(ctx context.Context) (StatusResult, error)

Status reports index health/counts (QRY-09) by scanning the frozen graph: fileCount + filesByLanguage from a single IterateFiles scan, nodeCount + nodesByKind from a single IterateNodes scan, and edgesByKind from a single full edge-iteration scan (v0.11.0 Phase 1, FIXT-01) mirroring buildExpandAdjacency's established full-scan shape (internal/query/expand.go), unfiltered by RankEdges so a kind outside the 9-kind ranked set is still tallied. edgeCount itself still comes from GetMeta's indexer-stamped Meta.EdgeCount aggregate (internal/indexer/resolve.go) — a separate read from edgesByKind, not a sum of it.

A full edge scan is now UNCONDITIONAL on every status call — previously this method read only Meta.EdgeCount and never scanned edges at all. edgesByKind is deliberately derived fresh at read time on every call and never stored in Meta: D-01 scopes this phase to `status`, not to indexer/Meta changes, so a future phase MAY choose to stamp a per-kind aggregate at index time to remove this scan's cost — a real, named future optimization, not an oversight. Edge keys are `edge/<src>/<kind>/<dst>` with no leading kind segment (internal/graphstore/keys.go), so no cheaper per-kind prefix scan is available today: one full scan tallying every kind at once is the correct and only reasonable approach given the current key layout.

Every scan-derived count in the returned StatusResult (fileCount, nodeCount, nodesByKind, filesByLanguage, edgesByKind) comes from the SAME e.reader snapshot, so they are mutually consistent with each other. Meta.EdgeCount, by contrast, is a separately-stamped aggregate the indexer writes at index time — while a background re-index is in flight, it may legitimately disagree with the sum of edgesByKind. That disagreement is a true reading of an index mid-write, not a bug.

languages is derived from filesByLanguage (D-05: count > 0, sorted), not from a separate node-scan languageSet, so it reflects every file the indexer discovered and stored — including a file that yields zero extracted nodes — rather than only files with at least one resolved node. A missing Meta record (a store that exists but was never indexed) is tolerated rather than treated as an error: counts fall back to the scanned values and index.state reports "not_indexed".

ctx (WR-01) is threaded through to WorktreeMismatch, which spawns up to four git subprocesses — see WorktreeMismatch's doc comment for why this must be the caller's real, cancelable context rather than context.Background().

func (*Engine) UseDetector ¶

func (e *Engine) UseDetector(d *gitmeta.CachingDetector)

UseDetector installs a shared, caller-owned gitmeta.CachingDetector that WorktreeMismatch will route detection through instead of computing an uncached, Engine-private verdict.

This exists because internal/mcp's openEngine builds a FRESH Engine on every single tool call by design (D-02/D-08b, RESEARCH Pitfall 2) — an Engine-scoped cache alone (the mismatchOnce/mismatchCache fields below) yields ZERO cross-call benefit on the exact long-lived surface (the MCP server process) the cache exists to help, since a brand-new Engine means a brand-new sync.Once every time. internal/mcp therefore constructs ONE CachingDetector per server (BuildServer) and calls UseDetector on every Engine it opens, so all tool calls within one server's lifetime share a single git-subprocess-avoiding cache (D-13, corrected). The CLI needs no such call — it constructs at most one Engine per invocation, so the per-Engine cache alone is already free.

func (*Engine) WorktreeMismatch ¶

func (e *Engine) WorktreeMismatch(ctx context.Context) *gitmeta.Mismatch

WorktreeMismatch returns the live worktree/index-mismatch verdict for this Engine (D-14/WORK-01): whether startPath (where the caller stood) belongs to a DIFFERENT git working tree than repoRoot (the resolved index root). Detection runs at most once per Engine (guarded by mismatchOnce) — Status() and any render path that also calls this method within one request never re-spawn git.

ctx (WR-01) is threaded all the way down to the underlying git subprocesses (up to four, gitmeta.DetectIndexMismatch's doc comment) — every MCP handler and CLI command already receives a real, cancelable context (the handler's ctx / cmd.Context()); before WR-01 this method discarded it in favor of context.Background(), so a client that disconnected or timed out still left up to ~20s of uncancellable git subprocess work running with no way to abort it.

Returns nil, without ever panicking, when this Engine has no filesystem context to check: startPath == "" or repoRoot == "" (Engines built via New/NewWithRoot — the same degrade-safely shape computeStale already uses for e.repoRoot == ""). Otherwise delegates to e.detector.Detect, which is nil-receiver-safe (falls through to an uncached gitmeta.DetectIndexMismatch when no detector was injected via UseDetector) — so no nil branch is needed here.

BL-01 note: mismatchOnce/mismatchCache latch a verdict computed under a cancelled ctx too — but that is safe HERE, unlike gitmeta.CachingDetector. internal/mcp's openEngine builds a brand-new Engine (and therefore a brand-new mismatchOnce) on every single tool call, so this per-Engine latch never outlives one request; the long-lived poisoning risk lives entirely in the server-scoped CachingDetector this method delegates to, which is why BL-01's fix (never caching a cancelled-ctx verdict) lives in gitmeta.CachingDetector.Detect, not here. The CLI is unaffected for a different reason: cmd.Context() is always context.Background() today (IN-01, uncancellable), so a cancelled ctx never reaches this method on that surface at all.