Installation
For macOS, use brew install ast-grep.
For cross-platform via npm, use npm install -g @ast-grep/cli.
For Rust via Cargo, use cargo install ast-grep.
Basic Pattern Matching
#### Simple Pattern Search
To find all console.log calls, run sg with pattern console.log($MSG) and lang javascript.
To find all Python function definitions, run sg with pattern def $FUNC($$$ARGS): $$$BODY and lang python.
To find React useState hooks, run sg with pattern useState($INIT) and lang tsx.
#### Explore/Search Performance Optimization
AST-Grep provides significant performance benefits for codebase exploration compared to text-based search:
Why AST-Grep is Faster for Exploration
- Structural understanding eliminates false positives (50-80% reduction in irrelevant results)
- Syntax-aware matching reduces full file scans
- Single pass through AST vs multiple regex passes
Common Exploration Patterns
Find all function calls matching a pattern:
```bash
sg -p 'authenticate($$$)' --lang python -r src/
```
Find all classes inheriting from a base class:
```bash
sg -p 'class $A extends BaseService' --lang python -r src/
```
Find specific import patterns:
```bash
sg -p 'import fastapi' --lang python -r src/
```
Find React hooks usage:
```bash
sg -p 'useState($$)' --lang tsx -r src/
```
Find async function declarations:
```bash
sg -p 'async def $NAME($$$ARGS):' --lang python -r src/
```
Performance Comparison
grep -r "class.*Service" src/ - scans all files textually (~10s for large codebase)sg -p 'class $X extends Service' --lang python -r src/ - structural match (~2s)
Integration with Explore Agent
When using the Explore agent, AST-Grep is automatically prioritized for:
- Class hierarchy analysis
- Function signature matching
- Import dependency mapping
- API usage pattern detection
#### Meta-variables
Meta-variables capture matching AST nodes in patterns.
Single node capture uses $NAME syntax. For example, pattern const $NAME = require($PATH) captures the variable name and path.
Variadic capture uses $$$ARGS syntax. For example, pattern function $NAME($$$ARGS) captures function name and all arguments.
Anonymous single capture uses $$_ syntax when you need to match but not reference the value.
Code Transformation
#### Simple Rewrite
To rename a function, run sg with pattern oldFunc($ARGS), rewrite newFunc($ARGS), and lang python.
To update an API call, run sg with pattern axios.get($URL), rewrite fetch($URL), and lang typescript.
#### Complex Transformation with YAML Rules
Create a YAML rule file with the following structure. Set the id field to a unique rule identifier such as convert-var-to-const. Set language to the target language such as javascript. Under the rule section, specify the pattern to match such as var $NAME = $VALUE. Set the fix field to the replacement pattern such as const $NAME = $VALUE. Add a message describing the issue and set severity to warning or error.
Run sg scan with the rule option pointing to your rule file and the source directory.
Rule-Based Scanning
#### Configuration File
Create an sgconfig.yml file with the following sections. The ruleDirs section lists directories containing rule files such as ./rules/security and ./rules/quality. The testConfigs section specifies test file patterns. The languageGlobs section maps languages to file patterns, mapping python to .py files, typescript to .ts and .tsx files, and javascript to .js and .jsx files.
#### Security Rule Example
Create a security rule file for SQL injection detection. Set the id to sql-injection-risk. Set language to python and severity to error. Write a descriptive message about the vulnerability. Under the rule section, use the any operator to match multiple patterns including cursor.execute with percent formatting, cursor.execute with format method, and cursor.execute with f-string interpolation. Set the fix to show the parameterized query alternative.
Relational Rules
#### Inside Rule for Scoped Search
Create a rule that searches for console.log calls only inside function declarations. Set the pattern to console.log($$$ARGS) and add an inside constraint with pattern function $NAME($$$PARAMS).
#### Has Rule for Contains Check
Create a rule to find async functions without await. Set the pattern to async function $NAME($$$PARAMS) with a not constraint containing a has rule with pattern await $EXPR. Add message indicating async function without await.
#### Follows and Precedes Rules
Create a rule to detect missing error handling. Set the pattern to match error assignment $ERR := $CALL and add a not constraint with follows rule checking for if $ERR != nil error handling block.
Composite Rules
Create complex rules using the all operator to combine multiple conditions. For example, combine pattern useState($INIT) with inside constraint for function component and not precedes constraint for useEffect call.
---
|