- 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/:前端接口清单、页面依赖反查、运行时探针
151 lines
5.4 KiB
Bash
151 lines
5.4 KiB
Bash
#!/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)
|