Files
ssw-platform/scripts/check-contract.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

169 lines
6.2 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 契约对账尺子 —— `docs/contract.md` ↔ 代码里的真实路由
#
# 目的:把「契约文档」和「代码」这两份**独立**的真相**对账**。
# 契约 §6 的端点表原先是**散文表格**,代码里的路由注册是**另一处**
# ⇒ 加端点 / 改路径 / 改守卫 ⇒ 各改各的 ⇒ 漂移没人发现。
# 本尺子把契约附录 A 的 `[ENDPOINT]`(机器可读)与代码里**真实注册**的路由
# **双向**逐条对账:契约多 / 代码多 / 方法不符 / 归属层不符 / 守卫不符。
#
# 🔴 **纯静态**:不启动后端、不发请求。只需要 `python3`(macOS 自带)。
#
# 用法:
# bash scripts/check-contract.sh # 无参 ⇒ 全查
# bash scripts/check-contract.sh --help # 本用法
#
# 退出码:0 全过 / 1 有 ❌ 项 / 2 用法错或前置错误
#
# ── 判据(CC1–CC10)──
# CC2 端点**总数**一致(契约 N 条 == 代码 N 条)
# CC3 契约 → 代码:每条端点在代码里存在且**方法**一致
# CC4 代码 → 契约:代码里没有契约未登记的端点
# CC5 **归属层**一致(platform / 业务模块代号)
# CC6 **守卫**一致(面A 菜单 key / 面B 点权限编码 / 登录 / 无)——静态推导
# CC7 钉子测试的**字面量清单**(REGISTERED / JNPF_REGISTERED)与平台层路由双向覆盖
# CC8 业务路由**三处**一致(各模块 ROUTES 常量 / router() 注册 / ALL_ROUTES)
# CC9 契约面计数**自洽**([FACE] 登记的条数 == [ENDPOINT] 里各 face 的实际条数)
# CC10 **官方端点台账** ↔ 代码真实路由(双向)+ 打印「官方端点覆盖 N/M」
# CC1' **反自证**:注入已知漂移 ⇒ 必须被抓到(永远返回「干净」的尺子 = 没有尺子)
#
# 🔴 **期望值来自 `docs/contract.md` 附录 A**(机器可读)⇒ 改契约只改那一处。
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
SCRIPTS="$ROOT/scripts"
CONTRACT="$ROOT/docs/contract.md"
SRC="$ROOT/src/backend/src"
SCAN="$SCRIPTS/check-contract-scan.py"
CE_PY="$SCRIPTS/contract_expect.py"
usage() {
echo "用法: bash scripts/check-contract.sh"
echo " 纯静态对账「契约端点表 ↔ 代码里真实注册的路由」"
echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错或前置错误"
}
if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
usage
exit 0
fi
if [ "$#" -ne 0 ]; then
echo "❌ 未知参数: ${1}"
usage
exit 2
fi
# ---- 前置: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}" ]; then
echo "❌ 缺契约期望值读取器: ${CE_PY}"
exit 2
fi
if [ ! -f "${CONTRACT}" ]; then
echo "❌ 缺契约文件: ${CONTRACT}"
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-contract.sh" { print $2; exit }')"
PASS=0; FAIL=0
ok() { echo " ✅ $1"; PASS=$((PASS+1)); }
no() { echo " ❌ $1"; FAIL=$((FAIL+1)); }
hdr() { echo; echo "── $1 ──"; }
# ---- 跑扫描器 ----
SCAN_OUT="$("${PY_BIN}" "${SCAN}" --contract "${CONTRACT}" --src "${SRC}" 2>&1)"
SCAN_RC=$?
if [ "${SCAN_RC}" -eq 2 ]; then
echo "❌ 扫描器前置失败(契约读不出来 / 参数错):"
printf '%s\n' "${SCAN_OUT}" | sed 's/^/ /'
exit 2
fi
hdr "[CC2–CC10] 契约端点表 ↔ 代码真实路由 逐条对账"
DRIFT_LINES=""
while IFS=$'\t' read -r kind f1 f2 f3; do
[ -z "${kind:-}" ] && continue
case "${kind}" in
CHECK)
if [ "${f2}" = "OK" ]; then
ok "${f1}:${f3}"
else
no "${f1}:${f3}"
fi
;;
INFO)
# 🔴 进度信息(官方端点覆盖 N/M)—— **不计入** PASS/FAIL
echo " 📊 ${f1}:${f2}"
;;
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
# ---- CC1' 反自证:尺子自己必须能抓到漂移 ----
hdr "[CC1'] 扫描器反自证(--self-test 必须过)"
SELFTEST_OUT="$("${PY_BIN}" "${SCAN}" --self-test 2>&1)"
if [ "$?" -eq 0 ]; then
ok "扫描器自证通过:${SELFTEST_OUT}"
else
no "扫描器自证失败:${SELFTEST_OUT}"
fi
# -------- 尺子自证:跑出来的条数必须等于契约里登记的条数 --------
#
# 🔴 尺子自己知道它断言了几条(PASS+FAIL)。哪天有人删掉几条断言、或者某个分支提前
# return 了,尺子照样「全绿」—— 变弱的尺子比没有尺子更危险 ⇒ 条数由**契约**钉死。
hdr "[自证] 尺子条数与契约登记一致"
if [ -n "${CE_EXP_ASSERTIONS}" ]; then
CE_ACT_ASSERTIONS=$((PASS + FAIL))
if [ "${CE_ACT_ASSERTIONS}" -eq "${CE_EXP_ASSERTIONS}" ]; then
# 自证**不计入** PASS/FAIL(它是元断言,不是业务断言)
echo " ✅ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言 = 契约登记的 ${CE_EXP_ASSERTIONS} 条"
else
echo " ❌ 尺子自证:本尺子跑了 ${CE_ACT_ASSERTIONS} 条断言,契约登记 ${CE_EXP_ASSERTIONS} 条 ⇒ 尺子被改弱了(少了/多了断言)"
FAIL=$((FAIL + 1))
fi
else
echo " ❌ 契约 [RULER] 里没有登记 check-contract.sh 的期望条数"
FAIL=$((FAIL + 1))
fi
# -------- 总结 --------
echo
echo "── 总结 ──"
echo "PASS=${PASS} FAIL=${FAIL}"
if [ "${FAIL}" -eq 0 ]; then
echo "全 ✅ 契约与代码没漂移"
else
echo "有 ❌,请按上面修复(改契约 ⇒ 改 docs/contract.md 附录 A 的 [ENDPOINT])"
fi
exit $([ "${FAIL}" -eq 0 ] && echo 0 || echo 1)