ast-grep Rule Crafter
ast-grep uses tree-sitter to parse code into AST, enabling precise pattern matching. Rules are defined in YAML for linting, searching, and rewriting code.
Quick Start
id: no-console-log
language: JavaScript
rule:
pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)
message: Replace console.log with logger
Project Configuration
Project-level scanning requires an sgconfig.yml configuration file:
# sgconfig.yml (project root)
ruleDirs:
- rules # Rule directory, recursively loads all .yml files
Typical project structure:
my-project/
├── sgconfig.yml
├── rules/
│ ├── no-console.yml
│ └── custom/
│ └── team-rules.yml
└── src/
Running project scan:
ast-grep scan # Automatically finds sgconfig.yml
ast-grep scan --config path/to/sgconfig.yml # Specify config
Note:
ast-grep scancommand requiressgconfig.yml, whileast-grep run -pcan be used standalone.
Rule Workflow
Lint Rule (Common)
Check only without fixing, used for CI/editor hints:
# rules/no-console-log.yml
id: no-console-log
language: JavaScript
severity: warning
message: Avoid console.log in production code
rule:
pattern: console.log($$$ARGS)
Verify:
ast-grep scan -r rules/no-console-log.yml src/
Rewrite Rule (Optional)
Add fix when auto-fix is needed:
id: no-console-log
language: JavaScript
severity: warning
message: Replace console.log with logger
rule:
pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)
Apply fix:
ast-grep scan -r rules/no-console-log.yml --update-all src/
Development Workflow
- [ ] 1. Explore pattern with CLI: ast-grep -p 'pattern' src/
- [ ] 2. Create rule file (.yml)
- [ ] 3. Verify: ast-grep scan -r rule.yml src/
- [ ] 4. If false positives → add constraints → re-verify
Debug AST structure:
ast-grep -p 'console.log($ARG)' --debug-query ast
Essential Syntax
| Element | Syntax | Example |
|---|---|---|
| Single node | $VAR | console.log($MSG) |
| Multiple nodes | $$$ARGS | fn($$$ARGS) |
| Same content | Use same name | $A == $A |
| Non-capturing | $_VAR | $_FN($_FN) |
Core Rules Quick Reference
| Type | Purpose | Example |
|---|---|---|
pattern | Match code structure | pattern: if ($COND) {} |
kind | Match AST node type | kind: function_declaration |
all | Match ALL conditions | all: [pattern: X, kind: Y] |
any | Match ANY condition | any: [pattern: var $A, pattern: let $A] |
not | Exclude matches | not: {pattern: safe_call()} |
has | Must have child | has: {kind: return_statement} |
inside | Must be in ancestor | inside: {kind: class_body} |
Detailed References
Complete syntax guide: See rule-syntax.md
- Atomic rules (pattern, kind, regex, nthChild, range)
- Composite rules (all, any, not, matches)
- Relational rules (has, inside, follows, precedes)
- Transform and fixConfig
Language-specific patterns: See common-patterns.md
- JavaScript/TypeScript examples
- Python examples
- Go and Rust examples
Supported Languages
Bash, C, Cpp, CSharp, Css, Elixir, Go, Haskell, Hcl, Html, Java, JavaScript, Json, Kotlin, Lua, Nix, Php, Python, Ruby, Rust, Scala, Solidity, Swift, Tsx, TypeScript, Yaml