精通AST-GREP电子书

内 容 提 要

推荐序 结构化思维：AI时代开发者的"进化武器"

作者简介

前 言

入门篇 夯实概念基础

第1章 ast-grep 简介

1.1 什么是 ast-grep？

1.2 基于文本的代码搜索之局限

1.3 ast-grep 如何解决问题

1.4 核心能力

1.5 为什么结构化搜索至关重要

1.6 与 AST 操作 API 的比较

1.7 设计特性

第2章 抽象语法树、解析器与源代码转换

2.1 抽象语法树：代码的结构化表示

2.2 具体语法树：保留结构细节

2.3 解析过程：从文本到树

2.4 节点类型：具名与匿名

2.5 Tree-Sitter：解析器生成与基础设施

2.6 结构化匹配 vs. 文本匹配：对模式的影响

第3章 ast-grep 快速上手

3.1 ast-grep 游乐场：无需安装即可尝试

3.2 安装 ast-grep

3.3 运行简单的模式搜索

3.4 编写并使用规则

3.5 常用子命令

3.6 下一步

基础篇 掌握核心技能

第4章 模式化匹配

4.1 为什么文本搜索会失败

4.2 模式语义

4.3 结构化匹配 vs. 文本匹配

4.4 匹配机制

4.5 模式语法与调用

4.6 模式作用域与深度无关性

4.7 模式有效性要求

第5章 元变量替换

5.1 固定模式的局限性

5.2 什么是元变量

5.3 元变量语法

5.4 单节点元变量

5.5 多重元变量

5.6 捕获组与一致性

5.7 非捕获元变量

5.8 约束与边缘情况

第6章 基于规则的模式规范

6.1 动机：模式字符串的局限性

6.2 概念模型

6.3 规则架构 (Rule Schema)

6.4 调用模型

6.5 规则对象 (Rule Object)

6.6 原子规则：模式匹配

6.7 关系规则：上下文相关的匹配

6.8 复合规则：逻辑组合

6.9 元变量共享与交叉引用

6.10 实际示例

6.11 使用注意事项

第7章 使用 kind 进行节点类型匹配

7.1 动机：当模式无法胜任时

7.2 Tree-Sitter 类型系统

7.3 Kind 规则语义

7.4 将 Kind 与其他规则结合使用

7.5 结构化选择器 (Structural Selectors)

7.6 实际示例

7.7 使用注意事项

第8章 使用 regex 进行文本内容匹配

8.1 结构盲点问题

8.2 Regex 规则规范

8.3 应用领域

8.4 合取约束的必要性 (The Conjunction Imperative)

8.5 测试函数识别

8.6 标识符模式匹配

8.7 不区分大小写的匹配

8.8 字符串字面量内容检测

8.9 私有成员约定检测

8.10 注释标记检测

8.11 复杂模式：弃用 API 检测

8.12 性能特性

8.13 局限性

第9章 关系规则

9.1 语境问题

9.2 树关系作为匹配约束

9.3 祖先语境匹配：inside

9.4 后代语境匹配：has

9.5 兄弟顺序：follows 和 precedes

9.6 组合多个关系规则

9.7 关系规则实践

第10章 复合规则

10.1 组合问题

10.2 合取：all

10.3 析取：any

10.4 否定：not

10.5 理解复合规则的语义

10.6 隐式合取

10.7 组合多个规则

第11章 结构化代码转换

11.1 Fix 机制

11.2 转换调用模型

11.3 元变量替换语义

11.4 缩进规范化

11.5 多规则规范

11.6 转换模式

11.7 元变量绑定约束

11.8 语法有效性与模板片段

11.9 超越模板替换

中级篇 深化模式编写，实现工具链高效集成

第12章 带有上下文的模式对象

12.1 语法完整性要求

12.2 模式对象语义 (Pattern Object Semantics)

12.3 调用模型 (Invocation Model)

12.4 CLI 调用

12.5 实际应用

12.6 严格度级别 (Strictness Levels)

12.7 模式对象 vs. 类型约束 (Kind Constraints)

12.8 使用指南

12.9 局限性与边缘情况

第13章 细化关系规则：stopBy 与 field

13.1 搜索边界问题

13.2 stopBy：搜索终止控制

13.3 field：结构角色约束 (Structural Role Constraints)

13.4 结合使用 stopBy 和 field

13.5 实际应用

13.6 性能影响

13.7 总结

第14章 工具规则：可重用的匹配逻辑

14.1 规范与调用模型

14.2 局部工具规则定义

14.3 全局工具规则定义

14.4 matches 复合规则

14.5 递归工具规则 (Recursive Utilities)

14.6 工具规则组织策略

14.7 实际应用

14.8 工具规则库与重用模式

14.9 性能考量

14.10 总结

第15章 约束元变量匹配

15.1 仅靠模式匹配的局限性

15.2 约束语义：两阶段匹配

15.3 约束语法规范 (Constraint Syntax Specification)

15.4 约束谓词 (Constraint Predicates)

15.5 应用示例

15.6 约束评估语义 (Constraint Evaluation Semantics)

15.7 规则开发方法论

15.8 诊断技巧

15.9 总结

第16章 使用 sgconfig.yml 进行项目配置

16.1 项目配置模型

16.2 项目初始化

16.3 配置模式 (Schema)

16.4 语言与解析器配置

16.5 配置模式 (Patterns)

16.6 调用模型 (Invocation Models)

16.7 配置指南

16.8 常见配置问题

16.9 总结

第17章 测试你的规则：使用 ast-grep test 验证正确性

17.1 问题域：误报与漏报

17.2 测试剖析：有效与无效代码示例

17.3 测试组织：配置与文件结构

17.4 测试执行：解读结果

17.5 多行测试用例：处理真实代码

17.6 快照测试：捕获诊断细节

17.7 测试驱动开发：先写测试

17.8 边缘情况覆盖：测试边界条件

17.9 调试测试失败：系统诊断

17.10 集成到开发工作流

17.11 结论

第18章 编辑器集成：VSCode 与 LSP 实时代码分析

18.1 集成架构

18.2 Visual Studio Code 扩展

18.3 语言服务器协议 (LSP) 集成

18.4 配置选项

18.5 诊断性能与响应速度

18.6 实际开发工作流

18.7 排除集成故障

18.8 集成最佳实践

18.9 结论

第19章 ast-grep 游乐场：基于浏览器的开发实验室

19.1 架构与能力

19.2 操作模式：模式与配置

19.3 AST 可视化：理解语法结构

19.4 开发工作流

19.5 高级能力

19.6 操作约束

19.7 开发工作流中的战略应用

19.8 结论

第20章 调试规则：系统的诊断与解决

20.1 规则失效的本质

20.2 诊断工具

20.3 调试策略：增量组合

20.4 调试策略：AST 验证

20.5 调试策略：严格度校准

20.6 常见失效模式及解决方法

20.7 元变量绑定顺序

20.8 系统化的调试工作流

20.9 高效调试的原则

20.10 社区资源

第21章 借助 AI 助手开发规则

21.1 AI 与 ast-grep 的协同效应

21.2 ast-grep Claude Skill

21.3 构建有效的提示词 (Prompts)

21.4 实践工作流

21.5 与开发环境的集成

21.6 局限性与验证

21.7 参考提示词

21.8 建立有效的协作

高级篇 深挖ast-grep高阶能力与应用边界

第22章 深度探索：ast-grep 如何理解你的模式

22.1 模式转换流水线

22.2 第一阶段：预处理 (Preprocessing)

22.3 第二阶段：解析 (Parsing)

22.4 第三阶段：提取 (Extraction)

22.5 第四阶段：检测 (Detection)

22.6 模式编译实践

22.7 使用游乐场调试模式

22.8 对模式设计的启示

22.9 走向模式精通

第23章 提升匹配精度：严格度语义 (Strictness Semantics)

23.1 匹配等价性问题

23.2 严格度的定义

23.3 智能算法：默认行为

23.4 CST 严格度：完全语法保真

23.5 AST 严格度：真正的结构化匹配

23.6 宽松模式 (Relaxed Strictness)：容忍注释的匹配

23.7 签名模式 (Signature Strictness)：结构形状匹配

23.8 模板模式 (Template Strictness)：半结构化匹配

23.9 严格度对比：多级别下的单一模式

23.10严格度的指定

23.11 实际应用

23.12 选择合适的严格度

23.13 总结

第24章 高级 fix：扩展重写范围

24.1 基于节点的 Fix 之局限性

24.2 FixConfig 对象

24.3 移除对象属性

24.4 移除数组元素

24.5 双向扩展

24.6 使用复合规则进行扩展

24.7 非贪婪扩展行为

24.8 当扩展不足时

24.9 扩展规则的设计原则

24.10 与多重匹配操作的集成

24.11 调试扩展行为

第25章 转换捕获值：元变量上的字符串操作

25.1 直接置换的局限性

25.2 转换流水线架构

25.3 转换操作 (Transform Operations)

25.4 字符串风格转换语法

25.5 实际应用

25.6 运行语义与边缘情况

25.7 组合模式与最佳实践

25.8 局限性与约束

第26章 Rewriters：组合式代码转换

26.1 Find & Patch 范式的扩展

26.2 Rewriter 语法与语义

26.3 详细示例：字典构造函数转换

26.4 多个重写器：基于模式匹配的分发

26.5 重写器内部的嵌套转换

26.6 重写器中的元变量作用域

26.7 递归重写器：处理嵌套结构

26.8 joinBy 参数：控制组合

26.9 调试重写器规范

26.10 设计初衷：声明式转换

26.11 结论

第27章 使用 labels 自定义匹配高亮

27.1 默认高亮机制

27.2 标签：精准的高亮控制

27.3 实践应用：类中方法示例

27.4 细化安全诊断

27.5 标注多元变量（Multi-Metavariable）

27.6 编辑器集成与 LSP 语义

27.7 设计决策：为何采用声明式标签

27.8 配置模式

27.9 调试标签配置

27.10 局限性

27.11 结论

第28章 代码调用：ast-grep API

28.1 编程集成的必要性

28.2 API 工作流

28.3 绑定层架构

28.4 可用的绑定

28.5 Python API

28.6 JavaScript/TypeScript API

28.7 性能考量

28.8 局限性

第29章 流水线集成：JSON 输出与 Stdin 模式

29.1 流水线集成的必要性

29.2 JSON 输出：机器可读的结果

29.3 Stdin 模式：处理代码流

29.4 使用 jq 处理 JSON 输出

29.5 构建自动化工作流

29.6 与编程语言集成

29.7 性能考量

29.8 错误处理

29.9 局限性与考量

第30章 使用自定义语言扩展 ast-grep

30.1 基础：Tree-Sitter 的解析器架构

30.2 自定义语言的适用场景

30.3 集成自定义语言的要求

30.4 编译 Tree-Sitter 解析器

30.5 配置自定义语言

30.6 使用自定义语言

30.7 实践示例：集成 Julia

30.8 常见问题排查

30.9 语法质量考量

30.10 创建新语法

30.11 性能影响

30.12 版本兼容性

30.13 组织最佳实践

30.14可扩展性原则

第31章 处理嵌入式代码：语言注入

31.1 多语言文档难题

31.2 语言注入：多阶段扫描

31.3 内置注入：HTML 中的 JavaScript 和 CSS

31.4 自定义注入配置：styled-components

31.5 动态语言选择

31.6 高级示例：JavaScript 中的 GraphQL

31.7 注入规则模式：超越简单模板

31.8 注入深度限制

31.9 边缘情况与约束

31.10 诊断策略

31.11 总结

第32章 架构边界与工具选择

32.1 语法与语义的鸿沟

32.2 ast-grep 的架构约束

32.3 排除的分析能力

32.4 在工具生态系统中的定位

32.5 工具选择的决策标准

32.6 互补的工具使用

32.7 语法分析的生态位

32.8 作为设计决策的局限性

32.9 总结：架构意识实现有效使用

附录 ast-grep 术语表