ast-grep Structural Code Search & Refactoring
Structural code search and refactoring using ast-grep — matches code by its AST (abstract syntax tree) rather than text patterns.
When to Use This Skill
| Use this skill when... |
Use something else instead when... |
| The pattern depends on AST structure (function shape, call form, argument count) |
Searching plain text or regex matches → tools-plugin:rg-code-search |
| Refactoring API call sites across many files while preserving captured variables |
Running a one-shot anti-pattern scan with a report → code-antipatterns |
| Hand-written structural search/replace for an ad-hoc migration |
Functional refactors of a known file/directory → code-refactor |
| Building a new ast-grep rule for a codebase-specific smell |
Looking up agentic flags for an existing linter → code-lint |
When to Use ast-grep vs Grep/ripgrep
| Use ast-grep when... |
Use grep/rg when... |
| Pattern depends on code structure |
Simple text or regex match |
| Need to match any number of arguments |
Searching logs, docs, config |
| Refactoring across many files |
One-off literal string search |
| Finding anti-patterns (empty catch, etc.) |
Language doesn't matter |
| Replacing while preserving variables |
Quick filename/line check |
Decision rule: If your search pattern contains wildcards for "any expression," "any arguments," or "any function name," use ast-grep.
Pattern Syntax
| Pattern |
Matches |
Example |
$VAR |
Single AST node |
console.log($MSG) |
$$$ARGS |
Zero or more nodes |
func($$$ARGS) |
$_ |
Single node (no capture) |
$_ == $_ |
$A == $A |
Same node repeated |
Finds x == x (not x == y) |
Essential Commands
Search for Patterns
# Find structural patterns
ast-grep -p 'console.log($$$)' --lang js
ast-grep -p 'def $FUNC($$$): $$$' --lang py
ast-grep -p 'fn $NAME($$$) -> $RET { $$$ }' --lang rs
# Search in specific directory
ast-grep -p 'import $PKG' --lang js src/
# JSON output for parsing
ast-grep -p 'pattern' --lang js --json=compact
Search and Replace
# Preview changes (default - shows matches)
ast-grep -p 'var $V = $X' -r 'const $V = $X' --lang js
# Apply changes to all files
ast-grep -p 'var $V = $X' -r 'const $V = $X' --lang js -U
# Interactive review
ast-grep -p 'oldAPI($$$ARGS)' -r 'newAPI($$$ARGS)' --lang py -i
# Convert function syntax
ast-grep -p 'function($$$ARGS) { return $EXPR }' \
-r '($$$ARGS) => $EXPR' --lang js -U
# Update import paths
ast-grep -p "import $NAME from '@old/$PATH'" \
-r "import $NAME from '@new/$PATH'" --lang ts -U
Language Codes
| Code |
Language |
Code |
Language |
js |
JavaScript |
py |
Python |
ts |
TypeScript |
rs |
Rust |
jsx |
JSX |
go |
Go |
tsx |
TSX |
java |
Java |
cpp |
C++ |
rb |
Ruby |
c |
C |
php |
PHP |
Common Patterns by Language
JavaScript/TypeScript
# Find React hooks
ast-grep -p 'const [$STATE, $SETTER] = useState($INIT)' --lang jsx
# Find async functions
ast-grep -p 'async function $NAME($$$) { $$$ }' --lang js
# Find type assertions
ast-grep -p '$EXPR as $TYPE' --lang ts
# Find empty catch blocks
ast-grep -p 'try { $$$ } catch ($E) { }' --lang js
# Find eval usage (security)
ast-grep -p 'eval($$$)' --lang js
# Find innerHTML (XSS risk)
ast-grep -p '$ELEM.innerHTML = $$$' --lang js
# Find specific imports
ast-grep -p "import { $$$IMPORTS } from '$PKG'" --lang js
Python
# Find class definitions
ast-grep -p 'class $NAME($$$BASES): $$$' --lang py
# Find decorated functions
ast-grep -p '@$DECORATOR\ndef $FUNC($$$): $$$' --lang py
# Find dangerous shell calls
ast-grep -p 'os.system($$$)' --lang py
# Find SQL concatenation (injection risk)
ast-grep -p '"SELECT * FROM " + $VAR' --lang py
Rust
# Find unsafe blocks
ast-grep -p 'unsafe { $$$ }' --lang rs
# Find impl blocks
ast-grep -p 'impl $TRAIT for $TYPE { $$$ }' --lang rs
# Find public functions
ast-grep -p 'pub fn $NAME($$$) { $$$ }' --lang rs
Go
# Find goroutines
ast-grep -p 'go $FUNC($$$)' --lang go
# Find defer statements
ast-grep -p 'defer $FUNC($$$)' --lang go
# Find error handling
ast-grep -p 'if err != nil { $$$ }' --lang go
Common Refactoring Recipes
# Replace deprecated API calls
ast-grep -p 'oldAPI.$METHOD($$$)' -r 'newAPI.$METHOD($$$)' --lang js -U
# Rename a function across files
ast-grep -p 'oldName($$$ARGS)' -r 'newName($$$ARGS)' --lang py -U
# Remove console.log statements
ast-grep -p 'console.log($$$)' -r '' --lang js -U
# Convert require to import
ast-grep -p 'const $NAME = require($PKG)' \
-r 'import $NAME from $PKG' --lang js -i
# Add error handling wrapper
ast-grep -p 'await $EXPR' \
-r 'await $EXPR.catch(handleError)' --lang ts -i
Command-Line Flags
| Flag |
Purpose |
-p, --pattern |
Search pattern |
-r, --rewrite |
Replacement pattern |
-l, --lang |
Target language |
-i, --interactive |
Review changes one by one |
-U, --update-all |
Apply all changes |
--json |
JSON output (compact, stream, pretty) |
-A N |
Lines after match |
-B N |
Lines before match |
-C N |
Lines around match |
--debug-query |
Debug pattern parsing |
YAML Rules (Scan Mode)
For reusable rules, use ast-grep scan with YAML configuration:
# Scan with config
ast-grep scan -c sgconfig.yml
# Run specific rule
ast-grep scan -r rule-name
# Initialize a rules project
ast-grep new project my-linter
ast-grep new rule no-console-log
Minimal rule file:
id: no-empty-catch
language: JavaScript
severity: warning
message: Empty catch block hides errors
rule:
pattern: try { $$$ } catch ($E) { }
fix: |
try { $$$ } catch ($E) { console.error($E) }
For comprehensive YAML rule syntax, constraints, transformations, and testing, see REFERENCE.md.
Agentic Optimizations
| Context |
Command |
| Quick structural search |
ast-grep -p 'pattern' --lang js --json=compact |
| Count matches |
ast-grep -p 'pattern' --lang js --json=stream | wc -l |
| File list only |
ast-grep -p 'pattern' --json=stream | jq -r '.file' | sort -u |
| Batch refactor |
ast-grep -p 'old' -r 'new' --lang js -U |
| Scan with rules |
ast-grep scan --json |
| Debug pattern |
ast-grep -p 'pattern' --debug-query --lang js |
Quick Reference
# 1. Search for pattern
ast-grep -p 'pattern' --lang js src/
# 2. Preview rewrite
ast-grep -p 'old' -r 'new' --lang js
# 3. Apply rewrite
ast-grep -p 'old' -r 'new' --lang js -U
# 4. Scan with rules
ast-grep scan -c sgconfig.yml
# 5. Debug pattern
ast-grep -p 'pattern' --debug-query --lang js
laurigates