AST & Code Graph Indexing

Overview

Text-based search (grep, ripgrep) finds string matches. AST-based analysis understands structure — it knows the difference between a function definition, a function call, a comment, and a string literal.

Primary tool: ast-grep (sg / ast-grep) — a fast, Rust-based CLI for structural code search, lint, and rewriting. It uses tree-sitter for parsing and supports 20+ languages out of the box.

Core principle: When the question is about code structure, use AST analysis. When the question is about text content, use grep.

When to Use

Use this skill when the task involves:

Task	Why AST beats grep
Refactoring / renaming	Grep finds the string in comments and strings too; AST finds only the symbol
Dead code detection	Grep can't tell if an export is actually imported elsewhere
Dependency tracing	"What modules does X depend on?" requires understanding `import`/`require`
Impact analysis	"If I change function X, what breaks?" needs call-graph traversal
Circular dependency detection	Requires building and analyzing a full import graph
Code migration	Rewriting deprecated API patterns structurally across a codebase
Custom linting	Enforcing project-specific patterns that standard linters don't cover

Don't use this skill when:

Searching for a specific string, error message, or config value → use grep
Finding files by name or extension → use find/fd
The codebase is < 5 files and you can read them all → just read them

Prerequisites

Before using this tool for searches, you MUST check if ast-grep is installed natively on the system:

which ast-grep || which sg

If it is installed, use the native binary directly for semantic searches. Do not attempt to run it via Docker containers or complex wrapper scripts unless absolutely necessary.

If it is not installed, you can install it using one of the following methods depending on the OS:

Node.js: npm install -g @ast-grep/cli
MacOS (Homebrew): brew install ast-grep
Rust (Cargo): cargo install ast-grep --locked

Phase 1: Search — Find Code by Structure

ast-grep (recommended — all languages)

ast-grep uses pattern syntax that looks exactly like the code you're searching for, using $METAVAR wildcards to match any AST node.

Basic pattern search:

# Find all calls to console.log
ast-grep -p 'console.log($MSG)' -l js src/

# Find all require() calls
ast-grep -p 'require($MOD)' -l js src/

# Find all async functions
ast-grep -p 'async function $NAME($$$PARAMS) { $$$BODY }' -l js src/

# Find if-else without braces
ast-grep -p 'if ($COND) $STMT' -l js src/

Key metavariable syntax:

$NAME — matches a single AST node (like regex .). Example: foo($ARG) matches foo(a) but NOT foo(a, b).
$$$ARGS — matches zero or more nodes (like regex .*). Example: foo($$$ARGS) matches foo(), foo(a), and foo(a, b). This is the most common pitfall! Default to $$$ when matching arguments or block bodies unless you strictly want one node.
$_ — anonymous match (when you don't need to reference it later).

TypeScript generic calls require a separate pattern:

In TypeScript/TSX, a call like useState<string>('') has <string> as a separate type_arguments AST node. The pattern useState($$$ARGS) will NOT match it. You need two passes for full coverage:

# Non-generic calls (works for all languages)
ast-grep -p 'useState($$$ARGS)' src/

# Generic TypeScript calls like useState<T>()
ast-grep -p 'useState<$T>($$$ARGS)' -l tsx src/
ast-grep -p 'useState<$T>($$$ARGS)' -l ts src/

Use $$$T instead of $T if the type argument can be a union like string | null.

Search with rewrite preview:

# Preview replacing var with const
ast-grep -p 'var $NAME = $VALUE' -r 'const $NAME = $VALUE' -l js src/

# Apply interactively (prompts y/n per match)
ast-grep -p 'var $NAME = $VALUE' -r 'const $NAME = $VALUE' -l js --interactive src/

See ast-grep-cheatsheet.md for the full pattern reference.

Phase 2: Pipeline JSON Output to Scripts

Often, simply printing matches to the terminal isn't enough. For complex analysis, you should export the matches as JSON and process them with a script. This is highly recommended for building graphs, finding dead code, or generating reports.

Generate and save JSON:

# Export all function definitions to a file for secondary analysis
ast-grep -p 'function $NAME($$$PARAMS) { $$$BODY }' -l typescript --json src/ > functions.json

Then, write a quick Python or Node.js script to read functions.json and extract the specific node text, line numbers, or relationships you need! (e.g., parsing the JSON to find functions that have a specific naming convention or parsing out all import sources to build a dependency graph).

Phase 3: Complex Workflows (Step-by-Step)

Here are detailed methodologies for solving complex structural problems:

Workflow A: Impact Analysis (What breaks if I change X?)

Search: Find the definition of the target symbol X using ast-grep and ensure you have its exact name and module path.
Find Direct Callers: Use ast-grep to find all import statements that import X, and all function calls to X(). Save these results to a JSON file.
Analyze: If the codebase is large, write a quick script to parse the JSON and list the files/functions that call X.
Iterate (Transitive Callers): If necessary, repeat the process for the functions that call X to build a full call graph. (Alternatively, if this is a Python project, use the bundled build-graph.py script as shown in Phase 4).

Workflow B: Safe Refactoring / Migration

Search: ast-grep -p '<pattern>' src/ to find all matches of the old pattern.
Review: Add --json to inspect match details and ensure your pattern isn't capturing unintended code boundaries (e.g. ensure you used $$$BODY for blocks, not $BODY).
Preview: Add -r '<rewrite>' to see the replacement printed to stdout. Check a few edge cases.
Apply: Add --interactive to selectively apply changes, or remove --interactive if you're 100% confident (though you should usually trust but verify).
Verify: Re-run the search pattern ast-grep -p '<pattern>' and ensure it returns 0 matches.

Renaming a symbol requires multiple passes — function definitions, call sites, and import/export statements are structurally distinct AST node types, so a single pattern won't catch all of them:

# Pass 1: rename the definition
ast-grep -p 'function oldName($$$P) { $$$B }' -r 'function newName($$$P) { $$$B }' -l ts src/

# Pass 2: rename all call sites (also catches bare references like arr.map(oldName))
ast-grep -p 'oldName($$$ARGS)' -r 'newName($$$ARGS)' -l ts src/

# Pass 3: rename named imports
ast-grep -p 'import { oldName } from $MOD' -r 'import { newName } from $MOD' -l ts src/

Note: AST matching is exact on identifiers, so oldNameHelper will NOT be affected — unlike a naive sed replace.

Phase 4: Bundled Graph Builders (Fallback)

While ast-grep + JSON pipelines are powerful, this skill includes bundled scripts for common graph building tasks when you need full AST traversal beyond simple pattern matching.

Use these particularly when checking for dead code or circular dependencies.

🤖 Note to AI Agent: When calling these bundled scripts, you must construct an absolute path by replacing <SKILL_DIR> with the absolute directory path where this SKILL.md file is located. Do not execute these with relative paths from the user's project root, or they will fail.

Python codebases:

python3 <SKILL_DIR>/scripts/build-graph.py <directory> [flags]

# Common Flags:
# --callers <symbol>  (find direct and transitive callers)
# --unused            (find dead code / unreferenced symbols)
# --depends-on <mod>  (find reverse dependencies)
# --cycles            (detect circular imports)

JavaScript/TypeScript codebases:

# Export a quick symbol list with line numbers
node <SKILL_DIR>/scripts/parse-js.mjs <file> --symbols

Quick Reference

I want to...	ast-grep command
Find all calls to `foo()`	`ast-grep -p 'foo($$$ARGS)' src/`
Find function definitions	`ast-grep -p 'function $NAME($$$P) { $$$B }' src/`
Find unused imports	`ast-grep scan --inline-rules '...' src/`
Rename `oldFn` → `newFn`	3 passes: definition, call sites, imports (see Workflow B)
Convert `var` → `const`	`ast-grep -p 'var $N = $V' -r 'const $N = $V' --interactive src/`
JSON output for scripting	`ast-grep -p '<pattern>' --json src/ > out.json`
Check change impact	Build graph → find all transitive callers (reverse BFS)

Supporting Files

ast-grep-cheatsheet.md — Full ast-grep pattern and CLI reference
graph-schema.md — Node and edge type definitions with ER diagram
query-patterns.md — Detailed cookbook of query patterns with examples
scripts/parse-js.mjs — Cross-platform Node.js script for JS/TS AST parsing
scripts/build-graph.py — Python code graph builder

ast-code-graph