feat(ssw-loop): 关卡 I check_clear_coverage.sh 检测 docs 残留

ADR 0014 §Downstream §3 (2026-07-21 follow-up): 自动化关卡
检测 docs/{app}/ 残留状态, 提示开发者加 --clean-docs

阈值设计:
- 0 项 = 已 clean (clear 完整执行, 含 --clean-docs)
- ≤ 10 项 = 标准状态 (关卡 A 必读 7 MD + 4 html 视图)
- 11-13 项 = 略多 WARN
- ≥ 14 项 = clear 不完整, FAIL 提示加 --clean-docs

退出码:
- 0 = OK (≤ 13 项, 关卡 A 通过)
- 1 = 残留过多 (≥ 14 项)
- 2 = 关键缺失 (关卡 A 必读 7 MD 被删, 异常状态)

E2E 测试:
- jxcj (14 项残留): exit 1 → "clear 不完整" + 列出残留样本 + 提示 --clean-docs 命令
- testspace (10 项 + 缺 design.md): exit 2 → "关键文档缺失" 警示
- 干净状态 (clear 后, 0 项): exit 0 → "✓ 残留 ≤ 10"

集成方式: 后续 ssw-loop 阶段 6 加入 (在 check_summary_no_fake_pass.sh 之前).
当前手动调用: bash check_clear_coverage.sh docs/<app>/

引用 ADR 0014 (本回合写): docs/decisions/0014-app-clear-docs-coverage.md
This commit is contained in:
ssw committed 2026-07-21 15:55:27 +08:00
1 parent ae03cf39d1
commit 48f66ab6b3
1 file changed
+91
+91
View File
@@ -0,0 +1,91 @@
#!/bin/bash
# 关卡 I (v3.0+): app clear 完整性检查
# 用法: bash check_clear_coverage.sh <app_dir> [--clean-docs-hint]
#
# 用途: 检测 docs/{app}/ 残留状态, 提示是否需要 --clean-docs
#
# 检测内容:
# 1. docs/{app}/ 目录下文件总数 (含 _assets/test_logs/screenshots/scripts 子目录)
# 2. MD 源文件清单 (vs 已发布的 .html)
# 3. 当 docs/{app}/history-bak/ 已存在时, 列出历史归档大小
#
# 历史:
# - ADR 0014 (2026-07-21): docs/{app}/ 仅清 4 html 是历史 bug, 加 --clean-docs 修
# - 此脚本配套 ADR 0014, 让 ssw-loop 自动检测 docs 残留状态
#
# 退出码:
# 0 = 完整 (残留 ≤ 4 项: 4 html 文件 + 必要的 6 MD 设计依据, 默认保留 OK)
# 1 = 残留超阈值 (> 8 项, 提示 --clean-docs)
# 2 = 关键文件缺失 (关卡 A 必读被删, 不应是 clear 结果, 需人工排查)
set -e
APP_DIR="${1:?用法: $0 <app_dir>, 例: $0 docs/jxcj}"
APP_CODE=$(basename "$APP_DIR")
# 阈值设计: 历史默认 clear 行为会留 14+ 项 (4 html 不动 + 6 MD + 4 子目录 + _assets 等, 见 ADR 0014)
# - 0 项 = 已 clean (clear 完整执行)
# - ≤ 10 项 = 标准状态 (关卡 A 必读 + 4 html 视图)
# - 11-13 项 = 略多, WARN 提示 (例如新增 _assets/test_logs 等开发过程中)
# - ≥ 14 项 = clear 不完整历史状态, FAIL 提示加 --clean-docs
MAX_KEEP=10
WARN_THRESHOLD=11
FAIL_THRESHOLD=14
echo "🔍 关卡 I: 检查 $APP_CODE docs/ 完整性与 clear 残留"
echo " app_dir: $APP_DIR"
if [ ! -d "$APP_DIR" ]; then
echo " ❌ $APP_DIR 不存在"
exit 2
fi
# ============================================================
# 1. 关卡 A 关键 MD 必填检测 (clear 不应误删)
# ============================================================
echo " [关卡 A 必读]"
MISSING=()
for f in design.md testcase.md summary.md plan.md debug.md learnings.md; do
if [ ! -f "$APP_DIR/$f" ]; then
MISSING+=("$f")
fi
done
if [ ${#MISSING[@]} -gt 0 ]; then
echo " ❌ 缺失关键文档: ${MISSING[*]}"
echo " (clear 不应误删这些; 若是 clear 后缺失, 需从 history-bak/{ts}/ 还原)"
exit 2
else
echo " ✓ 7 关键 MD 齐全 (关卡 A 通过)"
fi
# ============================================================
# 2. 残留 MD + html + 子目录
# ============================================================
echo " [docs/ 残留清单]"
MD_COUNT=$(find "$APP_DIR" -maxdepth 1 -name "*.md" 2>/dev/null | wc -l)
HTML_COUNT=$(find "$APP_DIR" -maxdepth 1 -name "*.html" 2>/dev/null | wc -l)
SUBDIR_COUNT=$(find "$APP_DIR" -maxdepth 1 -mindepth 1 -type d ! -name "history-bak" 2>/dev/null | wc -l)
TOTAL=$((MD_COUNT + HTML_COUNT + SUBDIR_COUNT))
echo " MD 源文件: $MD_COUNT"
echo " HTML 渲染: $HTML_COUNT"
echo " 子目录 (不含 history-bak): $SUBDIR_COUNT"
echo " 总计: $TOTAL (阈值保留=$MAX_KEEP, 警告=$WARN_THRESHOLD)"
if [ "$TOTAL" -ge "$FAIL_THRESHOLD" ]; then
echo " ❌ clear 不完整: $TOTAL 项残留, ≥ $FAIL_THRESHOLD 触发 FAIL"
echo " 修复: dacli app clear --appCode=$APP_CODE --clean-docs (移到 history-bak/{ts}/files/docs/)"
echo " 详情见 dacli/docs/decisions/0014-app-clear-docs-coverage.md"
RESIDUAL_LIST=$(find "$APP_DIR" -maxdepth 1 -mindepth 1 ! -name "history-bak" 2>/dev/null | sed "s|^$APP_DIR/||" | head -10)
echo " 残留样本 (前 10):"
echo "$RESIDUAL_LIST" | sed 's/^/ /'
exit 1
elif [ "$TOTAL" -ge "$WARN_THRESHOLD" ]; then
echo " ⚠ 略多 ($TOTAL 项), WARN"
echo " 若准备 clear, 加 --clean-docs"
exit 0
elif [ "$TOTAL" -gt "$MAX_KEEP" ]; then
echo " ⚠ 略多, 但可接受 (关卡 A 必读未删)"
exit 0
else
echo " ✓ 残留 ≤ $MAX_KEEP (默认保留范围合理)"
exit 0
fi