ast-grep

name	ast-grep
description	语法感知的代码搜索、linting 和重写工具。支持基于 AST 的结构化代码搜索和批量代码转换。

AST-Grep

AST-Grep (ast-grep/sg) 是一个快速且用户友好的工具，用于代码搜索、linting 和大规模代码重写。

执行环境

路径类型	说明
使用方式	命令行工具，需要安装 ast-grep
调用场景	语法感知的代码搜索、结构化代码分析、批量代码转换
工作目录	项目根目录

安装

# macOS
brew install ast-grep

# Linux
cargo install ast-grep

# 验证安装
ast-grep --version

核心功能

1. 语法感知搜索

使用 AST（抽象语法树）进行代码搜索，而非简单的文本匹配。

# 搜索特定模式
ast-grep --lang python -p "def $FUNC($$$ARGS):"

# 搜索函数调用
ast-grep --lang ts -p "console.log($$$MSG)"

# 搜索条件语句
ast-grep --lang ts -p "if ($$COND) { $$$BODY }"

2. 代码 Linting

基于 AST 的代码检查，比传统 linter 更精确。

# 扫描项目
ast-grep scan -r sgconfig.yml

# 扫描特定目录
ast-grep scan src/

# 扫描特定文件
ast-grep scan src/main.ts

3. 代码重写

批量转换代码模式。

# 简单替换
ast-grep run -p "oldFunction($$$ARGS)" -r "newFunction($$ARGS)" --lang ts

# 复杂转换（使用 YAML 规则）
ast-grep run -r rule.yml

4. 规则测试

测试 ast-grep 规则是否正确。

# 测试规则
ast-grep test -r rule.yml

# 测试特定模式
ast-grep test -p "pattern" --lang ts

规则开发流程

通用流程

1. 理解查询：明确用户需求，必要时询问更多细节
2. 编写示例：编写匹配查询的简单代码示例
3. 编写规则：编写匹配示例的 ast-grep 规则
4. 测试规则：使用 test_match_code_rule 验证规则
   • 如果不匹配，移除部分子规则并调试
   • 如果使用 inside 或 has，确保使用 stopBy: end
5. 搜索代码：使用规则搜索代码库

规则开发步骤

1. 分解查询：将用户查询分解为更小的部分
2. 识别子规则：识别可用于匹配代码的子规则
3. 组合规则：使用关系规则或组合规则组合子规则
4. 调试规则：如果规则不匹配示例代码，移除部分子规则并调试不匹配的部分
5. 使用工具：使用 ast-grep mcp 工具转储 AST 或转储模式查询
6. 测试规则：使用 ast-grep mcp 工具针对示例代码片段测试规则

规则类型

1. 原子规则

匹配单个 AST 节点，基于内在属性。

pattern - 模式匹配

# 字符串模式
pattern: console.log($ARG)

# 对象模式（更精细的控制）
pattern:
  selector: field_definition
  context: class { $F }
  strictness: relaxed

kind - 节点类型匹配

kind: call_expression

regex - 正则表达式匹配

regex: ^[a-z]+$

nthChild - 位置匹配

# 数字
nthChild: 1

# An+B 公式
nthChild: 2n+1

# 对象形式
nthChild:
  position: 1
  reverse: true
  ofRule:
    kind: function_declaration

range - 范围匹配

range:
  start:
    line: 0
    column: 0
  end:
    line: 0
    column: 10

2. 关系规则

基于目标节点与其他节点的关系过滤目标。

inside - 在父节点内

inside:
  pattern: class $C { $$$ }
  stopBy: end

has - 包含子节点

has:
  pattern: await $EXPR
  stopBy: end

precedes - 在节点之前

precedes:
  pattern: return $VAL

follows - 在节点之后

follows:
  pattern: import $M from '$P'

stopBy - 搜索终止控制

# neighbor（默认）：在直接周围节点不匹配时停止
stopBy: neighbor

# end：搜索到方向末尾（inside 为根，has 为叶子）
stopBy: end

# 规则对象：在周围节点匹配提供的规则时停止（包含）
stopBy:
  pattern: class $END

field - 字段匹配

has:
  field: operator
  pattern: $$OP

3. 组合规则

使用逻辑操作组合其他规则。

all - 逻辑与（AND）

all:
  - kind: call_expression
  - pattern: console.log($ARG)

any - 逻辑或（OR）

any:
  - pattern: console.log($ARG)
  - pattern: console.warn($ARG)
  - pattern: console.error($ARG)

not - 逻辑非（NOT）

not:
  pattern: console.log($ARG)

matches - 规则重用

matches: my-utility-rule-id

元变量

$VAR - 单个命名节点捕获

# 有效
pattern: console.log($GREETING)

# 匹配
console.log('Hello World')

$$VAR - 单个未命名节点捕获

# 匹配操作符
rule:
  kind: binary_expression
  has:
    field: operator
    pattern: $$OP

$$$VAR - 多节点捕获

# 匹配零个或多个节点（非贪婪）
pattern: console.log($$$)

# 匹配可变参数
pattern: function $FUNC($$$ARGS) { $$$ }

_VAR - 非捕获元变量

# 不捕获，可以匹配不同内容
pattern: $_FUNC($_FUNC)

# 匹配
test(a)
testFunc(1 + 1)

编写规则的最佳实践

1. 始终使用 stopBy: end：对于关系规则，确保搜索到方向末尾

has:
  pattern: await $EXPR
  stopBy: end

2. 简单结构使用 pattern：代码结构简单时直接使用模式

pattern: console.log($ARG)

3. 复杂结构使用 rule：代码结构复杂时使用规则分解

rule:
  kind: function_declaration
  has:
    pattern: await $EXPR

4. 使用 kind 调试：如果 pattern 不工作，先用 kind 匹配节点类型

# 先确认节点类型
kind: call_expression

# 再使用 has 或 inside
has:
  pattern: console.log($ARG)

5. 关系规则无匹配时添加 stopBy：确保搜索到末尾

inside:
  pattern: class $C { $$$ }
  stopBy: end

YAML 规则配置

简单规则

# rule.yml
id: no-console-log
language: ts
rule:
  pattern: console.log($$$MSG)

复杂规则

# complex-rule.yml
id: prefer-const
language: ts
rule:
  all:
    - pattern: let $VAR = $INIT
    - not:
        pattern: $VAR = $EXPR

带修复的规则

# fix-rule.yml
id: no-var
language: ts
rule:
  pattern: var $VAR = $INIT
fix: const $VAR = $INIT

使用关系规则

# async-without-await.yml
id: async-without-await
language: ts
rule:
  all:
    - pattern: async function $FUNC($$$ARGS) { $$$BODY }
    - not:
        has:
          pattern: await
          stopBy: end

常用场景

1. 查找特定代码模式

# 查找所有 console.log
ast-grep -p "console.log($$$MSG)" --lang ts

# 查找所有未使用的变量
ast-grep -p "let $VAR = $INIT" --lang ts | grep -v "$VAR ="

2. 重构代码

# 替换 var 为 const
ast-grep run -p "var $VAR = $INIT" -r "const $VAR = $INIT" --lang ts

# 重命名函数
ast-grep run -p "oldFunc($$$ARGS)" -r "newFunc($$ARGS)" --lang ts

3. 代码审计

# 查找潜在的安全问题
ast-grep -p "eval($$$EXPR)" --lang js

# 查找 SQL 注入风险
ast-grep -p "query('$$SQL')" --lang py

4. API 迁移

# 迁移旧 API 到新 API
ast-grep run -p "oldApi($$$ARGS)" -r "newApi($$ARGS)" --lang ts

# 批量更新导入
ast-grep run -p "from 'old-lib' import $$IMPORT" -r "from 'new-lib' import $$IMPORT" --lang ts

与其他工具对比

特性	ast-grep	grep	ripgrep
语法感知	是	否	否
代码结构理解	是	否	否
跨语言支持	是	否	否
性能	快	快	最快
重写功能	是	否	否

参考资源

• 官方文档: https://ast-grep.github.io/
• GitHub: https://github.com/ast-grep/ast-grep
• 规则示例: https://ast-grep.github.io/catalog/
• Playground: https://ast-grep.github.io/playground/
• MCP 服务器: https://github.com/ast-grep/ast-grep-mcp

集成 Pi 工作流

Phase 1: 上下文检索

当需要理解代码结构时，使用 ast-grep 进行语法感知搜索：

# 查找特定模式
ast-grep -p "pattern" --lang <language>

Phase 4: 编码实施

使用 ast-grep 进行批量代码转换：

# 应用重构规则
ast-grep run -r rule.yml

Phase 5: 审计

使用 ast-grep 验证代码质量：

# 扫描潜在问题
ast-grep scan -r sgconfig.yml

注意事项

• ast-grep 需要安装才能使用
• 模式语法需要熟悉 AST 结构
• 复杂规则建议先测试再应用
• 大规模重构前建议备份代码
• 使用 stopBy: end 确保关系规则搜索完整
• 元变量必须符合语法要求（$VAR, $$VAR, $$$VAR）