tool-ast-grep-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ast-grep Rule Crafter

ast-grep 规则制作工具

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.

ast-grep 借助 tree-sitter 将代码解析为 AST，实现精准的模式匹配。规则通过 YAML 定义，可用于代码检查、搜索与重写。

Quick Start

快速开始

yaml

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

yaml

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:

yaml

undefined

项目级扫描需要

sgconfig.yml

配置文件：

yaml

undefined

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:

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

Note:
ast-grep scan
command requires
sgconfig.yml
, while
ast-grep run -p
can be used standalone.

ruleDirs:

rules # Rule directory, recursively loads all .yml files


典型项目结构：

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


运行项目扫描：

```bash
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
可独立使用。

Rule Workflow

规则工作流

Lint Rule (Common)

检查规则（常用）

Check only without fixing, used for CI/editor hints:

yaml

undefined

仅检查不修复，用于CI/编辑器提示：

yaml

undefined

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:

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

id: no-console-log language: JavaScript severity: warning message: Avoid console.log in production code rule: pattern: console.log($$$ARGS)


验证：

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

Rewrite Rule (Optional)

重写规则（可选）

Add

fix

when auto-fix is needed:

yaml

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:

bash

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

需要自动修复时添加

fix

：

yaml

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

应用修复：

bash

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:

bash

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

- [ ] 1. 用CLI探索模式：ast-grep -p 'pattern' src/
- [ ] 2. 创建规则文件(.yml)
- [ ] 3. 验证：ast-grep scan -r rule.yml src/
- [ ] 4. 若出现误报 → 添加约束 → 重新验证

调试AST结构：

bash

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

元素	语法	示例
单个节点	`$VAR`	`console.log($MSG)`
多个节点	`$$$ARGS`	`fn($$$ARGS)`
相同内容	使用相同名称	`$A == $A`
非捕获	`$_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}`

类型	用途	示例
`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}`

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

完整语法指南：查看 rule-syntax.md

原子规则（pattern、kind、regex、nthChild、range）
复合规则（all、any、not、matches）
关系规则（has、inside、follows、precedes）
转换与fixConfig

语言特定模式：查看 common-patterns.md

JavaScript/TypeScript 示例
Python 示例
Go 和 Rust 示例

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