Files
ssw-jnpf-lite-rust/scripts/check-citations.sh
T
adminandClaude Code 96594df72f feat(repo): 平台层/业务层分离收尾 + 六道闸门(把「尺子」变成机器)
**影响**
后端从「平台层里塞业务知识」改成「装配根 + 业务层自带 spec/菜单/路由」;闸门 5 道 → 6 道,
契约尺子 2 条 → 3 条;两把尺子**默认自起隔离后端** ⇒ 不用先起后端就能冒烟(CI 可跑)。
单测 220 passed / 0 failed;静态闸门 93 + 11 + 10 + 4 全绿;面 A 32/32、面 B 18/18 全绿。

**改动**
- 后端:新增 `platform/guard.rs`(生产档弱口令守卫六条判据 + 配置级/库内级两道检查)、
  `platform/menu.rs`(菜单 spec 的类型)、`bootstrap.rs`(装配根:唯一同时认识平台层与业务层的地方);
  业务模块的菜单与路由下沉到 `modules/<app>.rs`,平台层只 `merge(modules::router())` 一次。
- 闸门:新增 `check-boundary.sh`(分层红线 CP1–CP6)、`check-contract.sh`(契约端点表 + 官方端点台账
  ↔ 代码真实路由,CC2–CC10)、`check-citations.sh`(文档引文 `路径:行号` 逐条核对);
  `check-module.sh` 改为从契约期望值派生(63 → 93 条);三把尺子各带反自证用例。
- 契约:`docs/contract.md` 附录 A 扩成机器可读区段(`[ENDPOINT]` / `[FACE]` / `[OFFICIAL]` / `[RULER]` …)
  ⇒ 六把尺子的期望值只有一处;`[OFFICIAL]` 官方端点台账 53 行四态 ⇒ 覆盖 **8/47**(算出来的)。
- 尺子:`scripts/smoke_backend.sh` 让两把契约尺子默认自起隔离后端(显式给了 `B` ⇒ 不自起、不可达即退出码 2)。
- 文档:CLAUDE.md / SKILL.md / README.md / HANDOFF.md / HOWTO_MODULE.md / docs/* 同步到新结构与新闸门;
  裁决 96 → 98 条(P91 尺子自起设计、P92 官方端点覆盖账本)。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 11:33:25 +08:00

151 lines
5.4 KiB
Bash
Raw 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
# ssw-jnpf-lite-rust 引文校验尺子 —— 文档里的「路径:行号」是否还指得到真东西
#
# 目的:本仓的文档(SKILL / README / MIGRATION / JNPF_SOURCE_AUDIT / PERMISSION …)
# 大量引用源码位置 `文件.ext:行号`。这些行号**会漂移**:源码改一行 ⇒
# 上游行号整体位移 ⇒ 文档里的引用**静默指向别的行**——不报错,只是悄悄说错话。
# 本尺子把每条引文**解析到真实文件**并核对行号区间;顺带核对
# 「文档里的 DDL 行号表 ↔ 官方 DDL 真实行」。
#
# 🔴 **纯静态**:不启动后端、不发请求、不连库。只需要 `python3`(macOS 自带)。
#
# 用法:
# bash scripts/check-citations.sh # 无参 ⇒ 全查
# bash scripts/check-citations.sh --list # 顺带打印每条引文明细
# bash scripts/check-citations.sh --help
#
# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错或前置错误
#
# ── 判据(CIT1–CIT3)──
# CIT1 引文**可解析**:每条 `路径:行号` 都能定位到真实文件
# CIT2 引文**行号有效**:行号区间落在该文件的行数范围内
# CIT3 **DDL 行号表**对账:文档写的建表行号 ↔ 官方 DDL 那一行真的有 `CREATE TABLE`
# CIT1' **反自证**:注入已知坏引用 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子)
#
# 🔴 **期望值来自 `docs/contract.md` 附录 A 的 `[RULER]`**(条数由契约钉死)。
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
SCRIPTS="$ROOT/scripts"
SCAN="$SCRIPTS/check-citations-scan.py"
CE_PY="$SCRIPTS/contract_expect.py"
CONTRACT="$ROOT/docs/contract.md"
usage() {
echo "用法: bash scripts/check-citations.sh [--list]"
echo " 静态校验文档里的「路径:行号」引文是否还指得到真东西"
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错或前置错误"
}
LIST=""
while [ "$#" -gt 0 ]; do
case "$1" in
-h|--help) usage; exit 0 ;;
--list) LIST="--list"; shift ;;
*) echo "❌ 未知参数: $1"; usage; exit 2 ;;
esac
done
# ---- 前置:python3 / 扫描器 / 契约文件 ----
PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}"
if [ -z "${PY_BIN}" ]; then
echo "❌ 找不到 python3(扫描器需要它)"
exit 2
fi
if [ ! -f "${SCAN}" ]; then
echo "❌ 缺扫描器: ${SCAN}"
exit 2
fi
if [ ! -f "${CE_PY}" ] || [ ! -f "${CONTRACT}" ]; then
echo "❌ 缺契约期望值读取器或契约文件(docs/contract.md 附录 A)"
exit 2
fi
# ---- 契约期望值(唯一真源:docs/contract.md 附录 A)----
CE_RULER_ROWS="$("${PY_BIN}" "${CE_PY}" rows RULER 2>/dev/null)" || CE_RULER_ROWS=""
if [ -z "${CE_RULER_ROWS}" ]; then
echo "❌ 读契约期望值失败(docs/contract.md 附录 A 是不是被改坏了?)"
exit 2
fi
CE_EXP_ASSERTIONS="$(printf '%s\n' "${CE_RULER_ROWS}" | awk -F'\t' '$1=="check-citations.sh" { print $2; exit }')"
PASS=0; FAIL=0
ok() { echo " ✅ $1"; PASS=$((PASS+1)); }
no() { echo " ❌ $1"; FAIL=$((FAIL+1)); }
skip(){ echo " ⏭ $1"; PASS=$((PASS+1)); } # 外部参照根缺失 ⇒ 跳过但仍计入条数
hdr() { echo; echo "── $1 ──"; }
# ---- 跑扫描器 ----
SCAN_OUT="$("${PY_BIN}" "${SCAN}" --root "${ROOT}" ${LIST} 2>&1)"
SCAN_RC=$?
if [ "${SCAN_RC}" -eq 2 ]; then
echo "❌ 扫描器前置失败:"
printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /'
exit 2
fi
hdr "[CIT1–CIT3] 文档引文(路径:行号)逐条核对"
DRIFT_LINES=""
while IFS=$'\t' read -r kind f1 f2 f3; do
[ -z "${kind:-}" ] && continue
case "${kind}" in
CHECK)
case "${f2}" in
OK) ok "${f1}:${f3}" ;;
SKIP) skip "${f1}:${f3}" ;;
*) no "${f1}:${f3}" ;;
esac
;;
WARN)
# WARN 行只有 3 列(kind / id / 说明)⇒ 说明在 f2
if [ -n "${f3:-}" ]; then
DRIFT_LINES="${DRIFT_LINES}${f1}:${f3}"$'\n'
else
DRIFT_LINES="${DRIFT_LINES}${f1}:${f2}"$'\n'
fi
;;
esac
done <<< "${SCAN_OUT}"
if [ -n "${DRIFT_LINES}" ]; then
hdr "提示"
printf '%s' "${DRIFT_LINES}" | sed 's/^/ ⚠️ /'
fi
# ---- CIT1' 反自证:尺子自己必须能抓到坏引用 ----
hdr "[CIT1'] 扫描器反自证(--self-test 必须过)"
SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)"
if [ "$?" -eq 0 ]; then
ok "扫描器自证通过:${SELFTEST_OUT}"
else
no "扫描器自证失败:${SELFTEST_OUT}"
fi
# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 --------
hdr "[自证] 尺子条数与契约登记一致"
if [ -n "${CE_EXP_ASSERTIONS}" ]; then
CE_ACT_ASSERTIONS=$((PASS + FAIL))
if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then
echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条"
else
echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)"
FAIL=$((FAIL + 1))
fi
else
echo " ❌ 契约 [RULER] 里没有登记 check-citations.sh 的期望条数"
FAIL=$((FAIL + 1))
fi
# -------- 总结 --------
echo
echo "── 总结 ──"
echo "PASS=${PASS} FAIL=${FAIL}"
if [ "${FAIL}" -eq 0 ]; then
echo "全 ✅ 文档引文没漂移"
else
echo "有 ❌,请按上面修复(改文档里的行号 ⇒ 跟着源码一起改)"
fi
exit $([ "${FAIL}" -eq 0 ] && echo 0 || echo 1)