- 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]>
582 lines
26 KiB
Bash
Executable File
582 lines
26 KiB
Bash
Executable File
#!/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
|