Files
ssw-platform/scripts/check-citations.sh
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +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-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)