ast-grep-block

Files (4)

• SKILL.md
• recipes.md · templates/
• report-summary.md · templates/
• run-cli.sh · templates/

SKILL.md (first lines)

# 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 | >= 0.45.0 | AST 匹配引擎 |
| bash | >= 4 | run.sh 运行环境 |
| python3 + pyyaml | - | 元数据读取 / ignore 解析 |
| jq | >= 1.6 | JSON 输出处理 |

验证：
```bash
ast-grep --version && python3 -c 'import yaml' && jq --version
```

## 规则库锚定

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

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `CODE_CHECKLIST_ROOT` | `/disk2/helly_data/code/ast-grep-rules/code-checklist` | code-checklist 仓库根 |

```bash
# 检查锚定
[[ -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 不在仓库内复制规则。

## 分级语义（用户口径）

| 级别 | 含义 | CI 行为 | run.sh 退出码 |
|------|------|---------|---------------|
| **high** | 必须修改，必须本次修改 | 阻断提交/合并 | 1 |
| **medium** | 必须修改，但并非本次修改 | 登记跟踪，下次迭代 | 0 |
| **low** | 可接受不改 | 提示性建议 | 0 |

## 执行流程

### 步骤 1：确定目标范围

先识别项目结构，明确：

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

```bash
# 顶层结构盘点
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：选语言与级别

| 参数 | 取值 | 默认 |
|------|------|------|
| `--lang` | `java` / `cpp` / `ansi_c` | 必填 |
| `--level` | `high` / `medium` / `low` | 任选其一 |
| `--all` | 扫描所有级别 | 替代 `--level` |

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

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

```bash
# 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 .`。

From hellyguo/self-ai-spec, Apache-2.0.

More from hellyguo/self-ai-spec