用途:这是一份面向 ast-grep 规则编写与使用的社区最佳实践指南,适用于编写新的 lint 或搜索规则、调试无法匹配预期代码的模式、为大型代码库优化规则性能、组织 ast-grep 项目,以及审查规则的正确性与可维护性。
主要能力:内容包含 42 条规则,分为 8 个按影响度排序的类别。1) 模式正确性(CRITICAL,前缀 pattern-):使用可解析的合法代码作为模式、注意语言语法差异、用 context 与 selector 处理代码片段、避免匹配注释与字符串、配置模式严格度、按需选择 kind 或 pattern、用 debug query 查看 AST。2) 元变量使用(CRITICAL,meta-):命名约定、单节点匹配、复用元变量强制相等、下划线前缀表示非捕获、双美元匹配未命名节点、多匹配变量为惰性。3) 规则组合(HIGH,compose-):all 表示 AND、any 表示 OR、not 表示排除、inside 做上下文匹配、has 要求子节点、matches 复用规则。4) 约束设计(HIGH,const-):kind 过滤元变量、regex 文本过滤、避免在 not 内放约束、pattern 结构过滤、约束在匹配后生效。5) 重写正确性(MEDIUM-HIGH,rewrite-):保持语义、在 fix 中引用必要元变量、用 transform 处理复杂重写、先在代表性代码上测试、确保修复模板语法有效。6) 项目组织(MEDIUM,org-):标准目录结构、唯一描述性规则 ID、合适严重级别、文件过滤、清晰可执行的提示信息。7) 性能优化(MEDIUM,perf-):具体模式优于通用模式、用 stopBy 限制搜索深度、利用多线程并行扫描、避免热路径中的重正则。8) 测试与调试(LOW-MEDIUM,test-):同时编写有效与无效用例、用快照测试验证修复、先在 playground 中测试、覆盖边界条件。
使用方式:阅读各参考文件获取详细说明与代码示例,包括 _sections.md(类别结构与影响级别)、_template.md(新增规则模板),以及汇总全部规则的 AGENTS.md。
限制:资料未提供安装命令、运行命令、版本号、许可、收费或平台支持等具体信息,暂未提供。