tool-ast-grep-rules

ast-grep 规则编写器

ast-grep 使用 tree-sitter 将代码解析为 AST，从而实现精准的模式匹配。规则以 YAML 定义，用于检查、搜索和重写代码。

快速开始

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

项目配置

项目级扫描需要一个 sgconfig.yml 配置文件：

# sgconfig.yml (project root)
ruleDirs:
  - rules          # Rule directory, recursively loads all .yml files

典型的项目结构：

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

运行项目扫描：

ast-grep scan              # Automatically finds sgconfig.yml
ast-grep scan --config path/to/sgconfig.yml  # Specify config

注意：ast-grep scan 命令需要 sgconfig.yml，而 ast-grep run -p 可以独立使用。

规则工作流

检查规则（常用）

只检查，不修复，用于 CI／编辑器提示：

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

验证：

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

重写规则（可选）

需要自动修复时，添加 fix：

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

应用修复：

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

开发工作流

- [ ] 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

调试 AST 结构：

ast-grep -p 'console.log($ARG)' --debug-query ast

基本语法

元素	语法	示例
单个节点	$VAR	console.log($MSG)
多个节点	$$$ARGS	fn($$$ARGS)
相同内容	使用相同名称	$A == $A
不捕获	$_VAR	$_FN($_FN)

核心规则速查

类型	用途	示例
pattern	匹配代码结构	pattern: if ($COND) {}
kind	匹配 AST 节点类型	kind: function_declaration
all	匹配所有条件	all: [pattern: X, kind: Y]
any	匹配任一条件	any: [pattern: var $A, pattern: let $A]
not	排除匹配项	not: {pattern: safe_call()}
has	必须包含子节点	has: {kind: return_statement}
inside	必须位于祖先节点内	inside: {kind: class_body}

详细参考

完整语法指南：参见 rule-syntax.md

• 原子规则（pattern、kind、regex、nthChild、range）
• 组合规则（all、any、not、matches）
• 关系规则（has、inside、follows、precedes）
• Transform 和 fixConfig

特定语言的模式：参见 common-patterns.md

• JavaScript／TypeScript 示例
• Python 示例
• Go 和 Rust 示例

支持的语言

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