- check-scaffold.py: 三条判据从旧模型(sspf 必须声明为 Cargo 依赖)改为方案 C: SC3 应用不声明平台/框架件;SC4 业务包不声明外部依赖; SC5 Cargo.toml 不出现 sspf(平台由 .cargo/config.toml 的 --extern 提供)。 _base_tree 与 VIOLATIONS 同步,反自证仍 6/6。 - fetch-platform.sh: 生成的 .cargo/config.toml 同时写 rustdocflags (cargo test 的 doctest 走 rustdoc,不吃 build.rustflags,之前 E0432)。 - SKILL.md frontmatter description 改为「预编译 rlib / Gitea Release 按 tag+平台取包 / 零重编」。 - Cargo.toml 头部、HOWTO_MODULE、docs/runbook、new-pack/pack-sync 注释同步。 验证:verify.sh 全量 7/7(静态 3 步 + cargo test + release 构建 + 面 A/面 B 各 18 断言)。
387 lines
14 KiB
Python
Executable File
387 lines
14 KiB
Python
Executable File
#!/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:MODS\n"
|
||
"// >>>GEN:SPECS\n// <<<GEN:SPECS\n"
|
||
"// >>>GEN:ROUTES\n// <<<GEN:ROUTES\n"
|
||
"// >>>GEN:MENUS\n// <<<GEN:MENUS\n"
|
||
"// >>>GEN:ROUTER\n// <<<GEN:ROUTER\n",
|
||
)
|
||
_mk(
|
||
root,
|
||
"src/backend/src/modules/demo.rs",
|
||
"pub use sspf_pack_demo::DEMO_SPEC;\npub const ROUTES: [&str; 1] = [\"/x\"];\n",
|
||
)
|
||
_mk(
|
||
root,
|
||
"src/backend/src/packs_gen.rs",
|
||
"// >>>GEN:PACKS\n// <<<GEN:PACKS\n// >>>GEN:MANIFESTS\n// <<<GEN:MANIFESTS\n",
|
||
)
|
||
_mk(
|
||
root,
|
||
"src/backend/Cargo.toml",
|
||
'[package]\nname = "app"\nversion = "0.0.0"\n[dependencies]\n'
|
||
"# >>>GEN:PACK_DEPS\n# <<<GEN:PACK_DEPS\n",
|
||
)
|
||
subprocess.run(
|
||
[sys.executable, os.path.join(HERE, "pack-sync.py")],
|
||
capture_output=True,
|
||
text=True,
|
||
cwd=root,
|
||
env=dict(os.environ, PACK_SYNC_ROOT=os.path.abspath(root)),
|
||
check=True,
|
||
)
|
||
|
||
|
||
VIOLATIONS = {
|
||
# code: (注入动作, 期望变红的判据)
|
||
"SC1": (lambda r: _mk(r, "src/backend/src/platform/mod.rs", "// 抄回来的平台\n"), "SC1"),
|
||
"SC2": (
|
||
lambda r: _mk(r, "packs/demo/schema/002_bad.sql", "CREATE TABLE base_user (f_id text);\n"),
|
||
"SC2",
|
||
),
|
||
"SC3": (lambda r: _add_dep(r, "src/backend/Cargo.toml", "sspf-core", "{ workspace = true }"), "SC3"),
|
||
"SC4": (lambda r: _add_dep(r, "packs/demo/Cargo.toml", "axum", '"0.8"'), "SC4"),
|
||
"SC5": (
|
||
lambda r: _mk(
|
||
r,
|
||
"Cargo.toml",
|
||
'[workspace]\nmembers = ["src/backend", "packs/demo"]\n'
|
||
'[workspace.dependencies]\nsspf = { path = "../ssw-platform/crates/sspf" }\n',
|
||
),
|
||
"SC5",
|
||
),
|
||
# 改 `pack.toml` 的名字 ⇒ `packs_gen.rs` 的 JSON 快照与真源漂移
|
||
"SC6": (
|
||
lambda r: _mk(r, "packs/demo/pack.toml", '[pack]\napp_code = "demo"\nname = "改过的名字"\n'),
|
||
"SC6",
|
||
),
|
||
}
|
||
|
||
|
||
def _add_dep(root, rel, name, spec):
|
||
path = os.path.join(root, rel)
|
||
with open(path, encoding="utf-8") as f:
|
||
text = f.read()
|
||
with open(path, "w", encoding="utf-8") as f:
|
||
f.write(text + f"\n{name} = {spec}\n")
|
||
|
||
|
||
def self_test():
|
||
"""每条判据造一个**真实违规**,必须红;否则这条尺子是瞎的。"""
|
||
ok = 0
|
||
for code, (inject, expect) in VIOLATIONS.items():
|
||
tmp = tempfile.mkdtemp(prefix=f"scaf-{code}-")
|
||
try:
|
||
_base_tree(tmp)
|
||
# 基线必须全绿(否则「注入后变红」不能证明是注入导致的)
|
||
if not run(tmp, f"基线 {code}"):
|
||
print(f" ❌ 反自证 {code}:基线不是全绿,注入无意义")
|
||
continue
|
||
inject(tmp)
|
||
results = {c: fn(tmp)[0] for c, _, fn in CHECKS}
|
||
if results.get(expect) is False:
|
||
ok += 1
|
||
print(f" ✅ 反自证 {code}:注入违规 ⇒ {expect} 变红")
|
||
else:
|
||
print(f" ❌ 反自证 {code}:注入违规但 {expect} 仍绿(尺子瞎了)")
|
||
finally:
|
||
shutil.rmtree(tmp, ignore_errors=True)
|
||
print(f"── 反自证:{ok}/{len(VIOLATIONS)}")
|
||
return ok == len(VIOLATIONS)
|
||
|
||
|
||
def main(argv):
|
||
if "--self-test" in argv:
|
||
return 0 if self_test() else 1
|
||
if argv:
|
||
print(__doc__)
|
||
return 2
|
||
print("== check-scaffold:本仓只准有业务 ==")
|
||
return 0 if run(ROOT, "主跑") else 1
|
||
|
||
|
||
if __name__ == "__main__":
|
||
sys.exit(main(sys.argv[1:]))
|