Files
admin d8a8165dd7 fix(skill): 自检/文档同步到方案 C(SC3/SC4/SC5 + rustdocflags + description)
- 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 断言)。
2026-11-05 13:54:52 +08:00

387 lines
14 KiB
Python
Executable File
Raw Permalink 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 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:]))