| name | ast-grep |
| description | Translates natural language queries into ast-grep YAML rules for structural code search using Abstract Syntax Tree (AST) patterns. Use when asked to "find code patterns", "search for specific language constructs", "AST search", "structural search", "ast-grepで検索", "コードパターンを探して", "構造的に検索して", or when text-based grep is insufficient for matching code structure (e.g., "find all async functions that don't handle errors", "find all calls to X inside class Y"). |
ast-grep Code Search
Overview
Translates 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.
General Workflow
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:
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: end for relational rules (inside, has) to ensure search goes to the end of the direction
- Use
pattern for simple structures
- Use
kind with has/inside for complex structures
- Break complex queries into smaller sub-rules using
all, any, or not
Example rule file (test_rule.yml):
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 and references/cli-guide.md for CLI commands and tips.
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)
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)
ast-grep scan --rule test_rule.yml test_example.js
Debugging if no matches:
- Simplify the rule (remove sub-rules)
- Add
stopBy: end to relational rules if not present
- Use
--debug-query to understand the AST structure (see cli-guide.md)
- Check if
kind values are correct for the language
Common errors:
Step 5: Search the Codebase
Once the rule matches the example code correctly, search the actual codebase:
For simple pattern searches:
ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project
For complex rule-based searches:
ast-grep scan --rule my_rule.yml /path/to/project
For inline rules (without creating files):
ast-grep scan --inline-rules "id: my-rule
language: javascript
rule:
pattern: \$PATTERN" /path/to/project
References
references/rule_reference.md: Comprehensive ast-grep rule documentation (atomic, relational, composite rules, metavariables)
references/cli-guide.md: CLI commands, tips for writing effective rules, and common use case examples
Load these references when detailed rule syntax or CLI guidance is needed.