From 48f66ab6b39e7ec8065fd6f1d6cecd6098993ab5 Mon Sep 17 00:00:00 2001 From: ssw Date: Tue, 21 Jul 2026 15:54:08 +0800 Subject: [PATCH] =?UTF-8?q?feat(ssw-loop):=20=E5=85=B3=E5=8D=A1=20I=20chec?= =?UTF-8?q?k=5Fclear=5Fcoverage.sh=20=E6=A3=80=E6=B5=8B=20docs=20=E6=AE=8B?= =?UTF-8?q?=E7=95=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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// 引用 ADR 0014 (本回合写): docs/decisions/0014-app-clear-docs-coverage.md --- .../ssw-loop/scripts/check_clear_coverage.sh | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100755 skills/ssw-loop/scripts/check_clear_coverage.sh diff --git a/skills/ssw-loop/scripts/check_clear_coverage.sh b/skills/ssw-loop/scripts/check_clear_coverage.sh new file mode 100755 index 0000000..097a7a4 --- /dev/null +++ b/skills/ssw-loop/scripts/check_clear_coverage.sh @@ -0,0 +1,91 @@ +#!/bin/bash +# 关卡 I (v3.0+): app clear 完整性检查 +# 用法: bash check_clear_coverage.sh [--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 , 例: $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