tsa-graph

name: tsa-graph version: 2.0.0 description: | Code archaeology via call graph + symbol resolution. Answer "who calls X", "what does Y call", "where is Z defined", "what's the path from A to B" in one MCP call instead of multi-step grep + read. Uses persisted cross-file resolution (Synapse) so cross-module edges are precise, not regex-guessed.

Use when:

• User asks "what calls this function" / "what does this function call"
• Tracing a bug through layers (impact → caller chain)
• Planning refactor of a function/class (need full fanout)
• "Where is this symbol defined" / "find all references to X"
• "Show me the path from handler → DB"
• "Draw a UML class/package/component/sequence diagram"

Replaces: grep + read + manual chain-following (10-30k tokens) with 2-4 MCP calls (1-3k tokens). allowed-tools: - mcp__tree-sitter-analyzer__nav - mcp__tree-sitter-analyzer__search - mcp__tree-sitter-analyzer__structure - mcp__tree-sitter-analyzer__health - mcp__tree-sitter-analyzer__viz - Bash - Read

tsa-graph — Code archaeology, one call deep

This skill exposes the graph-focused tools that answer "who is connected to what" — the questions agents waste the most tokens on when they fall back to grep.

When to use

Pick the right tool by question shape:

Don't use when:

• You need the actual body of the function → use structure action=read
• You're hunting a string literal in non-source files → use Grep

Procedure

Single-question case (90% of uses)

Pick the matching tool, call once. Read the response. Done.

Example: "what calls score_file?"

nav action=callers function_name="score_file" language="python" limit=20

Returns: callers: [{name, file, line, callee_resolution, callee_resolved_file}, ...]. The callee_resolution field tells you local / project / stdlib / unknown so you can filter out noise.

When a question needs several graph hops plus source snippets, prefer the chain surface:

search action=chain query="search('score_file').explore(max_files=3).callers(depth=1).callees(depth=1)"

Multi-step case (refactor planning)

Fan out 3 in parallel:

1. nav action=callers (who depends on this — blast radius)
2. nav action=callees (what this depends on — what may need updating)
3. search action=symbol with the symbol name (find aliases / shadows)

Then if you need a specific reachability path:

nav action=call_path from_function="X" to_function="Y" max_depth=10

Reading the new resolution fields (Synapse)

Each callee entry now carries:

name: "Path"
file: ".../health_scorer.py"
line: 366
callee_resolution: stdlib | local | project | third_party | dynamic | unknown
callee_resolved_file: "" | "<file the callee lives in>"
callee_symbol_id: null | <int FK to ast_symbol_rows>

Filter rules of thumb:

• resolution=stdlib → ignore for change-impact (won't be in this repo)
• resolution=local|project with non-null callee_symbol_id → trustworthy edge
• resolution=unknown → may need re-index: uv run tree-sitter-analyzer --ast-cache --ast-cache-mode index --ast-cache-force

CLI equivalents

uv run tree-sitter-analyzer --callees <FUNC> --output-format toon
uv run tree-sitter-analyzer --callers <FUNC> --output-format toon
uv run tree-sitter-analyzer --symbol-search <NAME> --output-format toon
uv run tree-sitter-analyzer --codegraph-xref <SYMBOL> --output-format toon
uv run tree-sitter-analyzer --call-path --call-path-source X --call-path-target Y
uv run tree-sitter-analyzer --uml class --output-format toon

Anti-patterns

• Don't grep -rn "def X" tree_sitter_analyzer/ — use search action=symbol (10x faster, precise)
• Don't read 5 files to trace a call chain — use nav action=call_path
• Don't ignore callee_resolution — unknown entries are noise, filter them

Decision surface

function: <queried name>
callee_count | caller_count: <int>
callees | callers: [
  {name, file, line, language, callee_resolution, callee_resolved_file}
]
verdict: INFO   # graph queries are observational, not actionable