#!/usr/bin/env bash # sspf 架构边界自检 —— crate 依赖纪律 + 内存红线 # # 目的:把 PLAN.md 判断 ②/⑥ 的架构约束变成**可执行的尺子**。 # 靠人读 Cargo.toml 守不住 —— 加依赖的人不会想到「这会让所有业务包背锅」。 # # 🔴 **纯静态**:不编译、不启动。只需要 bash + python3(macOS 自带)。 # # 用法: # bash scripts/check-arch.sh # 全查 # bash scripts/check-arch.sh --self-test # 反自证:造已知违规,必须被抓到 # # 退出码:0 全过 / 1 有 ❌ / 2 用法错 # # ── 判据 ── # AR1 `crates/sspf-sdk` 依赖只能有 `sspf-contract` # —— 业务包只依赖 sdk ⇒ sdk 多一个依赖 = 所有业务包都要背 # AR2 `packs/*/Cargo.toml` 依赖 ⊆ {sspf-sdk, serde} # —— 业务包必须能整目录搬走 ⇒ 不许挂在 axum / tokio / pglite 上 # AR3 `crates/sspf-contract` 源码不许 `use axum|tokio|pglite|sqlx` # —— 契约层一旦有 IO,业务包就再也不是「轻依赖」 # AR4 `crates/sspf-contract` 依赖 ⊆ {serde, serde_json, uuid, http} # AR5 `crates/sspf-mcp`(若已存在)依赖 ⊆ {sspf-contract, serde, serde_json, tokio, async-trait} # —— MCP 层要能同时接「进程内内核」和「远端 Java 后端」⇒ **不许依赖内核内部** # —— tokio / async-trait 是协议实现(stdio 异步读写)所需,不是业务依赖 # AR6 `crates/sspf-adapter-baseline` 依赖 ⊆ {sspf-mcp, sspf-contract, serde, serde_json, # tokio, http, hyper, hyper-util, http-body-util, bytes} # —— 适配器只认工具契约层;依赖内核 store 就等于把第二种后端钉死在本进程旁 # AR7 `crates/sspf-lowcode` 依赖 ⊆ {sspf-contract, serde, serde_json} # —— 低代码引擎是纯计算;依赖 DB/HTTP 会让它只能在内核里跑,且测试必须起库 # MEM1 非注释代码里不许出现 `SELECT *` # —— 终端产品内存预算 ≤ 120MB(PLAN.md 判断 ⑥)⇒ 全表读进 Vec 直接爆 # MEM2 `crates/**` 与 `src/backend/src/platform/**` 里不许出现无界 `HashMap` 缓存 # (近似检查:`static` + `Mutex/dev/null || true)" if [ -z "$hits" ]; then ok "AR3 sspf-contract 无 IO 依赖(无 axum/tokio/pglite/sqlx 的 use)" else bad "AR3 sspf-contract 出现 IO 依赖:" printf '%s\n' "$hits" | sed 's/^/ /' fi } # ---------------------------------------------------------------- AR4 check_ar4() { local f="$CRATES/sspf-contract/Cargo.toml" [ -f "$f" ] || { skip "AR4 sspf-contract 不存在"; return; } local deps; deps="$(deps_of "$f" | tr '\n' ' ')" if subset_of "$deps" "serde serde_json uuid http"; then ok "AR4 sspf-contract 依赖在白名单内([$deps])" else bad "AR4 sspf-contract 依赖越界:[$deps] —— 白名单 serde/serde_json/uuid/http" fi } # ---------------------------------------------------------------- AR5 check_ar5() { local f="$CRATES/sspf-mcp/Cargo.toml" [ -f "$f" ] || { skip "AR5 sspf-mcp 不存在(P1 才落地)"; return; } local deps; deps="$(deps_of "$f" | tr '\n' ' ')" if subset_of "$deps" "sspf-contract serde serde_json tokio async-trait"; then ok "AR5 sspf-mcp 依赖干净([$deps])" else bad "AR5 sspf-mcp 依赖越界:[$deps] —— 只允许 sspf-contract/serde/serde_json/tokio/async-trait" fi } # ---------------------------------------------------------------- AR6 check_ar6() { local f="$CRATES/sspf-adapter-baseline/Cargo.toml" [ -f "$f" ] || { skip "AR6 sspf-adapter-baseline 不存在"; return; } local deps; deps="$(deps_of "$f" | tr '\n' ' ')" # 🔴 适配器只许依赖「工具契约层 + HTTP 客户端」。 # 一旦依赖 sspf-store / axum,第二种后端就只能跑在同一个内核旁边 —— 双轨失效。 if subset_of "$deps" "sspf-mcp sspf-contract serde serde_json tokio http hyper hyper-util http-body-util bytes"; then ok "AR6 sspf-adapter-baseline 依赖干净([$deps])" else bad "AR6 sspf-adapter-baseline 依赖越界:[$deps] —— 只许工具契约层 + HTTP 客户端,不许依赖内核 store" fi } # ---------------------------------------------------------------- AR7 check_ar7() { local f="$CRATES/sspf-lowcode/Cargo.toml" [ -f "$f" ] || { skip "AR7 sspf-lowcode 不存在"; return; } local deps; deps="$(deps_of "$f" | tr '\n' ' ')" # 🔴 低代码引擎必须是**纯计算**:解析 / 校验 / SQL 生成。 # 一旦依赖 pglite / axum,它就只能在内核里跑 —— CLI、MCP、离线校验工具都用不了, # 而且测试必须起数据库(现在 38 个测试 0 依赖、毫秒级)。 if subset_of "$deps" "sspf-contract serde serde_json"; then ok "AR7 sspf-lowcode 依赖干净([$deps])" else bad "AR7 sspf-lowcode 依赖越界:[$deps] —— 只许契约层 + 序列化,不许 DB / HTTP" fi } # ---------------------------------------------------------------- AR8 # 业务包装载器(`crates/sspf-plugin`)的依赖白名单。 # # 🔴 **为什么单列一条**:装载器是「业务包 ⇄ 内核」的唯一中介。 # 它一旦依赖 axum / tokio / pglite,业务包就**间接背上 web 框架**(AR2 的精神废掉), # 而且「包可整目录搬走」这个承诺再也证不了。 # 装载器只做「读清单 + 校验兼容区间 + 收集 entities/menus/routes」⇒ 纯数据。 check_ar8() { local f="$CRATES/sspf-plugin/Cargo.toml" [ -f "$f" ] || { skip "AR8 sspf-plugin 不存在(批次 12 才落地)"; return; } local deps; deps="$(deps_of "$f" | tr '\n' ' ')" if subset_of "$deps" "sspf-sdk sspf-contract serde serde_json"; then ok "AR8 sspf-plugin 依赖干净([$deps])" else bad "AR8 sspf-plugin 依赖越界:[$deps] —— 只允许 sspf-sdk/sspf-contract/serde/serde_json(不许 axum/tokio/pglite)" fi } # ---------------------------------------------------------------- AR9 # **平台层不许认识任何业务包**(业务知识隔离,红线 12)。 # # 🔴 方向是「内核 ⇒ 包」,**不是**「包 ⇒ 内核」:`src/backend/Cargo.toml` 依赖 # `sspf-pack-` 是**允许**的(装配根要装载它们); # 但 `src/backend/src/platform/**` 里出现 `use sspf_pack_*` ⇒ 平台层知道了 # 具体业务 ⇒ 加/删业务包就要改平台层 ⇒ 「链接就好」这个承诺是假的。 check_ar9() { local dir="$KERNEL/src/platform" [ -d "$dir" ] || { skip "AR9 平台层目录不存在"; return; } local hits hits="$(grep -rnE '^[[:space:]]*(pub )?use[[:space:]]+sspf_pack_' "$dir" 2>/dev/null || true)" if [ -z "$hits" ]; then ok "AR9 平台层没有 use sspf_pack_*(业务知识没漏进 platform/)" else bad "AR9 平台层出现了业务包引用(业务知识漏进 platform/ ⇒ 加包要改平台层):" printf '%s\n' "$hits" | sed 's/^/ /' fi } # ---------------------------------------------------------------- PACK1 # **spec 单一真源**:`modules/.rs` 只许做转发,不许自己写 spec。 # # 🔴 背景:批次 12 之前 `modules/asset.rs` 与 `packs/asset/src/lib.rs` 是 # **两份逐字拷贝** ⇒ 改一处忘另一处 ⇒ **静默**不一致,且当时没有任何闸门比对。 # 现在 spec 的真源在包里,模块文件只 `pub use` 转发。 # ⇒ 本闸门要防的是「有人又在模块文件里写了一份」—— # 那等于回到两份拷贝,而且**看起来一切正常**(编译过、测试过)。 # # 判据(对每个「模块文件里有 `pub use sspf_pack_`」的模块): # · 模块文件里**不许**出现 `: EntitySpec =` / `: MenuSpec =` 的定义 # (`pub use` 转发不算定义 —— 它没有 `=` 字面量); # · 与它同 app_code 的包**必须存在**且**确实声明了** EntitySpec(否则转发了个空)。 check_pack1() { local n=0 for mf in "$MODULES_DIR"/*.rs; do [ -f "$mf" ] || continue case "$(basename "$mf")" in mod.rs) continue ;; esac grep -q "pub use sspf_pack_" "$mf" 2>/dev/null || continue n=$((n + 1)) local name; name="$(basename "$mf" .rs)" # ① 模块文件里不许有 spec / menu 的**定义**(`= EntitySpec {` / `= MenuSpec {`) local defs defs="$(grep -nE '=[[:space:]]*(EntitySpec|MenuSpec)[[:space:]]*\{' "$mf" 2>/dev/null || true)" if [ -n "$defs" ]; then bad "PACK1 ${name}.rs 既 re-export 又**自己定义**了 spec(两份拷贝回来了):" printf '%s\n' "$defs" | sed 's/^/ /' continue fi # ② 包必须存在,且真的声明了 EntitySpec local lib="$ROOT/packs/$name/src/lib.rs" if [ ! -f "$lib" ]; then bad "PACK1 ${name}.rs 从 sspf_pack_${name} 转发,但 packs/${name}/src/lib.rs 不存在" continue fi if ! grep -qE ':[[:space:]]*EntitySpec[[:space:]]*=' "$lib" 2>/dev/null; then bad "PACK1 packs/${name}/src/lib.rs 没有 EntitySpec 声明(模块转发了个空)" continue fi ok "PACK1 ${name}.rs 只做 re-export,spec 真源在 packs/${name}/src/lib.rs" done [ "$n" -eq 0 ] && skip "PACK1 尚无「模块转发业务包」的模块" return 0 } # ---------------------------------------------------------------- MEM1 # 只看**代码行**:去掉 `//` 之后的注释、`//!` / `///` 文档注释、以及字符串里的反引号示例。 check_mem1() { local hits hits="$(python3 - "$ROOT" <<'PY' import os, re, sys root = sys.argv[1] pat = re.compile(r'SELECT\s+\*', re.I) bad = [] for base in ('src/backend/src', 'crates'): for dirpath, dirnames, files in os.walk(os.path.join(root, base)): dirnames[:] = [d for d in dirnames if d not in ('target', 'tests', 'data')] for fn in files: if not fn.endswith('.rs'): continue p = os.path.join(dirpath, fn) # 文件名以 _it.rs 结尾的是集成测试,不查 if fn.endswith('_it.rs'): continue try: lines = open(p, encoding='utf-8').read().splitlines() except OSError: continue in_test = False for i, line in enumerate(lines, 1): s = line.strip() if s.startswith('#[cfg(test)]'): in_test = True if in_test: continue code = line.split('//', 1)[0] if pat.search(code): bad.append(f'{p}:{i}: {s}') for b in bad: print(b) PY )" if [ -z "$hits" ]; then ok "MEM1 无非注释的 SELECT *(全表读进 Vec 会直接超内存预算)" else bad "MEM1 发现 SELECT *(终端产品内存预算 ≤120MB,禁止整表载入):" printf '%s\n' "$hits" | sed 's/^/ /' fi } # ---------------------------------------------------------------- MEM2 # 近似检查:出现 `Mutex "$tmp/Cargo.toml" <<'TOML' [package] name = "arch-selftest" version = "0.0.0" edition = "2021" [dependencies] sspf-sdk = { path = "../../crates/sspf-sdk" } axum = "0.8" TOML local before=$FAIL check_ar2 >/dev/null 2>&1 local caught=0 [ "$FAIL" -gt "$before" ] && caught=1 rm -rf "$tmp" FAIL=$before if [ "$caught" -eq 1 ]; then echo "✅ 反自证通过:AR2 抓到了 axum 依赖" else echo "❌ 反自证失败:AR2 没抓到明显违规 ⇒ 这把尺子是假的" rc=1 fi echo "── 反自证 2/4:往平台层塞一个 use sspf_pack_*,AR9 必须报 ❌ ──" # # 🔴 **为什么必须自证 AR9**:它的判据是 `grep platform/`。 # 目录名写错 / 路径拼错 ⇒ `grep` 永远返回空 ⇒ **永远"通过"**。 # 这类尺子比没有更危险(它给出虚假的安全感)。 local probe="$KERNEL/src/platform/__ar9_selftest.rs" if [ -d "$KERNEL/src/platform" ]; then printf 'use sspf_pack_asset::DATA_RESOURCE_SPEC;\n' > "$probe" before=$FAIL check_ar9 >/dev/null 2>&1 caught=0 [ "$FAIL" -gt "$before" ] && caught=1 rm -f "$probe" FAIL=$before if [ "$caught" -eq 1 ]; then echo "✅ 反自证通过:AR9 抓到了平台层里的 use sspf_pack_*" else echo "❌ 反自证失败:AR9 没抓到平台层里的业务包引用 ⇒ 尺子是假的" rc=1 fi else echo "⏭ 跳过 AR9 反自证(平台层目录不存在)" fi echo "── 反自证 3/4:往 re-export 的模块里塞一份 spec,PACK1 必须报 ❌ ──" # # 🔴 造在**临时模块文件**上(不动真文件):只要它同时有 `pub use sspf_pack_` # 和 `= EntitySpec {`,PACK1 就必须红。 local mprobe="$MODULES_DIR/__pack1_selftest.rs" if [ -d "$MODULES_DIR" ]; then cat > "$mprobe" <<'RS' pub use sspf_pack_asset::DATA_RESOURCE_SPEC; pub const DUP_SPEC: EntitySpec = EntitySpec { entity: "Dup", table: "dup", .. }; RS before=$FAIL check_pack1 >/dev/null 2>&1 caught=0 [ "$FAIL" -gt "$before" ] && caught=1 rm -f "$mprobe" FAIL=$before if [ "$caught" -eq 1 ]; then echo "✅ 反自证通过:PACK1 抓到了「既 re-export 又自己定义 spec」" else echo "❌ 反自证失败:PACK1 没抓到两份拷贝 ⇒ 尺子是假的" rc=1 fi else echo "⏭ 跳过 PACK1 反自证(业务模块目录不存在)" fi echo "── 反自证 4/4:往 sspf-plugin 塞 axum 依赖,AR8 必须报 ❌ ──" local pfile="$CRATES/sspf-plugin/Cargo.toml" if [ -f "$pfile" ]; then cp "$pfile" "$pfile.bak" printf 'axum = "0.8"\n' >> "$pfile" before=$FAIL check_ar8 >/dev/null 2>&1 caught=0 [ "$FAIL" -gt "$before" ] && caught=1 mv "$pfile.bak" "$pfile" FAIL=$before if [ "$caught" -eq 1 ]; then echo "✅ 反自证通过:AR8 抓到了装载器里的 axum 依赖" else echo "❌ 反自证失败:AR8 没抓到装载器里的 axum ⇒ 尺子是假的" rc=1 fi else echo "⏭ 跳过 AR8 反自证(sspf-plugin 不存在)" fi return $rc } # ---------------------------------------------------------------- main [ "${1:-}" = "--help" ] && { usage; exit 0; } echo "── 架构边界闸门(crate 依赖纪律 + 内存红线)──" check_ar1 check_ar2 check_ar3 check_ar4 check_ar5 check_ar6 check_ar7 check_ar8 check_ar9 check_pack1 check_mem1 check_mem2 echo printf '结果: %d 通过 / %d 失败 / %d 跳过\n' "$PASS" "$FAIL" "$SKIP" if [ "${1:-}" = "--self-test" ]; then echo self_test || exit 1 fi [ "$FAIL" -eq 0 ] || exit 1 exit 0