Files
ssw-platform/scripts/check-boundary-scan.py
T
sukyboor 9771fa844d init: 尚数网平台 JNPF 7.0 兼容后端(多应用 + 面 A/面 B 双契约)
- axum 0.8 + pglite:12 张表,多应用按 App-Code 头解析 f_system_id 隔离
- 面 A(ssw/react 形状)+ 面 B(官方 JNPF 形状,Vue-Version: 3)双契约并存
- 业务模块 asset/DataResource;面 B 用户 CRUD 9 条已落地
- 六道闸门 + 两把运行时尺子(perm-smoke 43 / perm-smoke-jnpf 23)
- scripts/:前端接口清单、页面依赖反查、运行时探针
2026-10-30 22:08:31 +08:00

246 lines
8.9 KiB
Python
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
"""check-boundary-scan.py —— 平台层「零业务知识」扫描器(`check-boundary.sh` 的 CP1 后端)。
🔴 **为什么需要它**:CLAUDE.md 红线 12 要求「加一个业务模块只碰业务层」
⇒ 平台层(`src/backend/src/platform/`)里**不许出现任何业务标识符**
(业务表名 / 实体名 / 路由前缀 / 菜单 id / 菜单 url / 菜单 en_code)。
这条规则**只靠人看代码守不住** —— 加模块的人不会主动去看平台层 ⇒ 需要一把尺子。
🔴 **禁止的标识符清单从业务层自己派生**(不是手写常量表):
业务层说了什么 ⇒ 平台层就不许出现什么 ⇒ **加一个业务模块,这把尺子自动变严**,
不会出现「忘了同步常量表 ⇒ 漏检」。
🔴 **只扫「字符串字面量」**(注释不算):
注释里举例说明业务名是**文档行为**(例如解释 CTE 作用域)⇒ 允许;
代码里出现业务标识符才是**耦合** ⇒ 拦。
用法:
python3 scripts/check-boundary-scan.py <modules_dir> <scan_dir> [<scan_dir>...]
退出码:
0 = 干净(平台层零业务标识符)
1 = 发现泄漏(逐条打印 `文件:行号: [种类] token`)
2 = 用法错
"""
import os
import re
import sys
# 🔴 业务层里「哪些字段是业务知识」的抽取规则(与 `EntitySpec` / `MenuSpec` 的字段名对齐)。
SPEC_TABLE_RE = re.compile(r'table:\s*"([^"]+)"')
SPEC_ENTITY_RE = re.compile(r'entity:\s*"([^"]+)"')
SPEC_APP_RE = re.compile(r'app_code:\s*"([^"]+)"')
MENU_BLOCK_RE = re.compile(r'MenuSpec\s*\{(.*?)\n\};', re.DOTALL)
MENU_FIELD_RE = {
# 🔴 `\b` 不可省:否则 `parent_id: "0"` 里的 `id:` 会被当成菜单 id。
"id": re.compile(r'\bid:\s*"([^"]+)"'),
"en_code": re.compile(r'\ben_code:\s*"([^"]+)"'),
"url_address": re.compile(r'\burl_address:\s*"([^"]+)"'),
}
# 🔴 字符串字面量:`r#"..."#` / `r"..."` / `"..."`(普通串的转义 `\"` 不影响子串判定)。
LITERAL_RE = re.compile(r'r(#*)"(.*?)"\1|"((?:[^"\\]|\\.)*)"', re.DOTALL)
def strip_comments(src):
"""去掉 `//` 行注释与 `/* */` 块注释(保留字符串字面量里的内容)。
🔴 逐字符扫描 ⇒ 字符串里的 `//`(如 `"http://x"`)不会被误当注释。
"""
out = []
in_block = False
for line in src.splitlines():
if in_block:
end = line.find("*/")
if end == -1:
continue
line = line[end + 2:]
in_block = False
buf = []
in_str = False
i = 0
n = len(line)
while i < n:
c = line[i]
if in_str:
buf.append(c)
if c == "\\" and i + 1 < n:
buf.append(line[i + 1])
i += 2
continue
if c == '"':
in_str = False
i += 1
continue
if c == '"':
in_str = True
buf.append(c)
i += 1
continue
if line.startswith("//", i):
break
if line.startswith("/*", i):
in_block = True
rest = line[i + 2:]
end = rest.find("*/")
if end == -1:
break
line = rest[end + 2:]
buf = []
i = 0
n = len(line)
in_str = False
continue
buf.append(c)
i += 1
out.append("".join(buf))
return out
def literals_with_lines(path):
"""⇒ [(行号, 字面量内容)](注释已剔除)。"""
with open(path, "r", encoding="utf-8") as fh:
lines = strip_comments(fh.read())
out = []
for idx, line in enumerate(lines, start=1):
for m in LITERAL_RE.finditer(line):
content = m.group(2) if m.group(1) is not None else m.group(3)
if content is not None:
out.append((idx, content))
return out
def business_tokens(modules_dir):
"""从业务层派生「平台层不许出现」的标识符清单。
⇒ [(种类, token)],种类用于报错时点名「漏的是哪一类」。
"""
tokens = []
seen = set()
def add(kind, value):
if not value:
return
key = (kind, value)
if key in seen:
return
seen.add(key)
tokens.append((kind, value))
for name in sorted(os.listdir(modules_dir)):
if not name.endswith(".rs") or name == "mod.rs":
continue
path = os.path.join(modules_dir, name)
with open(path, "r", encoding="utf-8") as fh:
src = "\n".join(strip_comments(fh.read()))
for m in SPEC_TABLE_RE.finditer(src):
add("业务表名", m.group(1))
for m in SPEC_ENTITY_RE.finditer(src):
add("业务实体名", m.group(1))
for m in SPEC_APP_RE.finditer(src):
add("业务路由前缀", "/api/ssw/{}/".format(m.group(1)))
for m in MENU_BLOCK_RE.finditer(src):
body = m.group(1)
for kind, rx in MENU_FIELD_RE.items():
for f in rx.finditer(body):
add("业务菜单 {}".format(kind), f.group(1))
return tokens
def rust_files(root):
"""⇒ root 下全部 `.rs` 文件(递归,按路径排序)。"""
out = []
for dirpath, dirnames, filenames in os.walk(root):
dirnames.sort()
for name in sorted(filenames):
if name.endswith(".rs"):
out.append(os.path.join(dirpath, name))
return out
def main(argv):
if len(argv) >= 2 and argv[1] == "--self-test":
return self_test()
if len(argv) < 3:
sys.stderr.write(
"用法: python3 scripts/check-boundary-scan.py <modules_dir> <scan_dir> [...]\n"
)
return 2
modules_dir = argv[1]
scan_dirs = argv[2:]
tokens = business_tokens(modules_dir)
if not tokens:
sys.stderr.write("业务层没解析出任何标识符(modules_dir 有问题?)\n")
return 2
violations = []
scanned = 0
for root in scan_dirs:
for path in rust_files(root):
scanned += 1
rel = os.path.relpath(path)
for lineno, content in literals_with_lines(path):
for kind, token in tokens:
if token in content:
violations.append((rel, lineno, kind, token, content.strip()))
for rel, lineno, kind, token, content in violations:
print("{}:{}: [{}] {} ← 字面量: {}".format(rel, lineno, kind, token, content[:120]))
print("scanned_files={} tokens={} violations={}".format(scanned, len(tokens), len(violations)))
return 1 if violations else 0
def self_test():
"""🔴 **反自证**:造一个「平台层泄漏业务表名」的假文件 ⇒ 必须被抓出来。
🔴 **为什么必须有**:一把永远返回「干净」的尺子 = 没有尺子。
自证 = 用同一条规则去抓一个**明知存在**的泄漏 ⇒ 抓到了 ⇒ 规则本身有效。
"""
import tempfile
with tempfile.TemporaryDirectory() as tmp:
mods = os.path.join(tmp, "modules")
plat = os.path.join(tmp, "platform")
os.makedirs(mods)
os.makedirs(plat)
with open(os.path.join(mods, "demo.rs"), "w", encoding="utf-8") as fh:
fh.write(
'pub const DEMO_SPEC: EntitySpec = EntitySpec {\n'
' app_code: "demo",\n'
' entity: "DemoItem",\n'
' table: "demo_item",\n'
'};\n'
)
# 泄漏:平台层里出现了业务表名(**在字符串字面量里**)。
with open(os.path.join(plat, "leak.rs"), "w", encoding="utf-8") as fh:
fh.write('const SQL: &str = "SELECT * FROM demo_item";\n')
# 不泄漏:只在**注释**里提到业务表名(文档行为,允许)。
with open(os.path.join(plat, "doc.rs"), "w", encoding="utf-8") as fh:
fh.write('// 例:SELECT * FROM demo_item\nconst OK: &str = "SELECT 1";\n')
tokens = business_tokens(mods)
# 表名 + 实体名 + 路由前缀(假 spec 里没有 MenuSpec ⇒ 没有菜单那三类)。
if len(tokens) != 3:
print("self-test: token 抽取数不对: {}".format(len(tokens)))
return 1
hits = 0
for path in rust_files(plat):
for _lineno, content in literals_with_lines(path):
for _kind, token in tokens:
if token in content:
hits += 1
if hits != 1:
print("self-test: 应恰好抓到 1 处泄漏,实际 {} 处".format(hits))
return 1
print("self-test: OK(泄漏被抓到、注释里的举例未被误报)")
return 0
if __name__ == "__main__":
sys.exit(main(sys.argv))