Files
dth/openspec/scripts/check_spec_coverage.sh
xstudio agent c1cf6f54e5 merge sandbox/ai-1790562657-0EF743: chg_0001 dth scaffold + chg_0002 experiment_platform MVP
- chg_0001_dth_scaffold (skip_coverage): openspec framework + NestJS+React+PGlite scaffold
- chg_0002_sp1_experiment_platform_mvp: 6 scenarios S1-S6 + 21 perm-smoke + 16 e2e + 3 demo operators (hello-mpc/pir/vertical-lr)

Sandbox task exit 0. Independent verification: check_spec_coverage.sh gap=0 PASS.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-09-28 10:54:34 +08:00

582 lines
26 KiB
Bash
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env bash
# ==============================================================================
# scripts/check_spec_coverage.sh (skill: ai-collab-framework)
# 校验 openspec/changes/ 下每个 chg_* 变更目录(含 archive/ 下带日期前缀的归档项):
# - 每个 scenario id 在 spec.md 中以 '### S<n>' 标题行存在
# - 每个 case id 在 testcases.md 中存在
# - 每个 case 的 Bound Task 在 tasks.md 中存在(反向校验)
# - spec.md 结构校验(借鉴 OpenSpec delta 约定):
# * 含 '## ADDED/MODIFIED/REMOVED Scenarios' 任一段即进入 delta 模式,
# 所有 S 块必须归属某个 delta 段(不允许散落在其他段下)
# * ADDED/MODIFIED/全量模式下的场景块必须非空壳(至少一条 **WHEN** 与 **THEN**)
# * REMOVED 块必须带 Reason 与 Migration
# * 与 openspec/specs/<capability>/spec.md 交叉核对:
# ADDED 的 id 不得已存在;MODIFIED/REMOVED 的 id 必须已存在;
# 主 spec 不存在时(新 capability)只允许 ADDED
# - proposal.md frontmatter 'skip_coverage: true' 豁免整个 chg
# (纯 refactor/docs/tooling 等不改行为的变更;勿为过门禁编造场景)
# - 每条 src/ 改动落在 implementation_files 白名单内
# (需要目标项目是 git 仓库;否则显式 WARN,不静默放行)
# 退出码:0 = pass;非 0 = 阻塞
#
# 用法:PROJECT_ROOT=<项目路径> bash scripts/check_spec_coverage.sh [--json]
# (PROJECT_ROOT 默认取当前目录;脚本可以放在技能包里,不必在项目内)
# --json:机器消费模式。stdout 输出单一 JSON document;文本输出全部抑制;
# 退码语义不变(0 = pass, 1 = fail)。错误信封采用 OpenSpec 风格
# `{ status: [{severity, code, message, fix?}] }`(仅在有 failure 时出现)。
# 默认模式 stdout 字节级不变(保护 `set -e` CI 消费者)。
# 回归自测:bash scripts/selftest_check_spec_coverage.sh (改本脚本后必跑)
# ==============================================================================
set -euo pipefail
# ---- 参数解析(必须在 source parse.sh 之前;JSON_MODE 影响后续行为)----
JSON_MODE=0
for arg in "$@"; do
case "$arg" in
--json) JSON_MODE=1 ;;
-h|--help)
sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
exit 0
;;
*)
echo "FAIL: 未知参数 '$arg'(仅支持 --json / --help)" >&2
exit 2
;;
esac
done
# ---- 公共解析器(scripts/lib/parse.sh)----
# 改 parse.sh 里的解析函数前请跑 selftest_check_spec_coverage.sh 验证 gate 默认行为不变。
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# shellcheck source=lib/parse.sh
. "$SCRIPT_DIR/lib/parse.sh"
# ---- JSON 累积器(仅 JSON_MODE=1 时填充)----
# 每个 chg 累积为一个 JSON object(字符串),终态用 jq 合并。
# 字段:name / status / failure_count / warning_count / failures / warnings
JSON_CHG_ENTRIES=""
# 全局 findings 数组(cross-chg 共享;信封失败时也归入)
JSON_FINDINGS=""
# json_quote: 把字符串安全嵌入 JSON。\n / " / \ 处理;其余原样。
# 不追求 RFC 7159 全部边界——只覆盖本脚本实际出现的字符(中英文 / 路径 / S<n>)。
json_quote() {
local s="$1"
s=${s//\\/\\\\}
s=${s//\"/\\\"}
s=${s// /\\t}
# 多行字串:把换行替换为字面 \n(让 jq 解析成单行 JSON value)
s=${s//$'\n'/\\n}
printf '"%s"' "$s"
}
# json_record_failure <code> <message> <fix?> [change_name]
# 同时累积到当前 chg(如果给定 change_name)和全局 findings。
json_record_failure() {
local code="$1" msg="$2" fix="${3:-}" chg="${4:-}"
local fix_json="null"
[ -n "$fix" ] && fix_json=$(json_quote "$fix")
local entry
entry=$(printf '{"severity":"error","code":%s,"message":%s,"fix":%s}' \
"$(json_quote "$code")" "$(json_quote "$msg")" "$fix_json")
if [ -n "$chg" ]; then
JSON_CHG_FAILURES="${JSON_CHG_FAILURES:+$JSON_CHG_FAILURES,}$entry"
fi
JSON_FINDINGS="${JSON_FINDINGS:+$JSON_FINDINGS,}$entry"
}
json_record_warning() {
local code="$1" msg="$2" chg="${3:-}"
local entry
entry=$(printf '{"severity":"warning","code":%s,"message":%s}' \
"$(json_quote "$code")" "$(json_quote "$msg")")
if [ -n "$chg" ]; then
JSON_CHG_WARNINGS="${JSON_CHG_WARNINGS:+$JSON_CHG_WARNINGS,}$entry"
fi
JSON_FINDINGS="${JSON_FINDINGS:+$JSON_FINDINGS,}$entry"
}
# ROOT: the project that uses this skill (NOT the skill's own location).
# Default: current working directory. Override with PROJECT_ROOT=<path>.
ROOT="${PROJECT_ROOT:-$(pwd)}"
CHANGES_DIR="$ROOT/openspec/changes"
EXIT=0
# implementation_files 白名单校验依赖 git。先判定环境能力,缺什么就 WARN 什么,
# 不允许静默不生效(无 git 仓库时白名单曾完全不起作用且无任何提示)。
GIT_OK=0
if git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1; then
GIT_OK=1
fi
# base 分支:让「本 chg 已 commit 的 src/ 改动」也纳入比对。
# 可用 SPEC_COVERAGE_BASE=<ref> 显式指定。
BASE_REF=""
if [ "$GIT_OK" = "1" ]; then
BASE_REF="${SPEC_COVERAGE_BASE:-}"
if [ -z "$BASE_REF" ]; then
for cand in origin/main origin/master main master; do
if git -C "$ROOT" rev-parse --verify -q "$cand" >/dev/null 2>&1; then
BASE_REF="$cand"
break
fi
done
fi
fi
# ---- 输出层 ----
# 文本模式:emit = echo(行为与 v2.4.0 字节级一致)
# JSON 模式:emit 不打印,仅把结构化数据累积到 JSON_CHG_ENTRIES;终态输出单一 JSON
# 唯一的差异是 JSON 模式下文本输出完全抑制。
if [ "$JSON_MODE" = "0" ]; then
echo "==[ check_spec_coverage ]================================="
echo "ROOT: $ROOT"
if [ "$GIT_OK" = "1" ]; then
echo "git: base=${BASE_REF:-<none, 只比对未提交改动>}"
fi
echo
fi
# Use find instead of globbing so this works in both bash and zsh.
# '*chg_*' 同时覆盖活动目录 chg_NNNN_<slug> 与归档项 archive/YYYY-MM-DD-chg_NNNN_<slug>。
while IFS= read -r d; do
[ -d "$d" ] || continue
MAP="$d/testcases.map.yaml"
SPEC="$d/spec.md"
TC="$d/testcases.md"
TASKS="$d/tasks.md"
PROPOSAL="$d/proposal.md"
CHG_FAIL=0
# 归档项只校验自身结构完整性;与主 spec 的指向核对(ADDED 不得已在/REMOVED 必须在)
# 只对活动 chg 做——归档时 delta 已合并进主 spec,再核对必然误报。
IS_ARCH=0
case "$d" in */archive/*) IS_ARCH=1 ;; esac
CHG_NAME=$(basename "$d")
JSON_CHG_FAILURES=""
JSON_CHG_WARNINGS=""
if [ "$JSON_MODE" = "0" ]; then
echo "── change: $CHG_NAME"
fi
# skip 豁免(借鉴 OpenSpec skip_specs):声明非行为变更则整个 chg 不再要求工件。
# 豁免标记只能写在 proposal.md 里——proposal 本身仍必需。
if grep -qE '^skip_coverage:[[:space:]]*true' "$PROPOSAL" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " SKIP proposal.md 声明 skip_coverage: true(非行为变更豁免),其余工件不校验"
fi
# JSON 模式:记录 SKIP 状态
if [ "$JSON_MODE" = "1" ]; then
entry=$(printf '{"name":%s,"status":"SKIP","failures":[],"warnings":[]}' \
"$(json_quote "$CHG_NAME")")
JSON_CHG_ENTRIES="${JSON_CHG_ENTRIES:+$JSON_CHG_ENTRIES,}$entry"
fi
continue
fi
# Required files(tasks.md 纳入必需:Bound Task 反向校验以它为基准)
for f in "$PROPOSAL" "$SPEC" "$TC" "$TASKS" "$MAP"; do
if [ ! -f "$f" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL MISSING: $f"
fi
json_record_failure "MISSING_FILE" "required file missing: $f" "建工件后重跑门禁" "$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
done
[ ! -f "$MAP" ] && continue
# 注意:set -o pipefail 下「grep 无匹配」会让整条管道非 0,
# 不加 `|| true` 时脚本会中途静默退出(既不报错也不继续检查后续 chg)。
SCEN_IDS=$(grep -oE 'id:[[:space:]]*[A-Za-z0-9_]+' "$MAP" 2>/dev/null | awk '{print $2}' | sort -u || true)
CASE_IDS=$(grep -oE 'cases:[[:space:]]*\[[^]]*\]' "$MAP" 2>/dev/null \
| grep -oE 'C[0-9]+_[A-Za-z0-9_]+' | sort -u || true)
N_SCEN=$(echo $SCEN_IDS | wc -w | xargs)
N_CASE=$(echo $CASE_IDS | wc -w | xargs)
if [ "$JSON_MODE" = "0" ]; then
echo " scenarios: $N_SCEN"
echo " cases: $N_CASE"
fi
# 防空跑:解析不到内容说明 map.yaml 结构不符合约定,此时必须 FAIL 而不是静默放行
if [ "$N_SCEN" = "0" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL map.yaml 未解析出任何 scenario(需要形如 'id: S1' 的行): $MAP"
fi
json_record_failure "MAP_EMPTY_SCENARIOS" \
"map.yaml 未解析出任何 scenario(需要形如 'id: S1' 的行): $MAP" \
"在 map.yaml scenarios: 段为每个场景写 'id: Sn' 行" "$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
if [ "$N_CASE" = "0" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL map.yaml 未解析出任何 case(需要形如 'cases: [C1_xxx]' 的行): $MAP"
fi
json_record_failure "MAP_EMPTY_CASES" \
"map.yaml 未解析出任何 case(需要形如 'cases: [C1_xxx]' 的行): $MAP" \
"在 map.yaml scenarios: 段为每条 case 写 'cases: [C1_xxx]' 列表" "$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
for sid in $SCEN_IDS; do
if ! grep -qE "^###[[:space:]]+${sid}([[:space:]]|:|$)" "$SPEC" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL scenario $sid NOT in $SPEC"
echo " spec.md 需含字面标题行 '### $sid' 或 '### $sid <场景名>'(门禁按标题匹配)"
echo " 「$sid/6 同 xxx」这类缩写合并写法不被识别,请逐场景写出标题"
fi
json_record_failure "SCENARIO_NOT_IN_SPEC" \
"scenario $sid NOT in $SPEC" \
"spec.md 需含字面标题行 '### $sid' 或 '### $sid <场景名>'(门禁按标题匹配)" \
"$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
done
for cid in $CASE_IDS; do
if ! grep -qF "$cid" "$TC" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL case $cid NOT in $TC"
fi
json_record_failure "CASE_NOT_IN_TESTCASES" \
"case $cid NOT in $TC" \
"在 testcases.md 写 '### $cid' 标题 + 至少一条用例" "$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
done
# 反向校验:testcases.md 里的 Bound Task 必须真实存在于 tasks.md
BT_IDS=$(grep -oE 'Bound Task:[[:space:]]*T[0-9]+' "$TC" 2>/dev/null | grep -oE 'T[0-9]+' | sort -u || true)
for t in $BT_IDS; do
if ! grep -qE "id:[[:space:]]*${t}([^0-9A-Za-z_]|$)" "$TASKS" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL Bound Task $t (referenced in $TC) NOT in $TASKS"
fi
json_record_failure "BOUND_TASK_NOT_IN_TASKS" \
"Bound Task $t (referenced in $TC) NOT in $TASKS" \
"在 tasks.md 写 'id: $t' 行,或修改 testcases.md 的 'Bound Task: $t' 指向真实任务" \
"$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
done
# ---- spec.md 结构校验(delta 模式 / 空壳 / REMOVED 完整性 / 主 spec 交叉核对)----
DELTA_MODE=0
if grep -qE '^##[[:space:]]+(ADDED|MODIFIED|REMOVED)[[:space:]]+Scenarios' "$SPEC" 2>/dev/null; then
DELTA_MODE=1
fi
ADDED_IDS=""; MOD_IDS=""; REM_IDS=""
S_BLOCKS=$(extract_s_blocks "$SPEC")
while IFS=$'\t' read -r sid kind flag1 flag2; do
[ -z "$sid" ] && continue
if [ "$DELTA_MODE" = "1" ] && [ "$kind" = "PLAIN" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL scenario $sid 散落在 delta 段之外(delta 模式下每个 S 块必须位于"
echo " '## ADDED|MODIFIED|REMOVED Scenarios' 三个段落之一)"
fi
json_record_failure "SCENARIO_OUTSIDE_DELTA" \
"scenario $sid 散落在 delta 段之外(delta 模式下每个 S 块必须位于 '## ADDED|MODIFIED|REMOVED Scenarios' 三个段落之一)" \
"把 $sid 移到对应的 delta 段下" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
case "${flag1:-}" in
NO-WHEN|NO-THEN|NO-REASON|NO-MIGRATION)
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL scenario $sid ($kind) 块不完整:缺 ${flag1#NO-}"
case "${flag2:-}" in
NO-*) echo " 同时缺 ${flag2#NO-}" ;;
esac
if [ "$kind" = "REMOVED" ]; then
echo " REMOVED 块需含 **Reason** 与 **Migration** 两行"
else
echo " 场景块至少需各一条 '- **WHEN**' 与 '- **THEN**'(空壳场景不放行)"
fi
fi
# 错误信息合并:flag1/flag2 一起;fix 提示根据 kind 分支
local_fix="在 $sid 场景块下加 '- **WHEN**' 与 '- **THEN**' 各一条(REMOVED 块需 **Reason** 与 **Migration**)"
json_record_failure "INCOMPLETE_SCENARIO_BLOCK" \
"scenario $sid ($kind) 块不完整:缺 ${flag1#NO-}${flag2:+; 同时缺 ${flag2#NO-}}" \
"$local_fix" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
;;
esac
case "$kind" in
ADDED) ADDED_IDS="$ADDED_IDS $sid" ;;
MODIFIED) MOD_IDS="$MOD_IDS $sid" ;;
REMOVED) REM_IDS="$REM_IDS $sid" ;;
esac
done <<< "$S_BLOCKS"
if [ "$DELTA_MODE" = "1" ] && [ "$IS_ARCH" = "0" ]; then
CAP=$(grep -m1 '^# Spec:' "$SPEC" 2>/dev/null | sed -E 's/^#[[:space:]]*Spec:[[:space:]]*//; s/[[:space:]]+$//' || true)
if [ -n "$CAP" ] && [ "${CAP#*<}" = "$CAP" ]; then
MAIN="$ROOT/openspec/specs/$CAP/spec.md"
if [ ! -f "$MAIN" ]; then
if [ -n "${MOD_IDS// /}" ] || [ -n "${REM_IDS// /}" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL spec 声明了 MODIFIED/REMOVED,但主 spec 不存在: $MAIN"
echo " 新 capability 只允许 ADDED;或确认 '# Spec:' 行的名称与 openspec/specs/ 目录一致"
fi
json_record_failure "DELTA_BUT_NO_MAIN_SPEC" \
"spec 声明了 MODIFIED/REMOVED,但主 spec 不存在: $MAIN" \
"新 capability 只允许 ADDED;或确认 '# Spec:' 行的名称与 openspec/specs/ 目录一致" \
"$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
else
for sid in $ADDED_IDS; do
if grep -qE "^###[[:space:]]+${sid}([[:space:]]|:|$)" "$MAIN" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL ADDED scenario $sid 已存在于主 spec(${MAIN})——应改为 MODIFIED 并整块拷贝"
fi
json_record_failure "ADDED_ALREADY_EXISTS" \
"ADDED scenario $sid 已存在于主 spec(${MAIN})" \
"应改为 MODIFIED 并整块拷贝" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
done
for sid in $MOD_IDS; do
if ! grep -qE "^###[[:space:]]+${sid}([[:space:]]|:|$)" "$MAIN" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL MODIFIED 目标 $sid 不在主 spec(${MAIN})中——MODIFIED 必须指向已存在的场景"
fi
json_record_failure "MODIFIED_NOT_IN_MAIN" \
"MODIFIED 目标 $sid 不在主 spec(${MAIN})中" \
"MODIFIED 必须指向已存在的场景,或修正场景 id" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
done
for sid in $REM_IDS; do
if ! grep -qE "^###[[:space:]]+${sid}([[:space:]]|:|$)" "$MAIN" 2>/dev/null; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL REMOVED 目标 $sid 不在主 spec(${MAIN})中——REMOVED 必须指向已存在的场景"
fi
json_record_failure "REMOVED_NOT_IN_MAIN" \
"REMOVED 目标 $sid 不在主 spec(${MAIN})中" \
"REMOVED 必须指向已存在的场景,或修正场景 id" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
done
fi
fi
else
if [ "$JSON_MODE" = "0" ]; then
echo " note: 全量 spec(旧式)。新 chg 建议改用 '## ADDED/MODIFIED/REMOVED Scenarios' delta 段,"
echo " 归档时按标记合并进 openspec/specs/<capability>/spec.md(见 SKILL.md 归档动作)"
fi
fi
# ---- a4 cross-check: map.yaml 的 '# spec: <capability>@chg_NNNN' 注释 ----
# 与 spec.md '# Spec: <capability>' 标题对齐;同时 chg_NNNN 与目录 basename 对齐。
# 注释缺失不阻塞(保持向后兼容——老 fixture 没填注释;新 chg 应照模板写注释)。
# 双方都写了但不一致 = FAIL(jxcj 实跑教训:comment 是纯装饰时两处写歪没人发现)。
SPEC_CAP=$(grep -m1 '^# Spec:' "$SPEC" 2>/dev/null | sed -E 's/^#[[:space:]]*Spec:[[:space:]]*//; s/[[:space:]]+$//' || true)
MAP_SPEC_LINE=$(grep -m1 -E '^[[:space:]]*#[[:space:]]*spec:[[:space:]]*[^[:space:]]+@chg_[0-9]+' "$MAP" 2>/dev/null || true)
if [ -n "$MAP_SPEC_LINE" ] && [ -n "$SPEC_CAP" ]; then
MAP_CAP=$(printf '%s\n' "$MAP_SPEC_LINE" | sed -E 's/.*spec:[[:space:]]*([^@[:space:]]+)@.*/\1/')
MAP_CHG=$(printf '%s\n' "$MAP_SPEC_LINE" | sed -E 's/.*@chg_([0-9]+).*/chg_\1/')
# 占位符(<...>)跳过 capability 比对——模板原文/未替换的 chg 不应判 FAIL。
# chg_NNNN 与目录对齐仍查(学用临时值也会被检出)。
if [[ "$MAP_CAP" != *"<"* ]] && [[ "$MAP_CAP" != *">"* ]] && [ "$MAP_CAP" != "$SPEC_CAP" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL map.yaml '# spec: $MAP_CAP@...' 与 spec.md '# Spec: $SPEC_CAP' capability 不一致"
echo " 两处 capability 名要对齐;chg 改一处时另一处也要改"
fi
json_record_failure "CAPABILITY_COMMENT_MISMATCH" \
"map.yaml '# spec: $MAP_CAP@...' 与 spec.md '# Spec: $SPEC_CAP' capability 不一致" \
"两处 capability 名要对齐;chg 改一处时另一处也要改" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
fi
DIR_CHG=$(basename "$d")
case "$DIR_CHG" in
${MAP_CHG}_*|archive/*-${MAP_CHG}_*) ;;
*)
if [ "$JSON_MODE" = "0" ]; then
echo " FAIL map.yaml 注释 chg id '$MAP_CHG' 与目录 basename '$DIR_CHG' 不一致"
fi
json_record_failure "CHG_ID_COMMENT_MISMATCH" \
"map.yaml 注释 chg id '$MAP_CHG' 与目录 basename '$DIR_CHG' 不一致" \
"把 map.yaml '# spec: ...@$MAP_CHG' 改为当前目录对应的 chg_NNNN" "$CHG_NAME"
EXIT=1; CHG_FAIL=1
;;
esac
fi
# ---- implementation_files 走白名单 ----
# 把白名单条目直接当 git pathspec 用(不再硬编 src/);这样 monorepo/非根 src/
# 布局(backend/src/、packages/foo/src/ 等)也能真实生效(jxcj 实跑教训:
# 'git diff -- src/' 只匹配仓库根 src/,monorepo 下等于没查、且不 WARN)。
# 解析规则:在 'implementation_files:' 之后取 yaml 列表项(' - path'),
# 跳过空行、行末注释、缩进错位。
IMPL_PATHS=()
while IFS= read -r p; do
[ -n "$p" ] && IMPL_PATHS+=("$p")
done < <(awk '
/implementation_files:/ { in_block = 1; next }
in_block && /^[[:space:]]*-[[:space:]]*/ {
line = $0
sub(/^[[:space:]]*-[[:space:]]*/, "", line)
sub(/[[:space:]]*#.*$/, "", line)
sub(/[[:space:]]+$/, "", line)
if (line != "") print line
next
}
in_block && /^[[:space:]]*[A-Za-z_]/ { in_block = 0 }
' "$MAP" 2>/dev/null)
if [ "${#IMPL_PATHS[@]}" -gt 0 ]; then
if [ "$GIT_OK" = "0" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " WARN $ROOT 不是 git 仓库,implementation_files 白名单未参与校验(门禁未生效,非通过)"
echo " 跑 'git init && git add -A && git commit -m init' 后重跑本脚本以启用"
fi
json_record_warning "IMPL_FILES_NO_GIT" \
"$ROOT 不是 git 仓库,implementation_files 白名单未参与校验(门禁未生效,非通过)" \
"$CHG_NAME"
else
# 未提交改动 + 相对 base 分支已提交的改动都算(只看 diff HEAD 会漏掉已 commit 的越界改动)
# 把白名单条目作为 pathspec 喂给 git:每个条目独立 arg(不再硬编 src/)
SRC_CHANGES=$(
{ git -C "$ROOT" diff --name-only HEAD "${IMPL_PATHS[@]}" 2>/dev/null || true
if [ -n "$BASE_REF" ]; then
git -C "$ROOT" diff --name-only "$BASE_REF"...HEAD "${IMPL_PATHS[@]}" 2>/dev/null || true
fi
} | sort -u
)
if [ -z "$BASE_REF" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " WARN 未找到 base 分支 (main/master),只比对了未提交的 src/ 改动"
echo " 已 commit 的越界改动不会被查到;可用 SPEC_COVERAGE_BASE=<ref> 指定基线"
fi
json_record_warning "NO_BASE_REF" \
"未找到 base 分支 (main/master),只比对了未提交的 src/ 改动" \
"$CHG_NAME"
fi
# 友好提示(不阻塞):白名单全以 src/ 开头但仓库根无 src/ 目录——
# 这正是历史上 monorepo 静默失效的入口;现在 pathspec 已按 entries 真实查找,
# 但作者可能漏掉了真实子目录(如 backend/src/)。
if printf '%s\n' "${IMPL_PATHS[@]}" | grep -q '^src/' && [ ! -d "$ROOT/src" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " note 白名单条目以 src/ 开头但 $ROOT 下无 src/ 目录(monorepo?)。"
echo " 把条目改为真实子路径(如 backend/src/)以避免歧义。门禁按条目路径生效,不阻塞。"
fi
fi
for path in $SRC_CHANGES; do
ok=0
for allowed in "${IMPL_PATHS[@]}"; do
if [[ "$path" == "$allowed"* ]]; then ok=1; break; fi
done
if [ "$ok" = "0" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " WARN out-of-scope src change: $path"
fi
json_record_failure "OUT_OF_SCOPE_SRC" \
"out-of-scope src change: $path" \
"把改动移到 implementation_files 白名单内,或扩展白名单" "$CHG_NAME"
EXIT=1
CHG_FAIL=1
fi
done
fi
fi
if [ "$CHG_FAIL" = "0" ]; then
if [ "$JSON_MODE" = "0" ]; then
echo " OK"
fi
fi
# JSON 模式:把当前 chg 的累积结果作为一个 entry 入数组
if [ "$JSON_MODE" = "1" ]; then
CHG_STATUS="PASS"
[ "$CHG_FAIL" = "1" ] && CHG_STATUS="FAIL"
if grep -qE '^skip_coverage:[[:space:]]*true' "$PROPOSAL" 2>/dev/null; then
CHG_STATUS="SKIP"
fi
entry=$(printf '{"name":%s,"status":"%s","failures":[%s],"warnings":[%s]}' \
"$(json_quote "$CHG_NAME")" "$CHG_STATUS" \
"${JSON_CHG_FAILURES:-}" "${JSON_CHG_WARNINGS:-}")
JSON_CHG_ENTRIES="${JSON_CHG_ENTRIES:+$JSON_CHG_ENTRIES,}$entry"
fi
done < <(find "$CHANGES_DIR" -mindepth 1 -maxdepth 2 -type d -name '*chg_*' | sort)
# ---- 终态输出 ----
if [ "$JSON_MODE" = "0" ]; then
echo
if [ "$EXIT" = "0" ]; then
echo "==[ PASS ]== spec coverage gap = 0"
else
echo "==[ FAIL ]== see FAIL above; merge blocked"
fi
exit $EXIT
fi
# JSON 模式:构建单一 JSON document
# 字段:root / changes[] / summary{pass,fail,skip,findings} / status[] (envelope, 仅失败时)
# 计数策略:让 jq 数真值(`length` 算数组元素数),不在 bash 里用 grep 数逗号分隔符。
# 退化路径(无 jq)才用 grep 兜底。jq 调用是对自身中间输出做计算——jq 不存在时 jq 退 127,
# 也用 { || true; } 兜住,避免 set -e 终止。
if command -v jq >/dev/null 2>&1; then
PASS_CT=$(jq -nc --argjson a "[$JSON_CHG_ENTRIES]" '[ $a[] | select(.status=="PASS") ] | length')
FAIL_CT=$(jq -nc --argjson a "[$JSON_CHG_ENTRIES]" '[ $a[] | select(.status=="FAIL") ] | length')
SKIP_CT=$(jq -nc --argjson a "[$JSON_CHG_ENTRIES]" '[ $a[] | select(.status=="SKIP") ] | length')
if [ -n "$JSON_FINDINGS" ]; then
FINDING_CT=$(jq -nc --argjson a "[$JSON_FINDINGS]" '$a | length')
else
FINDING_CT=0
fi
TOTAL=$(jq -nc --argjson a "[$JSON_CHG_ENTRIES]" '$a | length')
else
# 无 jq 兜底:grep -c 数行(仅用于多 chg 计数;findings 数省略)
PASS_CT=$(printf '%s' "$JSON_CHG_ENTRIES" | { grep -oE '"status":"PASS"' || true; } | wc -l | xargs)
FAIL_CT=$(printf '%s' "$JSON_CHG_ENTRIES" | { grep -oE '"status":"FAIL"' || true; } | wc -l | xargs)
SKIP_CT=$(printf '%s' "$JSON_CHG_ENTRIES" | { grep -oE '"status":"SKIP"' || true; } | wc -l | xargs)
if [ -n "$JSON_FINDINGS" ]; then
FINDING_CT=$(printf '%s' "$JSON_FINDINGS" | { grep -oE '^\{' || true; } | wc -l | xargs)
else
FINDING_CT=0
fi
TOTAL=$((PASS_CT + FAIL_CT + SKIP_CT))
fi
# 用 jq 合并输出(如果系统无 jq,回退到 printf 拼接——后者仍能产出合法 JSON)
if command -v jq >/dev/null 2>&1; then
if [ "$EXIT" = "0" ]; then
jq -nc \
--arg root "$ROOT" \
--argjson changes "[$JSON_CHG_ENTRIES]" \
--argjson pass "$PASS_CT" \
--argjson fail "$FAIL_CT" \
--argjson skip "$SKIP_CT" \
--argjson findings_count "$FINDING_CT" \
'{root: $root, summary: {pass: $pass, fail: $fail, skip: $skip, findings: $findings_count}, changes: $changes}'
else
jq -nc \
--arg root "$ROOT" \
--argjson changes "[$JSON_CHG_ENTRIES]" \
--argjson status "[$JSON_FINDINGS]" \
--argjson pass "$PASS_CT" \
--argjson fail "$FAIL_CT" \
--argjson skip "$SKIP_CT" \
--argjson findings_count "$FINDING_CT" \
'{root: $root, status: $status, summary: {pass: $pass, fail: $fail, skip: $skip, findings: $findings_count}, changes: $changes}'
fi
else
# 无 jq 回退(仅用于无 jq 环境,CI 一般有 jq)
if [ "$EXIT" = "0" ]; then
printf '{"root":"%s","summary":{"pass":%s,"fail":%s,"skip":%s,"findings":%s},"changes":[%s]}\n' \
"$ROOT" "$PASS_CT" "$FAIL_CT" "$SKIP_CT" "$FINDING_CT" "$JSON_CHG_ENTRIES"
else
printf '{"root":"%s","status":[%s],"summary":{"pass":%s,"fail":%s,"skip":%s,"findings":%s},"changes":[%s]}\n' \
"$ROOT" "$JSON_FINDINGS" "$PASS_CT" "$FAIL_CT" "$SKIP_CT" "$FINDING_CT" "$JSON_CHG_ENTRIES"
fi
fi
exit $EXIT