ast-grep：结构化搜索与重构利器

1 引言：代码搜索与重构的范式革命

在软件工程的浩瀚历史中，代码维护始终是一项充满挑战的核心任务。对于前端开发者而言，随着项目规模的指数级增长和技术栈的快速迭代（从 jQuery 到 AngularJS，再到 Vue.js 和 React 的百家争鸣），代码库的复杂性已达到前所未有的高度。在这样的背景下，"如何高效地理解、搜索并批量修改代码"成为了决定团队效能的关键因素。

长期以来，开发者手中的工具箱里主要躺着两类工具：一类是基于文本的搜索工具，如 Unix 哲学的代表 grep、sed 以及现代的高性能替代品 ripgrep；另一类是基于抽象语法树（AST）的重量级分析工具，如 ESLint、Prettier 以及 Facebook 推出的 jscodeshift。然而，这两类工具之间存在着巨大的鸿沟。

基于正则表达式的文本工具虽然速度极快且通用性强，但它们天生是"语法盲"。它们无法理解代码的上下文结构，无法区分变量名 user 和字符串 "user"，更无法处理跨行的函数定义或嵌套的括号结构。在面对复杂的重构任务时，正则往往显得力不从心，甚至危险。

另一端，基于 AST 的工具虽然精准，但门槛极高。编写一个 ESLint 插件或 jscodeshift 脚本通常需要深入了解编译原理，熟悉特定语言的 AST 规范（如 ESTree），并编写大量的样板代码。这种高昂的学习成本使得大多数团队只能依赖社区提供的规则，而难以针对自身的业务逻辑定制自动化重构工具。

正是在这种背景下，ast-grep（Abstract Syntax Tree grep）应运而生。它填补了文本搜索与专业 AST 分析之间的空白，通过引入"结构化搜索模式（Pattern）"，允许开发者使用类似原生代码的语法来描述 AST 结构。ast-grep 的出现不仅仅是一个新工具的诞生，它标志着代码搜索与重构工具的一次范式转移------从"基于字符的匹配"走向了"基于结构的理解"。

本报告旨在为前端开发者，特别是 Vue.js 生态系统的实践者，提供一份详尽的 ast-grep 权威指南。我们将从底层的 AST/CST 理论出发，深入剖析 ast-grep 的核心机制，详尽解读其配置系统与规则编写技巧，并特别针对 Vue 单文件组件（SFC）的复杂场景，展示如何利用 ast-grep 实现从 Options API 到 Composition API 的自动化架构迁移。这不仅是一份工具手册，更是一次关于代码结构认知与工程化思维的深度探索。

2 理论基石：从 AST 到 CST 的演进

在深入 ast-grep 的实战操作之前，理解其背后的理论基础至关重要。这不仅有助于我们编写更高效的规则，更能帮助我们在遇到匹配问题时透过现象看本质，快速定位根源。

2.1 抽象语法树（AST）与具体语法树（CST）的辩证关系

虽然工具名称中包含 "AST"，但在 ast-grep 的内部实现中，它实际上主要依赖于具体语法树（CST, Concrete Syntax Tree）。这两个概念的区别对于代码重构工具而言至关重要。

抽象语法树 (AST) 是源代码语法结构的一种抽象表示。在这种树状结构中，每一个节点都代表源代码中的一种结构。之所以称为"抽象"，是因为它丢弃了许多对于编译器后端生成机器码不重要的细节。例如，括号、分号、多余的空格和换行符，甚至注释，通常都不会出现在标准的 AST 中。对于编译器而言，a = b + c 和 a=b+c; 表达的是完全相同的语义，因此它们的 AST 结构往往是一致的。

然而，对于一个致力于"代码重构（Refactoring）"和"代码格式化（Linting）"的工具来说，这些被 AST 丢弃的"琐碎（Trivial）"细节却是至关重要的。当我们希望将 var x = 1; 重写为 const x = 1; 时，我们不仅希望改变关键字，还希望保留原有的缩进、空格风格以及行尾的分号，甚至包括这行代码上方的注释。如果使用纯粹的 AST，重构后的代码往往会丢失格式信息，变成一行紧凑但难以阅读的字符串，必须再次经过 Prettier 等工具的格式化。

具体语法树 (CST) 则忠实地记录了源代码的所有字符。在 CST 中，空格、注释、括号等都拥有自己的节点。这使得 CST 能够支持"无损重写"------即只修改目标节点，而完全保留周围代码的原始格式。

ast-grep 的精妙之处在于它在 API 层面巧妙地融合了二者。虽然底层解析引擎生成的是 CST，但 ast-grep 的匹配算法允许用户像操作 AST 一样忽略琐碎细节。例如，当你编写模式 foo($A) 时，ast-grep 会自动处理目标代码中 foo 和 ( 之间可能存在的空格，或者参数列表中的换行符。它默认关注"具名节点（Named Nodes）"（如函数定义、标识符），而智能地跳过"匿名节点（Unnamed Nodes）"（如标点符号），从而在易用性与精确性之间找到了完美的平衡。

2.2 Tree-sitter：增量解析引擎的革命

ast-grep 的强大能力在很大程度上归功于其集成的解析引擎 ------ Tree-sitter。Tree-sitter 是由 GitHub 开发的一个现代解析生成器工具，它为 ast-grep 提供了以下核心能力，使其在性能和功能上超越了传统的 AST 工具：

特性	描述	对 ast-grep 的意义
通用性 (Polyglot)	支持 C, Rust, Go, Python, JavaScript, TypeScript, HTML, Vue, CSS 等多种语言。	使 ast-grep 成为一个跨语言的通用工具，前端开发者可以用同一套语法处理 JS, TS, CSS 和 HTML。
增量解析 (Incremental)	当源文件被编辑时，仅重新解析修改的部分，而非全量解析。	极大地提升了编辑器（如 VS Code）内插件的响应速度，实现了实时 Linting 和搜索。
鲁棒性 (Robustness)	即使代码存在语法错误，也能生成部分有效的语法树。	允许开发者在代码编写过程中（此时代码往往是不完整的）依然能使用搜索和跳转功能。
高性能 (Performance)	基于 C 编写的核心运行时，极低的内存占用和极快的解析速度。	使得 ast-grep 能够在大规模代码库（数万个文件）中实现秒级的搜索响应。

2.3 结构化模式匹配的核心哲学

ast-grep 最具革命性的创新在于其"模式（Pattern）"的设计哲学。传统的 CSS 选择器（如 .class > #id）或 XPath 虽然强大，但需要学习全新的语法，且与源代码本身差异巨大。

ast-grep 采用了一种"同构"的设计理念：用代码搜索代码。

当你想要搜索一个 console.log 调用时，你不需要构建复杂的 AST 选择器（如 CallExpression[callee.name="console"][callee.property="log"]），你只需要编写模式：console.log($ARGS)。这个模式本身就是一段合法的 JavaScript 代码（加上了特殊的元变量），这极大地降低了认知负荷。

开发者只需将脑海中的目标代码写出来，并将变化的部分用通配符代替，即可完成复杂的查询。这种设计哲学不仅降低了入门门槛，还使得规则的可读性大幅提升。团队成员在阅读 sgconfig.yml 规则文件时，无需在大脑中进行"AST 转换"，直接就能看懂规则意图。

3 工具链环境搭建与配置全解

工欲善其事，必先利其器。在本章中，我们将详细介绍如何在不同平台上搭建 ast-grep 的开发环境，并解析其项目结构。

3.1 命令行工具 (CLI) 的多平台部署

ast-grep 的核心是一个名为 sg（Structural Grep 的缩写）的二进制命令行工具。它是进行大规模代码扫描、批量重构以及 CI/CD 集成的基础。

3.1.1 通过 npm 安装（前端开发者推荐）

对于前端开发者，最便捷的方式是通过 npm 或 pnpm 安装，这样可以将其作为项目的开发依赖进行版本管理。

bash 复制代码

# 全局安装
npm install @ast-grep/cli -g

# 或者作为项目开发依赖安装（推荐）
npm install @ast-grep/cli -D

安装后，可以通过 sg 命令调用。验证安装：

bash 复制代码

sg --version
# 输出示例: 0.26.0

3.1.2 通过 Cargo 安装（Rust 开发者或高性能需求）

如果你追求极致的启动速度，或者机器上没有 Node.js 环境，可以直接从源码编译或安装 Rust 二进制包。

bash 复制代码

cargo install ast-grep

3.1.3 通过 Homebrew 安装（macOS 用户）

bash 复制代码

brew install ast-grep

3.2 VS Code 插件：可视化开发环境

虽然 CLI 功能强大，但在编写和调试规则时，可视化的反馈循环是必不可少的。ast-grep 官方提供了 VS Code 插件，它是目前体验最好的开发伴侣。

安装步骤：

打开 VS Code 扩展市场（Extensions View）
搜索 "ast-grep"
点击安装由 "ast-grep" 发布的官方插件

核心功能深度解析：

结构化搜索面板 ：插件提供了一个专门的搜索面板，允许用户输入 Pattern 并实时查看匹配结果。这比全局文本搜索更精准。例如，搜索 result 不会匹配到字符串 "result"。
实时诊断 (Diagnostics) ：如果项目根目录下存在 sgconfig.yml，插件会自动启动语言服务器（LSP）。任何违反规则的代码都会被波浪线标记，鼠标悬停即可查看错误信息。
快速修复 (Quick Fix) ：对于配置了 fix 字段的规则，插件支持 Cmd+.（macOS）或 Ctrl+.（Windows）一键自动修复代码。
AST 调试器 (Debug Query) ：这是编写规则的神器。通过命令面板运行 ast-grep: Debug Query（或在较新版本中通过 UI 入口），开发者可以将光标置于源代码上，实时查看该代码对应的 Tree-sitter CST 结构。这对于确定特定语法的 kind 名称（如 method_definition 还是 function_declaration）至关重要。

3.3 项目脚手架初始化

要在现有项目中引入 ast-grep 进行规范管理，需要初始化标准的项目结构。

bash 复制代码

sg new

该交互式命令会引导用户创建以下核心文件和目录：

sgconfig.yml：项目的"大脑"，负责定义规则文件的查找路径、语言配置以及测试套件的位置。它是 LSP 启动的标志文件。
rules/ ：存放 YAML 规则文件的目录。通常建议按语言或功能模块（如 security, style, vue-migration）进行子目录划分。
utils/ ：存放可复用规则组件（Utility Rules）的目录。类似于编程中的"公共函数库"，这里的规则可以被其他规则通过 matches 字段引用。

sgconfig.yml 配置全解：

yaml 复制代码

# 规则文件所在的目录列表
ruleDirs:
  - rules

# 实用工具规则所在的目录
utilDirs:
  - utils

# 测试用例配置
testConfigs:
  - testDir: rules/tests # 存放测试快照的目录

# 自定义语言扩展映射（非常重要，尤其对 Vue 开发）
languageGlobs:
  html:
    - "*.vue" # 简单策略：将.vue 视为 HTML 处理
  typescript:
    - "*.ts"
    - "*.tsx"

4 模式语法（Pattern Syntax）深度指南

ast-grep 的模式语法是其精髓所在。掌握模式语法，意味着掌握了与代码结构对话的语言。

4.1 元变量（Meta Variables）：捕捉变化的通配符

元变量是模式中的占位符，用于匹配 AST 中的特定节点。在 ast-grep 中，元变量统一以 $ 符号开头，后跟大写字母（如 $VAR, $A, $MATCH）。

类型	语法	描述	匹配示例	不匹配示例
单节点元变量	`$A`	匹配任意单个 AST 节点。这是最常用的类型。	模式 `console.log($MSG)` 匹配 `console.log("hello")`，`$MSG` 捕获字符串节点 `"hello"`。	`console.log(a, b)`（因为参数列表包含逗号，不是单个节点）。
多节点元变量	`$$$A`	匹配零个或多个连续的 AST 节点。通常用于匹配函数参数列表、数组元素或语句块中的多行代码。	模式 `foo($$$ARGS)` 匹配 `foo()`, `foo(1)`, `foo(1, 2, 3)`。	无。
匿名元变量	`$_`	仅用于匹配占位，不保存捕获内容，也无法在 fix 中引用。	模式 `if ($_ == null)` 匹配任何判空逻辑。	-
包含匿名节点	`$$A`	匹配节点及其周边的"匿名节点"（如分号、逗号）。这是高级用法，用于处理涉及标点符号的精细匹配。	模式 `return $$VAL` 可以匹配包含分号的返回语句。	-

元变量捕获机制 ：元变量的一个强大特性是引用一致性 。如果在同一个模式中多次使用相同的元变量名（如 $A），ast-grep 会强制要求这些位置匹配到的 AST 节点在文本上是完全一致的。

scss 复制代码

模式： $A == $A
匹配： x == x, foo() == foo()
不匹配： x == y, foo() == bar()

这使得检测诸如"自我赋值"（Self-assignment）或"冗余比较"这类逻辑错误变得异常简单。

4.2 严格模式（Strictness）：控制匹配的精度

有时，我们希望模式匹配更加宽松，忽略注释或某些特定的语法变体；有时则需要极其精确。ast-grep 提供了 strictness 选项来控制这一行为。

级别	描述	应用场景
cst	最严格。要求模式与目标代码在 CST 层面完全一致，包括空格、注释和标点。	几乎不使用，除非进行极其严格的格式检查。
smart	默认值。忽略模式中的匿名节点（如分号），但如果目标代码中有额外的重要节点则不匹配。	大多数搜索和重构场景。
ast	仅匹配具名节点。完全忽略所有标点、括号和注释。	当你需要忽略代码风格差异（如有无尾随逗号）时使用。
relaxed	最宽松。允许忽略注释和更多琐碎细节。	快速原型开发或模糊搜索。

4.3 选择器（Selector）与上下文（Context）

在某些情况下，我们只想匹配代码片段的一部分，但这段代码如果不放在特定的上下文中是无效的。例如，在 JavaScript 类中定义类属性 field = 1。如果直接写模式 field = 1，解析器可能会将其误判为变量赋值。

这时可以使用 Pattern Object：

yaml 复制代码

rule:
  pattern:
    context: class A { $F } # 提供上下文：这是一个类体
    selector: field_definition # 指明我们真正想匹配的是其中的 field_definition 节点

这种机制确保了 Tree-sitter 能够正确解析模式的语法含义，避免因片段歧义导致的匹配失败。

5 规则配置（Rule Configuration）百科全书

YAML 规则文件是 ast-grep 自动化能力的载体。一个规则对象由三大类子规则构成：原子规则、关系规则和复合规则。

5.1 原子规则 (Atomic Rules)：匹配的基础

原子规则直接针对当前节点进行检查。

pattern: 字符串模式或模式对象。

yaml 复制代码

pattern: console.log($MSG)

kind: 检查节点的 AST 类型名称。这需要通过 debug-query 查找。

yaml 复制代码

kind: function_declaration # 仅匹配函数声明

regex: 对节点的文本内容进行正则表达式匹配。这是 ast-grep 中唯一使用正则的地方，通常配合 kind 使用以提高性能。

yaml 复制代码

kind: identifier
regex: ^[A-Z_]+$ # 匹配全大写的常量名

nthChild: 基于节点在父容器中的位置进行匹配（类似 CSS 的 :nth-child）。

yaml 复制代码

nthChild: 1 # 匹配第一个子节点

range: 限制匹配的行列范围（通常由外部工具生成，手动编写较少使用）。

5.2 关系规则 (Relational Rules)：上下文约束

关系规则用于描述节点之间的层级或顺序关系，是实现复杂逻辑的关键。

inside: 当前节点必须位于某个特定祖先节点内部。示例：查找循环内部的 await（通常是性能瓶颈）。

yaml 复制代码

rule:
  pattern: await $PROMISE
  inside:
    kind: for_statement
    stopBy: function_declaration # 优化：遇到函数边界停止搜索

has: 当前节点必须包含满足条件的后代节点。示例：查找包含 console.log 的函数。

yaml 复制代码

rule:
  kind: function_declaration
  has:
    pattern: console.log($_)

follows: 当前节点必须紧跟在某个兄弟节点之后。示例：查找紧跟在 import 语句之后的变量声明。

precedes: 当前节点必须紧邻在某个兄弟节点之前。

5.3 复合规则 (Composite Rules)：逻辑组合

用于组合上述规则。

all: 逻辑与（AND）。所有子规则必须同时满足。

any: 逻辑或（OR）。任一子规则满足即可。

not: 逻辑非（NOT）。子规则必须不满足。

综合示例：查找不在 try 块中且包含 API 调用的函数

yaml 复制代码

rule:
  kind: function_declaration
  has:
    pattern: api.call($$$ARGS)
  not:
    inside:
      kind: try_statement

6 重写引擎（The Rewrite Engine）：代码炼金术

找到代码只是第一步，ast-grep 的终极目标是重构。重写引擎包含三个核心组件：fix、transform 和 rewriters。

6.1 fix：基础字符串替换

最简单的修复方式是提供一个字符串模板，其中引用了捕获的元变量。

yaml 复制代码

rule:
  pattern: var $A = $B
fix: const $A = $B

6.2 transform：元变量的数据变换

有时我们需要修改捕获到的元变量内容，例如改变大小写、提取子串等。transform 字段允许我们在 fix 之前对元变量进行处理。

支持的变换操作：

substring: 截取字符串（支持负索引）
replace: 使用正则替换文本内容
convert: 大小写转换（camelCase, snake_case, PascalCase, upperCase, lowerCase）

示例：将常量名转换为小写

yaml 复制代码

rule:
  pattern: const $CONST = $VAL
transform:
  LOWER_NAME:
    convert:
      source: $CONST
      toCase: lowerCase
fix: const $LOWER_NAME = $VAL

6.3 rewriters：递归重写的高级技巧

这是 ast-grep 最强大的功能之一，专门解决"一对多"或"复杂结构遍历"的难题。

假设我们需要将一个包含多个属性的对象拆分为多个独立的变量声明（这在 Vue Options API 迁移中非常常见）：

输入：

javascript 复制代码

const obj = { a: 1, b: 2, c: 3 };

目标：

javascript 复制代码

const a = 1;
const b = 2;
const c = 3;

普通的 fix 无法做到这一点，因为 $$$PROP 捕获的是整个属性列表。我们需要遍历这个列表。

解决方案：

定义一个 rewriter 规则，专门处理单个属性（a: 1 -> const a = 1;）
在主规则中，使用 rewrite 变换，将 rewriter 应用于捕获的列表

yaml 复制代码

rule:
  pattern: const obj = { $$$PROPS }

transform:
  NEW_CODE:
    rewrite:
      source: $$$PROPS
      rewriters: [prop-to-var]
      joinBy: "\n" # 用换行符连接结果

fix: $NEW_CODE

rewriters:
  - id: prop-to-var
    rule:
      kind: pair
      pattern: $KEY: $VAL
    fix: const $KEY = $VAL;

7 Vue.js 深度集成与策略

Vue.js 的单文件组件（SFC）对代码分析工具提出了巨大挑战。一个 .vue 文件实际上包含了三种语言：HTML (Template), JavaScript/TypeScript (Script), CSS/SCSS (Style)。要完美支持 Vue，我们需要根据需求选择不同的解析策略。

7.1 策略一：HTML 解析模式（基础支持）

对于简单的模板分析，或者仅需处理顶层标签结构，可以将 .vue 文件视为 HTML 处理。这是最简单的配置方式。

sgconfig.yml:

yaml 复制代码

languageGlobs:
  html:
    - "*.vue"

局限性 ：在这种模式下，<script> 标签内的代码被视为纯文本（Text Node）。你无法用 JavaScript 模式去匹配其中的函数或变量。这仅适用于模板重构（如迁移 slot 语法）。

7.2 策略二：语言注入（Language Injection）模式（完美支持）

为了深入分析 <script> 和 <style> 内部，必须使用 ast-grep 的语言注入功能。这允许我们在一个宿主语言（Vue/HTML）文档中划定特定区域，并指定用另一种语言（JS/TS/CSS）来解析该区域。

7.2.1 准备自定义 Vue 语言库

虽然 ast-grep 内置了许多语言，但为了获得最佳效果，有时需要手动配置 Vue 的 Tree-sitter 库。

sgconfig.yml 配置：

yaml 复制代码

customLanguages:
  vue:
    libraryPath:.tree-sitter/vue.so # 需预先编译
    extensions: [vue]
    expandoChar: $

7.2.2 配置注入规则

我们需要告诉 ast-grep：遇到 <script lang="ts"> 时，请切换到 TypeScript 解析器。

yaml 复制代码

languageInjections:
  # 处理 TypeScript 脚本
  - hostLanguage: vue
    rule:
      pattern: <script lang="ts">$$$CONTENT</script>
    injected: typescript
  
  # 处理 Setup 语法糖
  - hostLanguage: vue
    rule:
      pattern: <script setup>$$$CONTENT</script>
    injected: typescript

  # 处理普通 JavaScript
  - hostLanguage: vue
    rule:
      pattern: <script>$$$CONTENT</script>
      not: { regex: lang= } # 排除已匹配的 ts
    injected: javascript

一旦配置完成，你在 rules/ 目录下编写的 TypeScript 规则（language: typescript）将自动穿透 .vue 文件，匹配 <script> 标签内的代码，仿佛它们是独立的 .ts 文件一样。

8 实战案例：Vue 2 Options API 迁移至 Composition API

这是前端领域目前需求最迫切、难度最大的重构任务之一。我们将通过一系列 ast-grep 规则，演示如何自动化完成这一迁移。

8.1 任务拆解

Options API 代码：

javascript 复制代码

export default {
  data() {
    return {
      count: 0,
      title: 'Hello'
    }
  },
  methods: {
    increment() {
      this.count++;
    }
  }
}

目标 Composition API 代码（<script setup>）：

javascript 复制代码

import { ref } from 'vue';

const count = ref(0);
const title = ref('Hello');

const increment = () => {
  count.value++;
};

8.2 第一步：重构 data() 为 ref()

我们需要提取 data 返回对象的所有属性，并将其转换为 const x = ref(y) 格式。

规则文件：rules/vue-data-to-ref.yml

yaml 复制代码

id: vue-data-to-ref
language: TypeScript # 通过注入生效
rule:
  kind: method_definition
  pattern: |
    data() {
      return { $$$PROPS }
    }
transform:
  REF_DEFS:
    rewrite:
      source: $$$PROPS
      rewriters: [prop-to-ref-const]
      joinBy: "\n"
fix: |
  /* TODO: Move to setup */
  $REF_DEFS

rewriters:
  - id: prop-to-ref-const
    rule:
      kind: pair
      pattern: $KEY: $VAL
    fix: const $KEY = ref($VAL);

此规则会将 data() 方法体替换为一系列 const 声明。开发者后续只需将这些声明移动到 <script setup> 顶层即可。

8.3 第二步：处理 this 上下文引用

在 Options API 中，状态通过 this.count 访问；在 setup 中，ref 变量需通过 .value 访问（在模板中自动解包，但在 JS 中需要）。这是一个典型的上下文敏感重构。

规则文件：rules/vue-remove-this.yml

yaml 复制代码

id: vue-remove-this
language: TypeScript
rule:
  pattern: this.$PROP
  inside:
    kind: export_statement # 限制范围，防止误伤普通类中的 this
fix: $PROP.value

注意：这是一个激进的规则。在实际工程中，你可能需要更精细的约束，例如检查 $PROP 是否确实是定义在 data 中的变量。这可以通过 ast-grep 的多步扫描或编写脚本来实现。

8.4 第三步：v-model 语法升级

Vue 2 的 v-model 对应属性 value 和事件 input。Vue 3 变更为 modelValue 和 update:modelValue。

规则文件：rules/vue-vmodel-migration.yml

yaml 复制代码

id: vue3-vmodel-rename
language: HTML # 针对模板部分
rule:
  kind: attribute
  pattern: v-model="$VAR"
  # 这里可以添加 constraints 检查组件名，如果只针对特定组件迁移
fix: v-model:modelValue="$VAR"

如果组件定义了 model: { prop: 'checked', event: 'change' }，情况会更复杂。这种情况下，建议结合 ast-grep 的搜索功能定位受影响组件，然后手动或半自动处理。

9 高级开发流：VS Code 与 CI/CD 集成

9.1 调试工作流

在编写上述复杂的 Vue 迁移规则时，不可避免会遇到匹配失败的情况。高效的调试流程如下：

打开目标 .vue 文件
启动 AST 查看器：在 VS Code 中调用 ast-grep: Debug Query
检查注入状态：确保 <script> 标签内的代码被正确识别为 program (TypeScript) 而非 text
如果显示为 text，说明语言注入配置有误
验证 Kind：将光标移至 data 关键字，确认其 CST 节点类型（如 property_identifier 或 method_definition），据此调整规则中的 kind

9.2 CI/CD 自动化门禁

为了防止重构后的代码回退（例如有人又意外提交了 var 或 Options API 代码），应将 ast-grep 加入流水线。

GitHub Actions 示例：

yaml 复制代码

name: Code Standard
on: [push, pull_request]
jobs:
  ast-grep-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install ast-grep
        run: npm install @ast-grep/cli -g
      - name: Scan Codebase
        run: sg scan --config sgconfig.yml

sg scan 命令会以非零状态码退出如果发现 severity: error 的违规项，从而阻断合并。

10 进阶：编程式 API (NAPI)

对于那些仅靠 YAML 无法描述的逻辑（例如：需要读取外部配置文件来决定重命名映射，或者需要跨文件分析），ast-grep 提供了 JavaScript 接口（基于 N-API 绑定 Rust 核心）。

脚本示例：统计项目中所有 Vue 组件的 Props 定义

javascript 复制代码

const { parse } = require('@ast-grep/napi');
const fs = require('fs');
const glob = require('fast-glob');

const files = glob.sync('src/**/*.vue');

files.forEach(file => {
  const content = fs.readFileSync(file, 'utf-8');
  // 假设我们已经通过某种方式提取了 script 内容，或者直接解析
  // 简单起见，这里假设是处理 extracted script
  const root = parse('typescript', content).root();
  
  const props = root.findAll({
    pattern: 'defineProps($$$ARGS)'
  });
  
  if (props.length > 0) {
    console.log(`File ${file} uses defineProps`);
  }
});

这种能力使得前端架构师可以编写非常复杂的"自定义 linter"或"代码分析报表"，而性能远超使用 Babel/TypeScript Compiler API 实现的同类工具。

11 结语

ast-grep 不仅仅是一个工具，它代表了前端工程化能力的一次跃升。通过掌握 AST/CST 的结构化搜索与重写技术，开发者不再是被动地维护代码，而是能够像外科医生一样对代码库进行精准、高效的手术。

对于 Vue 开发者而言，从 Options API 到 Composition API 的迁移不再是一场耗时数月的人力噩梦，而变成了一系列可控、可测试、自动化的工程任务。随着 ast-grep 生态的成熟（如更多现成的规则集 vue-codemod 的移植），我们有理由相信，结构化代码变换将成为未来前端开发的标准技能。

希望这份手册能成为你掌握这一利器的起点，助你在架构演进的道路上游刃有余。