#!/usr/bin/env bash # ============================================================================== # scripts/check_spec_coverage.sh (skill: ai-collab-framework) # 校验 openspec/changes/ 下每个 chg_* 变更目录(含 archive/ 下带日期前缀的归档项): # - 每个 scenario id 在 spec.md 中以 '### S' 标题行存在 # - 每个 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//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)。 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 [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=. 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= 显式指定。 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:-}" fi echo fi # Use find instead of globbing so this works in both bash and zsh. # '*chg_*' 同时覆盖活动目录 chg_NNNN_ 与归档项 archive/YYYY-MM-DD-chg_NNNN_。 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//spec.md(见 SKILL.md 归档动作)" fi fi # ---- a4 cross-check: map.yaml 的 '# spec: @chg_NNNN' 注释 ---- # 与 spec.md '# Spec: ' 标题对齐;同时 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= 指定基线" 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