ast-grep by aiskillstore

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

# AST-Grep

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

## 执行环境

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

## 安装

```bash
# macOS
brew install ast-grep

# Linux
cargo install ast-grep

# 验证安装
ast-grep --version
```

## 核心功能

### 1. 语法感知搜索

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

```bash
# 搜索特定模式
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 更精确。

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

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

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

### 3. 代码重写

批量转换代码模式。

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

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

### 4. 规则测试

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

```bash
# 测试规则
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` - 模式匹配

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

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

#### `kind` - 节点类型匹配

```yaml
kind: call_expression
```

#### `regex` - 正则表达式匹配

```yaml
regex: ^[a-z]+$
```

#### `nthChild` - 位置匹配

```yaml
# 数字
nthChild: 1

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

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

#### `range` - 范围匹配

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

### 2. 关系规则

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

#### `inside` - 在父节点内

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

#### `has` - 包含子节点

```yaml
has:
  pattern: await $EXPR
  stopBy: end
```

#### `precedes` - 在节点之前

```yaml
precedes:
  pattern: return $VAL
```

#### `follows` - 在节点之后

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

#### `stopBy` - 搜索终止控制

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

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

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

#### `field` - 字段匹配

```yaml
has:
  field: operator
  pattern: $$OP
```

### 3. 组合规则

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

#### `all` - 逻辑与（AND）

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

#### `any` - 逻辑或（OR）

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

#### `not` - 逻辑非（NOT）

```yaml
not:
  pattern: console.log($ARG)
```

#### `matches` - 规则重用

```yaml
matches: my-utility-rule-id
```

## 元变量

### `$VAR` - 单个命名节点捕获

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

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

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

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

### `$$$VAR` - 多节点捕获

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

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

### `_VAR` - 非捕获元变量

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

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

## 编写规则的最佳实践

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

```yaml
has:
  pattern: await $EXPR
  stopBy: end
```

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

```yaml
pattern: console.log($ARG)
```

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

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

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

```yaml
# 先确认节点类型
kind: call_expression

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

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

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

## YAML 规则配置

### 简单规则

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

### 复杂规则

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

### 带修复的规则

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

### 使用关系规则

```yaml
# 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. 查找特定代码模式

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

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

### 2. 重构代码

```bash
# 替换 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. 代码审计

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

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

### 4. API 迁移

```bash
# 迁移旧 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 进行语法感知搜索：

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

### Phase 4: 编码实施

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

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

### Phase 5: 审计

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

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

## 注意事项

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