ast-grep
提供基于抽象语法树的结构化代码搜索能力,支持跨语言精准匹配代码模式、定位特定语法结构、识别复杂代码特征,适用于需理解代码语义而非简单文本匹配的深度代码分析场景。
| name | ast-grep |
| description | Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics. |
ast-grep Code Search
Overview
This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.
When to Use This Skill
Use this skill when users:
- Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
- Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
- Request searches that require understanding code structure rather than just text
- Ask to search for code with particular AST characteristics
- Need to perform complex code queries that traditional text search cannot handle
General Workflow
Follow this process to help users write effective ast-grep rules:
Step 1: Understand the Query
Clearly understand what the user wants to find. Ask clarifying questions if needed:
- What specific code pattern or structure are they looking for?
- Which programming language?
- Are there specific edge cases or variations to consider?
- What should be included or excluded from matches?
Step 2: Create Example Code
Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.
Example: If searching for "async functions that use await", create a test file:
▼javascript复制代码// test_example.js async function example() { const result = await fetchData(); return result; }
Step 3: Write the ast-grep Rule
Translate the pattern into an ast-grep rule. Start simple and add complexity as needed.
Key principles:
- Always use
stopBy: endfor relational rules (inside,has) to ensure search goes to the end of the direction - Use
patternfor simple structures - Use
kindwithhas/insidefor complex structures - Break complex queries into smaller sub-rules using
all,any, ornot
Example rule file (test_rule.yml):
▼yaml复制代码id: async-with-await language: javascript rule: kind: function_declaration has: pattern: await $EXPR stopBy: end
See references/rule_reference.md for comprehensive rule documentation.
Step 4: Test the Rule
Use ast-grep CLI to verify the rule matches the example code. There are two main approaches:
Option A: Test with inline rules (for quick iterations)
▼bash复制代码echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules "id: test language: javascript rule: kind: function_declaration has: pattern: await \$EXPR stopBy: end" --stdin
Option B: Test with rule files (recommended for complex rules)
▼bash复制代码ast-grep scan --rule test_rule.yml test_example.js
Debugging if no matches:
- Simplify the rule (remove sub-rules)
- Add
stopBy: endto relational rules if not present - Use
--debug-queryto understand the AST structure (see below) - Check if
kindvalues are correct for the language - For zero matches from
run --pattern(not rules), see the "Zero Matches?" tip below
Step 5: Search the Codebase
Once the rule matches the example code correctly, search the actual codebase:
For simple pattern searches:
▼bash复制代码ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project
For complex rule-based searches:
▼bash复制代码ast-grep scan --rule my_rule.yml /path/to/project
For inline rules (without creating files):
▼bash复制代码ast-grep scan --inline-rules "id: my-rule language: javascript rule: pattern: \$PATTERN" /path/to/project
ast-grep CLI Commands
Inspect Code Structure (--debug-query)
Dump the AST structure to understand how code is parsed:
▼bash复制代码ast-grep run --pattern 'async function example() { await fetch(); }' \ --lang javascript \ --debug-query=cst
Available formats:
cst: Concrete Syntax Tree (shows all nodes including punctuation)ast: Abstract Syntax Tree (shows only named nodes)pattern: Shows how ast-grep interprets your pattern
Use this to:
- Find the correct
kindvalues for nodes - Understand the structure of code you want to match
- Debug why patterns aren't matching
Example:
▼bash复制代码# See the structure of your target code ast-grep run --pattern 'class User { constructor() {} }' \ --lang javascript \ --debug-query=cst # See how ast-grep interprets your pattern ast-grep run --pattern 'class $NAME { $$$BODY }' \ --lang javascript \ --debug-query=pattern
Test Rules (scan with --stdin)
Test a rule against code snippet without creating files:
▼bash复制代码echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test language: javascript rule: pattern: await \$EXPR" --stdin
Add --json for structured output:
▼bash复制代码echo "const x = await fetch();" | ast-grep scan --inline-rules "..." --stdin --json
Search with Patterns (run)
Simple pattern-based search for single AST node matches:
▼bash复制代码# Basic pattern search ast-grep run --pattern 'console.log($ARG)' --lang javascript . # Search specific files ast-grep run --pattern 'class $NAME' --lang python /path/to/project # JSON output for programmatic use ast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .
When to use:
- Simple, single-node matches
- Quick searches without complex logic
- When you don't need relational rules (inside/has)
Reading --json Output
--json prints a bare JSON array of matches (no matches wrapper). For pattern foo($ARG, $$$REST):
▼json复制代码[{ "text": "foo(\"value\", 1, 2)", "file": "src/app.js", "range": { "start": { "line": 41, "column": 10 }, "end": { "line": 41, "column": 27 } }, "metaVariables": { "single": { "ARG": { "text": "\"value\"" } }, "multi": { "REST": [ { "text": "1" }, { "text": "2" } ] } } }]
scan --json uses the same schema.
(Each match also includes lines and language.) range.start.line is 0-based. Named metavariables ($ARG) land in single, list metavariables ($$$REST) in multi as a list (empty if nothing captured). Extract with jq:
▼bash复制代码ast-grep run --pattern 'foo($ARG)' --lang javascript --json . \ | jq -r '.[] | "\(.file):\(.range.start.line + 1): \(.metaVariables.single.ARG.text)"'
Search with Rules (scan)
YAML rule-based search for complex structural queries:
▼bash复制代码# With rule file ast-grep scan --rule my_rule.yml /path/to/project # With inline rules ast-grep scan --inline-rules "id: find-async language: javascript rule: kind: function_declaration has: pattern: await \$EXPR stopBy: end" /path/to/project # JSON output ast-grep scan --rule my_rule.yml --json /path/to/project
When to use:
- Complex structural searches
- Relational rules (inside, has, precedes, follows)
- Composite logic (all, any, not)
- When you need the power of full YAML rules
Tip: For relational rules (inside/has), always add stopBy: end to ensure complete traversal.
Tips for Writing Effective Rules
Always Use stopBy: end
For relational rules, always use stopBy: end unless there's a specific reason not to:
▼yaml复制代码has: pattern: await $EXPR stopBy: end
This ensures the search traverses the entire subtree rather than stopping at the first non-matching node.
Start Simple, Then Add Complexity
Begin with the simplest rule that could work:
- Try a
patternfirst - If that doesn't work, try
kindto match the node type - Add relational rules (
has,inside) as needed - Combine with composite rules (
all,any,not) for complex logic
Use the Right Rule Type
- Pattern: For simple, direct code matching (e.g.,
console.log($ARG)) - Kind + Relational: For complex structures (e.g., "function containing await")
- Composite: For logical combinations (e.g., "function with await but not in try-catch")
Debug with AST Inspection
When rules don't match:
- Use
--debug-query=cstto see the actual AST structure - Check if metavariables are being detected correctly
- Verify the node
kindmatches what you expect - Ensure relational rules are searching in the right direction
Zero Matches? Patterns Match Whole AST Nodes
run --pattern matches complete AST nodes, not text substrings, so zero matches can mean "code absent" or "pattern has the wrong node shape":
- Qualified paths are whole nodes:
env::var($ENV)does NOT matchstd::env::var("X"). Try both bare and fully-qualified forms, or use$$$to absorb extra intermediate nodes. - To tell them apart: test the pattern on a snippet known to contain the code, and inspect how ast-grep parsed it with
--debug-query=pattern(works forrun, not justscan/rules). For zero matches from rules instead, follow the Step 4 debugging checklist.
Escaping in Inline Rules
When using --inline-rules, escape metavariables in shell commands:
- Use
\$VARinstead of$VAR(shell interprets$as variable) - Or use single quotes:
'$VAR'works in most shells
Example:
▼bash复制代码# Correct: escaped $ ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" . # Or use single quotes ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .
Common Use Cases
Find Functions with Specific Content
Find async functions that use await:
▼bash复制代码ast-grep scan --inline-rules "id: async-await language: javascript rule: all: - kind: function_declaration - has: pattern: await \$EXPR stopBy: end" /path/to/project
Find Code Inside Specific Contexts
Find console.log inside class methods:
▼bash复制代码ast-grep scan --inline-rules "id: console-in-class language: javascript rule: pattern: console.log(\$\$\$) inside: kind: method_definition stopBy: end" /path/to/project
Find Code Missing Expected Patterns
Find async functions without try-catch:
▼bash复制代码ast-grep scan --inline-rules "id: async-no-trycatch language: javascript rule: all: - kind: function_declaration - has: pattern: await \$EXPR stopBy: end - not: has: pattern: try { \$\$\$ } catch (\$E) { \$\$\$ } stopBy: end" /path/to/project
Resources
references/
Contains detailed documentation for ast-grep rule syntax:
rule_reference.md: Comprehensive ast-grep rule documentation covering atomic rules, relational rules, composite rules, and metavariables
Load these references when detailed rule syntax information is needed.









