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]>
This commit is contained in:
xstudio agent committed 2026-09-28 10:54:34 +08:00
commit c1cf6f54e5
314 files changed
+55077

No files matched your search

+581
View File
@@ -0,0 +1,581 @@
#!/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