Files
ssw-jnpf-lite-rust/scripts/pack-sync.py
T
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

362 lines
13 KiB
Python
Executable File
Raw 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 -*-
"""pack-sync —— 把业务包声明同步到所有「派生位置」。
🔴 **为什么存在**:加一个业务包要改四处**派生位置**,其中两处漏了**不报错**:
| # | 派生位置 | 内容 | 漏了会怎样 |
|---|---|---|---|
| ① | `src/backend/src/packs_gen.rs` 的 `>>>GEN:PACKS` | `load_static` 调用 | 面 B 端点**静默 404** |
| ② | `src/backend/src/packs_gen.rs` 的 `>>>GEN:MANIFESTS` | `pack.toml` 的 JSON 快照 | 装载失败 / 清单与真源不一致 |
| ③ | `src/backend/src/modules/mod.rs` 五个生成段 | `pub mod` / `ALL_SPECS` / `ALL_ROUTES` / `ALL_MENUS` / `router()` | 面 A **静默 404** + 菜单不种 ⇒ 守卫查不到 |
| ④ | `src/backend/Cargo.toml` 的 `# >>>GEN:PACK_DEPS` | 每个包的 path 依赖 | 编译报错(响亮) |
⇒ 全部由本脚本从 **`packs/*/pack.toml` + `modules/*.rs`** 生成;
`--check` 在「改了包没跑生成」时**红**,不要让漂移活到运行时。
🔴 **真源**:
- 表 DDL / 列 / 菜单 / 面 B 路由 ⇒ `packs/<app>/`(业务包,不声明外部依赖,走 --extern)
- 面 A 适配器 / spec 转发 ⇒ `src/backend/src/modules/<app>.rs`
用法:
python3 scripts/pack-sync.py # 同步(幂等)
python3 scripts/pack-sync.py --check # 只检查(不写)⇒ 有漂移就退出 1
python3 scripts/pack-sync.py --dry-run # 打印将要写入的内容
退出码:0 = 成功 / 1 = --check 发现漂移 / 2 = 用法错或前置错误
"""
import json
import os
import re
import sys
import tomllib
HERE = os.path.dirname(os.path.abspath(__file__))
# 🔴 `PACK_SYNC_ROOT` 只给**反自证**用(`check-scaffold.py --self-test` 在临时树里跑)——
# 缺了它,「生成物漂移」这条尺子就只能检查真实仓库 ⇒ 自证会假绿。
ROOT = os.environ.get("PACK_SYNC_ROOT") or os.path.dirname(HERE)
PACKS_DIR = os.path.join(ROOT, "packs")
MODULES_DIR = os.path.join(ROOT, "src/backend/src/modules")
PACKS_GEN = os.path.join(ROOT, "src/backend/src/packs_gen.rs")
MOD_RS = os.path.join(MODULES_DIR, "mod.rs")
APP_CARGO = os.path.join(ROOT, "src/backend/Cargo.toml")
class SyncError(Exception):
"""前置错误(不是漂移)⇒ 退出码 2。"""
# ---------------------------------------------------------------- 读取真源
def read_packs():
"""`packs/*/pack.toml` ⇒ {app: manifest dict}(按 app 字典序)。"""
if not os.path.isdir(PACKS_DIR):
raise SyncError(f"没有 {PACKS_DIR}(业务包目录)")
out = {}
for name in sorted(os.listdir(PACKS_DIR)):
path = os.path.join(PACKS_DIR, name, "pack.toml")
if not os.path.isfile(path):
continue
with open(path, "rb") as f:
data = tomllib.load(f)
pack = data.get("pack")
if not pack:
raise SyncError(f"{path} 缺 [pack] 段")
app = pack.get("app_code")
if app != name:
raise SyncError(f"{path} 的 app_code={app!r} 与目录名 {name!r} 不一致")
out[app] = pack
if not out:
raise SyncError(f"{PACKS_DIR} 下没有任何包(pack.toml)")
return out
MODULE_SPEC_RE = re.compile(r"pub use sspf_pack_[a-z0-9_]+::([A-Z0-9_]+_SPEC);")
MODULE_MENU_RE = re.compile(r"pub use sspf_pack_[a-z0-9_]+::([A-Z0-9_]+_MENU);")
MODULE_ROUTES_RE = re.compile(r"pub const ROUTES: \[&str; (\d+)\]")
def read_modules():
"""`modules/*.rs`(除 mod.rs)⇒ {app: {spec, menu, routes}}。"""
if not os.path.isdir(MODULES_DIR):
raise SyncError(f"没有 {MODULES_DIR}")
out = {}
for fn in sorted(os.listdir(MODULES_DIR)):
if not fn.endswith(".rs") or fn == "mod.rs":
continue
app = fn[: -len(".rs")]
with open(os.path.join(MODULES_DIR, fn), encoding="utf-8") as f:
src = f.read()
spec = MODULE_SPEC_RE.search(src)
if not spec:
raise SyncError(
f"modules/{fn} 里找不到 `pub use sspf_pack_{app}::<X>_SPEC;`"
"(面 A 适配器必须转发包的 spec,不许自己重写一份)"
)
menu = MODULE_MENU_RE.search(src)
routes = MODULE_ROUTES_RE.search(src)
if not routes:
raise SyncError(f"modules/{fn} 里找不到 `pub const ROUTES: [&str; N]`")
out[app] = {
"spec": spec.group(1),
"menu": menu.group(1) if menu else None,
"routes": int(routes.group(1)),
}
if not out:
raise SyncError(f"{MODULES_DIR} 下没有任何业务模块")
return out
def cross_check(packs, mods):
"""包与适配器必须一一对应(两边各少一个都是错的)。"""
only_pack = sorted(set(packs) - set(mods))
only_mod = sorted(set(mods) - set(packs))
if only_pack:
raise SyncError(
"这些包没有面 A 适配器:"
+ ", ".join(only_pack)
+ "(跑 `bash scripts/new-pack.sh` 补齐,或删掉该包)"
)
if only_mod:
raise SyncError(
"这些模块没有对应的包:"
+ ", ".join(only_mod)
+ "(业务真源在 `packs/<app>/`,模块只是适配器)"
)
# ---------------------------------------------------------------- 渲染
def gen_manifest_json(pack):
"""`pack.toml` ⇒ 装载器认的 JSON 快照(只取内核需要的字段)。"""
tables = [
{
"name": t["name"],
"ddl": t.get("ddl", ""),
"baseline_table": t.get("baseline_table", t["name"]),
}
for t in pack.get("tables", [])
]
doc = {
"pack": {
"app_code": pack["app_code"],
"name": pack.get("name", pack["app_code"]),
"version": pack.get("version", "1.0.0"),
"kernel": pack.get("kernel", ""),
"migratable": bool(pack.get("migratable", True)),
"tables": tables,
}
}
return json.dumps(doc, ensure_ascii=False, indent=2)
def const_prefix(app):
return app.upper().replace("-", "_")
def gen_pack_calls(packs):
out = []
for app in sorted(packs):
crate = "sspf-pack-" + app
out.append(f" // ---- {app} ----")
out.append(" regs.push(load_static(")
out.append(f' "{app}",')
out.append(f" {const_prefix(app)}_MANIFEST_JSON,")
out.append(f" Box::new({crate.replace('-', '_')}::Pack),")
out.append(f" {crate.replace('-', '_')}::DDLS,")
out.append(" kernel_version,")
out.append(" )?);")
out.append("")
return "\n".join(out).rstrip("\n")
def gen_manifests(packs):
out = []
for app in sorted(packs):
out.append(f"/// `packs/{app}/pack.toml` 的编译期快照。")
out.append(f'const {const_prefix(app)}_MANIFEST_JSON: &str = r#"{gen_manifest_json(packs[app])}"#;')
out.append("")
return "\n".join(out).rstrip("\n")
def gen_mods(mods):
return "\n".join(f"pub mod {app};" for app in sorted(mods))
def gen_specs(mods):
body = "\n".join(f" {app}::{mods[app]['spec']}," for app in sorted(mods))
return (
"/// 全部业务实体 spec。\n"
"///\n"
"/// 🔴 **本段由 `scripts/pack-sync.py` 生成** —— 加模块不用手改(见文件头)。\n"
"pub const ALL_SPECS: &[EntitySpec] = &[\n"
f"{body}\n"
"];"
)
def gen_routes(mods):
lines = []
for app in sorted(mods):
lines.extend(f" {app}::ROUTES[{i}]," for i in range(mods[app]["routes"]))
body = "\n".join(lines)
return (
"/// **全部业务路由**(面 A:`/api/ssw/{appCode}/{Entity}/{动作}`,每模块 3 条)。\n"
"///\n"
"/// 🔴 **与 `ALL_SPECS` 同序**(同一份模块清单生成)⇒ 可以按 3 条一组配对。\n"
"pub const ALL_ROUTES: &[&str] = &[\n"
f"{body}\n"
"];"
)
def gen_menus(mods):
lines = []
for app in sorted(mods):
if mods[app]["menu"]:
lines.append(f" {app}::{mods[app]['menu']},")
body = "\n".join(lines)
return (
"/// 全部业务内置菜单(**给人看的快照**)。\n"
"///\n"
"/// 🔴 真正种进库的是 `packs/*` 里 `BusinessPack::menus()` 的那一份\n"
"/// (`sspf::Platform::packs(reg)` 把 `PackRegistry.menus` 直接带进两段式种子)。\n"
"/// **不要再把本数组传给 `.menus()`** —— 同一份菜单给两次,种子 INSERT 会撞主键。\n"
"/// 这里留着是给测试 / 排障一个稳定的、不依赖装载流程的清单。\n"
"pub const ALL_MENUS: &[MenuSpec] = &[\n"
f"{body}\n"
"];"
)
def gen_router(mods):
apps = sorted(mods)
body = f" {apps[0]}::router()"
for app in apps[1:]:
body += f"\n .merge({app}::router())"
return (
"/// **全部业务模块的路由**(面 A,`Router::merge` 进平台装配链)。\n"
"///\n"
"/// 🔴 加业务模块 ⇒ **不用改这里**(本段由 `pack-sync.py` 生成)。\n"
"pub fn router() -> Router<AppState> {\n"
f"{body}\n"
"}"
)
def gen_pack_deps(packs):
return "\n".join(
f'sspf-pack-{app} = {{ path = "../../packs/{app}" }}' for app in sorted(packs)
)
# ---------------------------------------------------------------- 写回
def replace_region(text, begin, end, body, where):
"""把 `begin`/`end` 标记**之间**的内容换成 body(标记本身保留)。"""
i = text.find(begin)
j = text.find(end)
if i < 0 or j < 0 or j < i:
raise SyncError(f"{where} 里找不到生成段标记 {begin} / {end}")
head = text[: i + len(begin)]
tail = text[j:]
return head + "\n" + body + "\n" + tail
def build_outputs(packs, mods):
with open(PACKS_GEN, encoding="utf-8") as f:
packs_gen = f.read()
with open(MOD_RS, encoding="utf-8") as f:
mod_rs = f.read()
with open(APP_CARGO, encoding="utf-8") as f:
app_cargo = f.read()
new_packs_gen = replace_region(
packs_gen,
"// >>>GEN:PACKS",
"// <<<GEN:PACKS",
gen_pack_calls(packs),
PACKS_GEN,
)
new_packs_gen = replace_region(
new_packs_gen,
"// >>>GEN:MANIFESTS",
"// <<<GEN:MANIFESTS",
gen_manifests(packs),
PACKS_GEN,
)
new_mod = replace_region(mod_rs, "// >>>GEN:MODS", "// <<<GEN:MODS", gen_mods(mods), MOD_RS)
new_mod = replace_region(new_mod, "// >>>GEN:SPECS", "// <<<GEN:SPECS", gen_specs(mods), MOD_RS)
new_mod = replace_region(new_mod, "// >>>GEN:ROUTES", "// <<<GEN:ROUTES", gen_routes(mods), MOD_RS)
new_mod = replace_region(new_mod, "// >>>GEN:MENUS", "// <<<GEN:MENUS", gen_menus(mods), MOD_RS)
new_mod = replace_region(new_mod, "// >>>GEN:ROUTER", "// <<<GEN:ROUTER", gen_router(mods), MOD_RS)
new_cargo = replace_region(
app_cargo, "# >>>GEN:PACK_DEPS", "# <<<GEN:PACK_DEPS", gen_pack_deps(packs), APP_CARGO
)
return [PACKS_GEN, MOD_RS, APP_CARGO], [new_packs_gen, new_mod, new_cargo]
def main(argv):
check = "--check" in argv
dry = "--dry-run" in argv
if any(a not in ("--check", "--dry-run") for a in argv):
print(__doc__)
return 2
try:
packs = read_packs()
mods = read_modules()
cross_check(packs, mods)
paths, news = build_outputs(packs, mods)
except SyncError as e:
print(f"❌ {e}", file=sys.stderr)
return 2
drift = []
for path, new in zip(paths, news):
with open(path, encoding="utf-8") as f:
old = f.read()
if old != new:
drift.append(path)
if dry:
for path, new in zip(paths, news):
print(f"===== {os.path.relpath(path, ROOT)} =====")
print(new)
return 0
if check:
if drift:
print("❌ 生成物与 `packs/*` / `modules/*` 漂移:", file=sys.stderr)
for p in drift:
print(" - " + os.path.relpath(p, ROOT), file=sys.stderr)
print(" ⇒ 跑 `python3 scripts/pack-sync.py` 修好,别手改生成段。", file=sys.stderr)
return 1
# 🔴 正向判据:零漂移也要说清「我到底看了几个包」
print(f"✅ pack-sync --check:{len(packs)} 个包 / {len(mods)} 个模块,生成物无漂移")
return 0
for path, new in zip(paths, news):
with open(path, "w", encoding="utf-8") as f:
f.write(new)
print(f"✅ 已同步 {len(packs)} 个包 → {len(drift)} 个文件有变化")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))