trace
Walk the code graph from starting nodes along specified edges to return a deduplicated subgraph of reachable structure, with configurable depth and node limits.
Instructions
Python: Bounded multi-hop BFS traversal — returns a typed Subgraph.
The composition primitive: it walks the follow edges outward from
start across multiple hops, deduping by canonical handle, and returns a
Subgraph of the reachable structure. Use resolve()/inspect() to obtain
canonical handles first, then trace() to see structure across hops (call
chains, reverse-import closures, member trees).
Composes the same edge registry as expand; the implemented edges
(members, callees, imported_by, subclasses, superclasses,
imports, enclosing_scope) are traversed. Any other edge named in
follow (deferred reference edges, unknown names) is reported in
unsupported_edges rather than silently dropped — a silent drop would
falsely read as "no such neighbours".
Response shape — Subgraph::
{ "nodes": { handle: Stub, ... }, # deduped by canonical handle
"edges": [ {"from": h, "to": h, "kind": edge}, ... ],
"truncated": bool, # a cap cut off reachable nodes
"truncation_reasons": ["max_depth"?, "max_nodes"?], # which cap(s) fired
"unsupported_edges": [ {"edge", "reason", "detail"}, ... ] }Edges are NOT deduped across kinds; edges to already-visited handles are
recorded (so cycles stay visible) but never re-expanded, guaranteeing
termination on cyclic graphs. truncated is true ONLY when max_depth
or max_nodes cut off reachable handles before natural termination — not
merely because a cap was set.
Args:
start: One canonical handle, or a list of them, as BFS roots.
follow: Edge names to traverse at every hop (e.g. ["members"],
["callees"], ["imported_by"]).
project_path: Project root path (default: current directory).
max_depth: Maximum hop distance from a root before a node becomes a
non-expanded frontier leaf (default 3).
max_nodes: Maximum number of distinct nodes in the subgraph; reaching it
sets truncated (default 50).
stop_when: Optional StopPredicate (exclude_external /
module_pattern / exclude_tests); a matching adjacent is a
pruned boundary. Roots are never pruned. exclude_external stops
at stdlib/site-packages nodes — keeps a trace inside the project (the
common callees case).
Returns:
A Subgraph dict (plain, JSON-serialisable). Never raises; an
unresolvable root simply contributes no node.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start | Yes | ||
| follow | Yes | ||
| project_path | No | . | |
| max_depth | No | ||
| max_nodes | No | ||
| stop_when | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||