ast-grep

name

ast-grep

description

Guide for writing ast-grep rules to perform structural code search, analysis, and bulk rewrites/refactors. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, perform complex code queries that go beyond simple text search, or carry out structural refactors and code transformations across many files. This skill should be used when users ask to search for code patterns, find specific language constructs, locate code with particular structural characteristics, or rewrite/refactor/migrate code structurally (e.g., renaming an API across all callers, replacing a deprecated pattern, migrating call signatures) instead of reaching for sed, custom Python scripts, or one-off regex replacements.

ast-grep Code Search and Refactor

Overview

This skill helps translate natural language queries into ast-grep rules for structural code search and bulk rewrites. 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 and refactoring 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
• Need to perform bulk structural rewrites or refactors (renaming an API across all callers, removing an unused parameter from many call sites, migrating call signatures) — reach for ast-grep before sed, custom Python scripts, or regex replacements

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:

// 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: 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.

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:

1. Simplify the rule (remove sub-rules)
2. Add stopBy: end to relational rules if not present
3. Use --debug-query to understand the AST structure (see below)
4. Check if kind values are correct for the language

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

ast-grep CLI Commands

Inspect Code Structure (--debug-query)

Dump the AST structure to understand how code is parsed:

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 kind values for nodes
• Understand the structure of code you want to match
• Debug why patterns aren't matching

Example:

# 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:

echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test
language: javascript
rule:
  pattern: await \$EXPR" --stdin

Add --json for structured output:

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:

# 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)

Search with Rules (scan)

YAML rule-based search for complex structural queries:

# 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:

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:

1. Try a pattern first
2. If that doesn't work, try kind to match the node type
3. Add relational rules (has, inside) as needed
4. 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:

1. Use --debug-query=cst to see the actual AST structure
2. Check if metavariables are being detected correctly
3. Verify the node kind matches what you expect
4. Ensure relational rules are searching in the right direction

Escaping in Inline Rules

When using --inline-rules, escape metavariables in shell commands:

• Use \$VAR instead of $VAR (shell interprets $ as variable)
• Or use single quotes: '$VAR' works in most shells

Example:

# 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:

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:

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:

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

Bulk Rewrites and Refactors

When the goal is to change code rather than just find it, use --rewrite (for one-pattern rewrites) or a rule file with fix: (for anything more complex). Prefer this over sed, custom Python scripts, or regex replacements whenever the change depends on code structure rather than literal text.

Workflow

Four discrete steps — do them in order, do not skip:

1. Search to see what matches and how many call sites the pattern will touch:

   ast-grep run --lang rust -p 'foo($A, $B, &[])' tests/
   

2. Preview the rewrite as a colored diff (no --update-all — files are not modified):

   ast-grep run --lang rust -p 'foo($A, $B, &[])' --rewrite 'foo($A, $B)' tests/
   

3. Apply in place with --update-all:

   ast-grep run --lang rust -p 'foo($A, $B, &[])' --rewrite 'foo($A, $B)' --update-all tests/
   

4. Reformat with the language's formatter. ast-grep splices the rewrite text into the existing layout without re-indenting, so multi-line argument lists often end up oddly formatted:

   cargo fmt --all          # Rust
   prettier --write .       # JS/TS
   gofmt -w .               # Go
   

Pre-flight: search for what the pattern WON'T match

A pattern only rewrites the call sites that literally match it. Before changing a callee's signature on the assumption a single rewrite handled everything, run a complementary search for the survivors.

Concrete example from a real refactor: the goal was to drop the env_vars: &[(&str, &str)] parameter from run_covgate. Rewriting run_covgate($W, $C, $A, &[]) → run_covgate($W, $C, $A) cleaned up 27 callers — but several remaining 4-arg call sites still passed non-empty env_vars (e.g., &[("GITHUB_STEP_SUMMARY", path)]). Those did not match the empty-&[] pattern, were not rewritten, and broke compilation when the parameter was removed from the function definition.

The pre-flight that would have caught this: before removing the parameter, also run a "what's left" search with a fully open metavariable in the trailing slot:

# Find all 4-arg calls (any third arg, including non-empty env)
ast-grep run --lang rust -p 'run_covgate($W, $C, $A, $E)' tests/

If anything remains after the targeted rewrite, decide explicitly how to handle each survivor (manual edit, separate _with_env overload, etc.) before changing the signature.

Metavariable substitution in rewrites

In both --rewrite strings and rule-file fix: strings:

• $X (single uppercase identifier) substitutes the matched node verbatim
• $$$X substitutes a variadic match (zero or more nodes)
• Everything else in the pattern is a literal — only metavariables are substituted

Because matching is structural, the same pattern works whether the original call is on one line or spread across many — the AST match is identical. ast-grep does not re-indent the substitution, which is why the reformat step matters.

When to escalate to a rule file with fix:

-p + --rewrite on the command line is enough when the rewrite is unconditional and expressible as a single pattern → replacement. Reach for a YAML rule file with a fix: field when:

• The rewrite is conditional on context (only inside tests/, only when a metavariable matches a regex, only when wrapped in a specific construct)
• You need composite logic — all, any, not, inside, has
• You want the refactor to be a reviewable, replayable artifact committed alongside the diff

Example rule file (drop-empty-env.yml):

id: drop-empty-env-from-run-covgate
language: rust
rule:
  pattern: run_covgate($W, $C, $A, &[])
fix: run_covgate($W, $C, $A)

Apply with scan (not run):

# Preview
ast-grep scan --rule drop-empty-env.yml tests/

# Apply
ast-grep scan --rule drop-empty-env.yml --update-all tests/

For conditional rewrites, add constraints: to bind metavariables to sub-patterns or regexes, and use relational rules (inside, has) under rule:. See references/rule_reference.md for the full YAML grammar.

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.