Symbols & References

Structural lookup is the exact, graph-shaped side of RCE Code. Instead of ranking text it answers precise questions about definitions and the edges between them: where is this symbol defined, who refers to it, who calls it, and what does it call. These come from tree-sitter extraction plus a heuristic resolver that links references back to the symbols they name.

Everything here is keyed off the symbols and refs tables. A Symbol is a definition (its name, qualified name, kind, file, line/column span, parent, and signature). A Reference is a call or import site, with the name it targets and — once resolved — the symbol id it points to plus a confidence.

By-name vs. resolved

The single most important distinction is whether a query works purely on names or on the resolved reference graph. Resolution is a best-effort, name-based heuristic — not a type checker — so resolved queries are higher precision but only cover references the resolver was confident about.

• find_references(name) — every reference whose target name matches, resolved or not. Broadest recall; finds all the call/import sites that mention a name.
• get_references_from(symbol_id) — outgoing references that originate inside a symbol's body, by name. These may be unresolved (the target symbol id can be None).
• get_references(symbol_id) — incoming references that the resolver linked to this symbol. Resolved only; these are the confident inbound edges.
• get_callers(symbol_id) / get_callees(symbol_id) — the resolved call graph. Callers are symbols whose body contains a resolved reference to this symbol; callees are symbols this one resolves a reference to. Both return Symbols, not References.

Finding definitions

Several methods locate Symbol definitions. find_symbol(name, kind=None) returns every definition with that exact name, optionally filtered by SymbolKind (e.g. FUNCTION, CLASS, METHOD). get_definitions(file) lists every definition in a file in source order. get_definition_at(file, line, col) returns the innermost symbol whose span contains a position (column is 0-indexed), and get_symbols_in_chunk(chunk_id) returns the definitions that belong to a given chunk — handy for bridging a search hit back to its symbols.

from rce.code import CodeEngine
from rce.code.types import SymbolKind

engine = CodeEngine.open_or_create("/path/to/repo")
engine.index()

# every definition named "authenticate"
for sym in engine.find_symbol("authenticate"):
    print(sym.kind, sym.qualified_name, f"{sym.file_path}:{sym.start_line}")

# only the class definitions named "Session"
classes = engine.find_symbol("Session", kind=SymbolKind.CLASS)

# all definitions in one file, in source order
for sym in engine.get_definitions("src/auth/session.py"):
    print(sym.start_line, sym.kind, sym.qualified_name)

# the innermost symbol at a cursor position (col is 0-indexed)
here = engine.get_definition_at("src/auth/session.py", 42, 8)
engine.close()

Walking the reference graph

With a symbol's id you can traverse edges in both directions. The example below finds a function, lists who calls it and what it calls, and shows the difference between by-name and resolved reference queries.

(sym,) = engine.find_symbol("charge_card")   # assume a single match

# resolved call graph (returns Symbols)
callers = engine.get_callers(sym.id)         # who calls charge_card
callees = engine.get_callees(sym.id)         # what charge_card calls

# resolved incoming references (returns References linked to this symbol)
incoming = engine.get_references(sym.id)

# outgoing references by name from this symbol's body (may be unresolved)
outgoing = engine.get_references_from(sym.id)
for ref in outgoing:
    status = "resolved" if ref.to_symbol_id is not None else "unresolved"
    print(ref.to_name, status, round(ref.resolution_confidence, 2))

# every reference site that names "charge_card", regardless of resolution
all_sites = engine.find_references("charge_card")

# imports only
imports = engine.find_references("requests", is_import=True)

Query-to-method map

CLI

# list every definition in a file (line, kind, qualified name)
rce-code symbols src/auth/session.py

# find definitions named "authenticate" across the repo
rce-code find authenticate

# references to a name (calls + imports; unresolved included)
rce-code refs charge_card
rce-code refs requests --imports     # only import references

# resolved call graph by name
rce-code callers charge_card
rce-code callees charge_card