#!/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 / FACE_B_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)