#!/usr/bin/env python3 # -*- coding: utf-8 -*- """check-scaffold —— 本仓「只是业务仓」的静态判据。 🔴 **为什么需要它**(2026-11-04 改造后): 平台实现已经搬到**已发布的 `sspf` 包**。如果没人钉住,最常见的退化是 「平台某段代码被顺手抄回业务仓」—— 抄回来的那一刻两份实现就开始分叉, 而且**不会报错**:抄来的那份能编译、能跑,只是从此升级平台升不动了。 所以本仓的判据不是「平台对不对」(那在平台仓),而是: **本仓只准有业务**。 | # | 判据 | 违反的典型表现 | |---|---|---| | SC1 | 没有平台实现目录(`platform/` / `routes.rs` / `crates/` / `db/schema.sql`) | 把平台源码抄回来 | | SC2 | 没有 `base_*` 建表语句 | 业务包/应用自建平台表 | | SC3 | 应用 crate 不声明平台/框架件(`sspf`/`axum`/`tokio`/… 全走 `--extern`) | 声明 `sspf-core` / `sspf` / `axum` 等,破坏 rlib 同源 | | SC4 | 每个业务包不声明外部依赖,且目录齐全 | 包里去连库 / 缺 `pack.toml` | | SC5 | `Cargo.toml` 里不出现 `sspf`(平台由 `.cargo/config.toml` 的 `--extern` 提供) | 有人又把 `sspf` 写成 path/git/version 依赖 | | SC6 | 生成物与 `packs/*` 不漂移 | 加包没跑 `pack-sync.py` | 用法: python3 scripts/check-scaffold.py # 主跑(SC1–SC6) python3 scripts/check-scaffold.py --self-test # 反自证:每条尺子造一个违规,必须红 退出码:0 = 全绿 / 1 = 有判据红 / 2 = 前置错误 """ import os import shutil import subprocess import sys import tempfile import tomllib HERE = os.path.dirname(os.path.abspath(__file__)) ROOT = os.path.dirname(HERE) # ---------------------------------------------------------------- 判据 def sc1_no_vendored_platform(root): """本仓不得出现平台实现的目录 / 文件。""" forbidden = [ "src/backend/src/platform", "src/backend/src/routes.rs", "src/backend/src/bootstrap.rs", "src/backend/db/schema.sql", "crates", ] hits = [p for p in forbidden if os.path.exists(os.path.join(root, p))] if hits: return False, "本仓出现平台实现:" + ", ".join(hits) + "(平台在 `sspf` 包里)" return True, "没有 platform/ / routes.rs / crates/ / db/schema.sql" def _iter_sources(root): for dirpath, dirnames, filenames in os.walk(root): dirnames[:] = [ d for d in dirnames if d not in ( ".git", "target", "node_modules", "dist", ".run", ".logs", ".tmp", "__pycache__", # 🔴 `docs/` 是**说明实物**(平台 DDL 的参考副本,给人读的), # 不是会被执行的建表语句 —— 判据只看业务代码 / 业务 DDL。 "docs", ) ] for fn in filenames: if fn.endswith((".rs", ".sql")): yield os.path.join(dirpath, fn) def sc2_no_base_tables(root): """业务侧不得建 `base_*` 平台表(DDL 归平台包管)。""" hits = [] for path in _iter_sources(root): try: with open(path, encoding="utf-8", errors="ignore") as f: text = f.read().lower() except OSError: continue # 只看「建表」语境:CREATE TABLE [IF NOT EXISTS] base_xxx idx = 0 while True: i = text.find("create table", idx) if i < 0: break tail = text[i : i + 120] if "base_" in tail: hits.append(os.path.relpath(path, root)) break idx = i + 1 if hits: return False, "出现 base_* 建表语句:" + ", ".join(sorted(set(hits))) return True, "业务侧没有 base_* 建表语句" def _deps(toml_path): with open(toml_path, "rb") as f: data = tomllib.load(f) return data.get("dependencies", {}) or {} # 方案 C(2026-11-05):下面这些全部由平台包 lib/ 经 `.cargo/config.toml` 的 `--extern` # 提供;一旦在 Cargo.toml 再声明一份,就是「同名 crate 两个实例」→ 跨 sspf API 边界 E0308。 _EXTERN_ONLY = ( "sspf", "axum", "tokio", "serde", "serde_json", "http", "bytes", "ssw-platform", "pglite-rs", "aes", "ecb", "md-5", ) def sc3_app_only_needs_facade(root): """应用 crate 只依赖业务包;平台/框架件一律走 .cargo/config.toml 的 --extern。""" path = os.path.join(root, "src/backend/Cargo.toml") if not os.path.isfile(path): return False, "找不到 src/backend/Cargo.toml" deps = _deps(path) # `sspf-pack-*` 是本仓自己的业务包(合法);其余平台拆件/框架件都不许声明。 bad = [ k for k in deps if k in _EXTERN_ONLY or (k.startswith("sspf-") and not k.startswith("sspf-pack-")) ] if bad: return False, "应用 crate 声明了平台/框架件(应由 .cargo/config.toml --extern 提供):" + ", ".join(sorted(bad)) return True, "应用 crate 只依赖业务包(平台/框架件走 --extern)" def sc4_packs_are_thin(root): """每个业务包不声明外部依赖(`sspf` 走 --extern),且四件套齐全。""" packs_dir = os.path.join(root, "packs") if not os.path.isdir(packs_dir): return False, "没有 packs/(示例业务包在哪?)" apps = sorted( d for d in os.listdir(packs_dir) if os.path.isdir(os.path.join(packs_dir, d)) ) if not apps: return False, "packs/ 下没有任何包" problems = [] for app in apps: base = os.path.join(packs_dir, app) for rel in ("Cargo.toml", "pack.toml", "src/lib.rs", "schema/001_init.sql"): if not os.path.isfile(os.path.join(base, rel)): problems.append(f"packs/{app} 缺 {rel}") cargo = os.path.join(base, "Cargo.toml") if os.path.isfile(cargo): deps = _deps(cargo) if deps: problems.append( f"packs/{app} 声明了依赖(应留空,平台/框架件走 --extern):{', '.join(sorted(deps))}" ) if problems: return False, ";".join(problems) return True, f"{len(apps)} 个包都不声明外部依赖,目录齐全" def sc5_no_sspf_in_cargo(root): """`Cargo.toml` 里不得出现 `sspf`:平台由 `.cargo/config.toml` 的 `--extern` 提供。""" ws = os.path.join(root, "Cargo.toml") with open(ws, "rb") as f: data = tomllib.load(f) wdeps = (data.get("workspace", {}) or {}).get("dependencies", {}) or {} if "sspf" in wdeps: return False, "workspace.dependencies 仍声明了 `sspf`(方案 C 应由 .cargo/config.toml 的 --extern 提供)" offenders = [] for member in ("src/backend/Cargo.toml",): path = os.path.join(root, member) if os.path.isfile(path) and "sspf" in _deps(path): offenders.append(member) if offenders: return False, "成员声明了 `sspf`(应由 .cargo/config.toml 的 --extern 提供):" + ", ".join(offenders) # 若已生成 config,顺手校验它确实喂了 sspf(没生成不算错:verify 可在 fetch 之前跑) cfg = os.path.join(root, ".cargo/config.toml") if os.path.isfile(cfg): text = open(cfg, encoding="utf-8", errors="ignore").read() if "sspf=" not in text or "dependency=" not in text: return False, ".cargo/config.toml 里没有 `--extern sspf=…` + `-L dependency=…`(重跑 scripts/fetch-platform.sh)" return True, "平台经 .cargo/config.toml 的 --extern 提供(Cargo.toml 未声明 sspf)" return True, "Cargo.toml 未声明 sspf(构建前先跑 scripts/fetch-platform.sh 生成 .cargo/config.toml)" def sc6_generated_files_in_sync(root): """生成物与 `packs/*` 不漂移(复用 pack-sync 的 --check)。""" script = os.path.join(HERE, "pack-sync.py") env = dict(os.environ, PACK_SYNC_ROOT=os.path.abspath(root)) proc = subprocess.run( [sys.executable, script, "--check"], capture_output=True, text=True, cwd=root, env=env, ) out = (proc.stdout + proc.stderr).strip().splitlines() detail = out[-1] if out else "(无输出)" return proc.returncode == 0, detail CHECKS = [ ("SC1", "本仓没有平台实现", sc1_no_vendored_platform), ("SC2", "业务侧不建 base_* 表", sc2_no_base_tables), ("SC3", "应用不声明平台/框架件", sc3_app_only_needs_facade), ("SC4", "业务包不声明外部依赖", sc4_packs_are_thin), ("SC5", "Cargo.toml 不出现 sspf", sc5_no_sspf_in_cargo), ("SC6", "生成物无漂移", sc6_generated_files_in_sync), ] # ---------------------------------------------------------------- 主跑 def run(root, label=""): ok_n = 0 for code, name, fn in CHECKS: passed, detail = fn(root) if passed: ok_n += 1 print(f" ✅ {code} {name} —— {detail}") else: print(f" ❌ {code} {name} —— {detail}") print(f"── {label}:PASS={ok_n} FAIL={len(CHECKS) - ok_n}") return ok_n == len(CHECKS) # ---------------------------------------------------------------- 反自证 def _mk(root, rel, content=""): path = os.path.join(root, rel) os.makedirs(os.path.dirname(path), exist_ok=True) with open(path, "w", encoding="utf-8") as f: f.write(content) def _base_tree(root): """造一棵**最小合法**的树(六条判据都绿),再逐条注入违规。""" _mk( root, "Cargo.toml", '[workspace]\nmembers = ["src/backend", "packs/demo"]\n', ) # 方案 C:平台经 .cargo/config.toml 的 --extern 提供(不再写进 Cargo.toml) _mk( root, ".cargo/config.toml", '[build]\nrustflags = [\n' ' "--extern", "sspf=/tmp/lib/libsspf-x.rlib",\n' ' "-L", "dependency=/tmp/lib",\n' ']\n', ) _mk( root, "src/backend/Cargo.toml", '[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n', ) _mk(root, "src/backend/src/lib.rs", "// app\n") _mk( root, "packs/demo/Cargo.toml", '[package]\nname = "sspf-pack-demo"\nversion = "0.0.0"\n[dependencies]\n', ) _mk(root, "packs/demo/pack.toml", '[pack]\napp_code = "demo"\n') _mk(root, "packs/demo/src/lib.rs", "// pack\n") _mk(root, "packs/demo/schema/001_init.sql", "CREATE TABLE IF NOT EXISTS demo_item (f_id text);\n") # 生成物:直接让 pack-sync 写一遍(它认 packs/* 与 modules/*) _mk( root, "src/backend/src/modules/mod.rs", "// >>>GEN:MODS\n// <<>>GEN:SPECS\n// <<>>GEN:ROUTES\n// <<>>GEN:MENUS\n// <<>>GEN:ROUTER\n// <<>>GEN:PACKS\n// <<>>GEN:MANIFESTS\n// <<>>GEN:PACK_DEPS\n# <<