#!/usr/bin/env bash # ssw-platform 引文校验尺子 —— 文档里的「路径:行号」是否还指得到真东西 # # 目的:本仓的文档(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)