ast-grep-rule-crafter

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 sgconfig.yml configuration file:

# sgconfig.yml (项目根目录)
ruleDirs:
  - rules          # 规则目录，递归加载所有 .yml 文件

Typical project structure:

my-project/
├── sgconfig.yml
├── rules/
│   ├── no-console.yml
│   └── custom/
│       └── team-rules.yml
└── src/

Run project scan:

ast-grep scan              # 自动查找 sgconfig.yml
ast-grep scan --config path/to/sgconfig.yml  # 指定配置

Note: ast-grep scan The command must include sgconfig.yml, while ast-grep run -p can be used alone.

Rule Workflow

Lint Rule (common)

Check only, no fix; 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 when automatic fixes are needed fix：

id: no-console-log
language: JavaScript
severity: warning
message: Replace console.log with logger
rule:
  pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)

Apply fixes:

ast-grep scan -r rules/no-console-log.yml --update-all src/

Development workflow

- [ ] 1. 用 CLI 探索 pattern: ast-grep -p 'pattern' src/
- [ ] 2. 创建规则文件 (.yml)
- [ ] 3. 验证: ast-grep scan -r rule.yml src/
- [ ] 4. 如有误报 → 添加 constraints → 重新验证

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 references/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 references/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