ast-grep

ast-grep 社区最佳实践

这是一份由 ast-grep 社区维护的全面指南，介绍 ast-grep 规则编写和使用的最佳实践。指南涵盖 8 个类别中的 46 条规则，并按影响程度排序，以指导自动化规则生成和代码转换。

适用场景

以下情况请参考这些指南：

• 为 lint 检查或搜索编写新的 ast-grep 规则
• 调试与预期代码不匹配的模式
• 优化规则在大型代码库中的性能
• 以规范的组织方式设置 ast-grep 项目
• 检查 ast-grep 规则的正确性和可维护性

通用工作流

创建 ast-grep 代码搜索规则时，请遵循以下工作流：

第 1 步：理解查询

明确你要查找的内容：

• 目标编程语言
• 要处理的边界情况
• 要包含和排除的内容

第 2 步：创建示例代码

编写一段示例代码，表示预期的匹配模式。

第 3 步：编写 ast-grep 规则

选择合适的方法：

• 简单结构使用 pattern
• 复杂结构使用 kind 和 has/inside
• 复合查询结合使用 all、any 或 not
• 关系规则（inside、has）始终使用 stopBy: end，确保完成完整搜索

第 4 步：测试规则

# Inspect AST structure
ast-grep run --pattern '[code]' --lang [language] --debug-query=ast

# Test inline rule
echo "[code]" | ast-grep scan --inline-rules "[rule]" --stdin

# Test from file
ast-grep scan --rule [file.yml] [path]

第 5 步：搜索代码库

部署已验证的规则：

# Search with pattern (simple matches)
ast-grep run --pattern '[pattern]' --lang [language] [path]

# Search with rule file (complex queries)
ast-grep scan --rule [file.yml] [path]

# Apply fixes interactively
ast-grep scan --rule [file.yml] --interactive [path]

快速提示

1. 始终使用 stopBy: end - 确保关系规则遍历完整子树
2. 从简单开始，逐步增加复杂度 - 先从模式入手，再尝试 kind，最后使用关系规则
3. 通过 AST 检查进行调试 - 使用 --debug-query=ast 验证结构匹配
4. 在内联规则中转义 - 对 Shell 命令使用 \$VAR 或单引号
5. 先在 playground 中测试 - 使用 https://ast-grep.github.io/playground.html 快速迭代

按优先级划分的规则类别

优先级	类别	影响	前缀
1	模式正确性	CRITICAL	pattern-
2	元变量用法	CRITICAL	meta-
3	规则组合	HIGH	compose-
4	约束设计	HIGH	const-
5	重写正确性	MEDIUM-HIGH	rewrite-
6	项目组织	MEDIUM	org-
7	性能优化	MEDIUM	perf-
8	测试与调试	LOW-MEDIUM	test-

快速参考

1. 模式正确性（CRITICAL）

• pattern-valid-syntax - 使用有效且可解析的代码作为模式
• pattern-language-aware - 考虑特定语言的语法差异
• pattern-context-selector - 对代码片段使用 context 和 selector
• pattern-avoid-comments-strings - 避免匹配注释和字符串内部的内容
• pattern-strictness-levels - 适当配置模式严格程度
• pattern-kind-vs-pattern - 根据特定性需求选择 kind 或 pattern
• pattern-debug-ast - 使用 debug query 检查 AST 结构
• pattern-nthchild-matching - 使用 nthChild 按索引进行位置匹配
• pattern-range-matching - 使用 range 匹配字符位置

2. 元变量用法（关键）

• meta-naming-convention - 遵循元变量命名约定
• meta-single-node - 使用元变量匹配单个 AST 节点
• meta-reuse-binding - 重用元变量以强制匹配相等
• meta-underscore-noncapture - 使用下划线前缀进行非捕获匹配
• meta-named-vs-unnamed - 使用双美元符号匹配未命名节点
• meta-multi-match-lazy - 了解多重匹配变量采用惰性匹配

3. 规则组合（高）

• compose-all-for-and-logic - 使用 all 表示规则之间的与逻辑
• compose-any-for-or-logic - 使用 any 表示规则之间的或逻辑
• compose-not-for-exclusion - 使用 not 表示排除模式
• compose-inside-for-context - 使用 inside 进行上下文匹配
• compose-has-for-children - 使用 has 指定子节点要求
• compose-matches-for-reuse - 使用 matches 重用规则
• compose-precedes-follows - 使用 precedes 和 follows 指定顺序位置
• compose-field-targeting - 使用 field 定位特定子节点

4. 约束设计（高）

• const-kind-filter - 使用 kind 约束筛选元变量
• const-regex-filter - 使用正则表达式约束匹配文本模式
• const-not-inside-not - 避免在 not 规则中使用约束
• const-pattern-constraint - 使用模式约束进行结构筛选
• const-post-match-timing - 了解约束在匹配后应用

5. 重写正确性（中高）

• rewrite-preserve-semantics - 在重写中保留程序语义
• rewrite-meta-variable-reference - 在 fix 中引用所有必要的元变量
• rewrite-transform-operations - 使用 transform 执行复杂重写
• rewrite-test-before-deploy - 在具有代表性的代码上测试重写
• rewrite-syntax-validity - 确保 fix 模板生成有效语法

6. 项目组织（中）

• org-project-structure - 使用标准项目目录结构
• org-unique-rule-ids - 使用唯一且描述明确的规则 ID
• org-severity-levels - 分配适当的严重性级别
• org-file-filtering - 使用文件筛选针对特定规则
• org-message-clarity - 编写清晰且可执行的消息

7. 性能优化（中）

• perf-specific-patterns - 优先使用特定模式，而非通用模式
• perf-stopby-boundaries - 使用 stopBy 限制搜索深度
• perf-thread-parallelism - 利用线程进行并行扫描
• perf-avoid-regex-heavy - 避免在热点路径中使用开销大的正则表达式

8. 测试与调试（低至中等）

• test-valid-invalid-cases - 编写有效和无效测试用例
• test-snapshot-updates - 使用快照测试验证修复
• test-playground-first - 先在 Playground 中测试模式
• test-edge-cases - 测试边缘情况和边界条件

如何使用

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

• AGENTS.md - 包含所有规则的完整编译指南

参考文件

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息