ast-grep-block 代码审查门禁技能

本文件中的 templates/... 均指本技能目录下的 templates/ 子目录。

用 code-checklist 规则集对源代码项目进行分级 AST 静态审查，输出命中清单与 CI 退出码。

适用场景

• 提交/合并前的质量门禁（high 命中则阻断）
• 代码审查前的自动化预检（全级别扫描登记问题）
• 重构前的存量问题盘点（按级别/类别统计）
• CI 流水线集成的质量门禁节点

核心思路

单一 CLI 模式：直接调用 code-checklist 仓库的 scripts/run.sh，该脚本封装了规则遍历、.astgrepignore 过滤、分级统计、CI 退出码输出。

不使用 ast-grep-mcp，因为：

• 审查语义需要"全规则批量 + ignore 过滤 + 退出码"，这些是 CLI 模式的优势
• MCP 适合"交互式抽查看上下文"，不适合门禁场景

工具依赖

验证：

ast-grep --version && python3 -c 'import yaml' && jq --version

规则库锚定

规则库通过环境变量定位：

# 检查锚定
[[ -n "$CODE_CHECKLIST_ROOT" ]] || CODE_CHECKLIST_ROOT=/disk2/helly_data/code/ast-grep-rules/code-checklist
[[ -x "$CODE_CHECKLIST_ROOT/scripts/run.sh" ]] || { echo "规则库未就绪: $CODE_CHECKLIST_ROOT" >&2; exit 2; }

# 查看当前覆盖（规则数）
for lang in java cpp ansi_c; do
    echo -n "$lang: "
    find "$CODE_CHECKLIST_ROOT/rules/$lang" -name '*.yml' | wc -l
done

如需切换规则库版本或位置，请在 shell 环境变量中配置 CODE_CHECKLIST_ROOT，本 skill 不在仓库内复制规则。

分级语义（用户口径）

执行流程

步骤 1：确定目标范围

先识别项目结构，明确：

• 源代码根目录（如 src/main/java、src/、<module>/src）
• 构建产物目录（build/、target/、out/、cmake-build-*/）→ 必须排除
• 第三方/二方库（third_party/、vendor/、lib/）→ 按需排除
• 测试目录（src/test/、gtest/）→ 按需排除

# 顶层结构盘点
eza <project_root>

# 文件数预估
fd --no-ignore -e java -t f <project_root> | wc -l   # Java
fd --no-ignore -e cpp -e h -e hpp -t f <project_root> | wc -l  # C++
fd --no-ignore -e c -e h -t f <project_root> | wc -l  # ANSI C

步骤 2：选语言与级别

推荐顺序：先跑 high 修阻断项，再跑 --all 盘点全量。

步骤 3：执行扫描（核心命令）

# 3a. 仅 high 级别（CI 门禁场景）
"$CODE_CHECKLIST_ROOT/scripts/run.sh" \
    --lang java --level high \
    --path <project_root>
echo "退出码: $?  # 0 通过 / 1 high 命中 / 2 参数错误"

# 3b. 全级别扫描（盘点场景）
"$CODE_CHECKLIST_ROOT/scripts/run.sh" \
    --lang java --all \
    --path <project_root>

# 3c. JSON 输出（CI/工具对接）
"$CODE_CHECKLIST_ROOT/scripts/run.sh" \
    --lang java --level high \
    --path <project_root> --json > report.json
echo $?  # 退出码仍正确返回

便捷封装见 templates/run-cli.sh，可复制到目标项目 scripts/ 直接 ./scripts/run-cli.sh java high .。

步骤 4：解读报告

文本输出格式（默认）：

=== ast-grep 扫描报告 ===
扫描路径: /path/to/project
高级(high): 12 条
中级(medium): 5 条
低级(low): 2 条

--- HIGH 命中明细 ---
src/dao/UserDao.java:42:13:empty-catch-block: catch (Exception e) {}
src/util/Crypto.java:108:25:hardcoded-secret: private String key = "sk-12345";
...

每行格式：<文件>:<行号>:<列号>:<规则ID>: <命中代码行>

JSON 输出格式（--json）：

[
  {
    "file": "src/dao/UserDao.java",
    "range": {"byteOffset": 1234, "start": {"line": 41, "column": 12}, "end": {"line": 42, "column": 25}},
    "lines": "catch (Exception e) {}",
    "text": "...AST 节点文本...",
    "ruleId": "empty-catch-block",
    "level": "high"
  },
  ...
]

详细字段说明与统计命令见 templates/report-summary.md。

步骤 5：复核 high 命中（必做）

high 命中必须逐条人工确认：

# 抽取所有 high 命中文件清单
jq -r 'select(.level=="high") | .file' report.json | sort -u > /tmp/high-files.lst

# 查看具体命中规则分布
jq -r 'select(.level=="high") | .ruleId' report.json | sort | uniq -c | sort -rn

# 抽查单文件原始上下文
rg -n -A 3 -B 3 'catch \(' src/dao/UserDao.java

对每条 high 命中判定：

• 真实问题 → 立即修复，重新跑步骤 3 验证退出码变为 0
• 规则误报 → 优先优化规则 constraints（修改 rule YAML）；次选登记 .astgrepignore

步骤 6：误报抑制（兜底）

误报抑制分两层，优先层优于兜底层：

6a. 优先层：优化规则 constraints

修改规则文件本身（在 $CODE_CHECKLIST_ROOT/rules/{lang}/{level}/...），通过 not/has/constraints.regex 等机制缩小命中范围。改后必须验证：

"$CODE_CHECKLIST_ROOT/scripts/validate-examples.sh"  # 正负样例回归
"$CODE_CHECKLIST_ROOT/scripts/validate-meta.sh"      # 元数据合法性

6b. 兜底层：.astgrepignore

在目标项目根（被扫描的项目，不是规则库）放置 .astgrepignore：

- rule: hardcoded-secret
  paths:
    - "src/test/resources/**"            # 测试资源目录常含示例密码
    - "**/test/**/*Fixture.java"
- rule: system-out-print
  paths:
    - "**/Main.java"                     # main 入口可打印 banner

run.sh 会自动读取被扫描项目根的 .astgrepignore 并对命中结果过滤。

注意：run.sh 只在被扫描路径根查找 .astgrepignore，所以必须在目标项目根放置，不是规则库根。

步骤 7：CI 集成

# CI 流水线片段（GitHub Actions / GitLab CI / Jenkins shell 步骤通用）
- name: ast-grep code-checklist
  run: |
    export CODE_CHECKLIST_ROOT=/path/to/code-checklist
    "$CODE_CHECKLIST_ROOT/scripts/run.sh" \
        --lang java --level high \
        --path . --json > ast-grep-report.json
    # 退出码 1 时 CI 自动失败

进阶 CI 模式（多语言、按目录增量、PR 仅扫变更文件）见 templates/recipes.md。

命令速查

输出位置

• 文本报告：默认 stderr + stdout（按 run.sh 实现）
• JSON 报告：通过 --json 参数，需重定向到文件
• 临时输出：本 skill 不创建临时文件，由调用方决定保存路径

陷阱与故障排除

最佳实践

1. 范围分级：先小范围试跑（如单模块 --path src/main/java/com/foo/bar），验证无误后再全量
2. 先 high 后 all：先解决 high 阻断项，再盘点 medium/low
3. 构建产物必排：build/、target/、out/、cmake-build-*/ 含生成代码会严重噪声
4. 复核必做：high 命中必须逐条人工确认，不能盲信工具
5. 优先优化规则：误报优先修 constraints，.astgrepignore 仅兜底
6. 结果归档：JSON 报告归档到 CI artifact，便于跨构建对比
7. 增量扫描：PR/commit 场景只扫变更文件，避免全量噪音（见 recipes）
8. 环境变量固化：CODE_CHECKLIST_ROOT 配置到 shell rc 或 CI 变量，避免硬编码

适用与限制

适用：

• Java / C++ / ANSI C 三语言（规则库覆盖范围）
• 字符串字面量、AST 结构可表达的代码模式
• CI/CD 质量门禁、提交前预检、审查前盘点

不适用：

• 规则库未覆盖的语言（Python/Go/Rust 等需扩展规则）
• 跨文件数据流分析（需 SonarQube / Infer 等）
• 运行时缺陷（需动态分析）
• 复杂类型推断（ast-grep 是语法层，无类型信息）

模板引用

技能版本: 1.0.0 核心工具: code-checklist/scripts/run.sh（CLI 模式） 依赖外部: $CODE_CHECKLIST_ROOT 规则库 典型耗时: Java 5k 文件 high 扫描 ≈ 30s-2min；C++ 5k 文件 ≈ 1-3min 输出位置: stdout/stderr 或重定向 JSON 文件