#!/usr/bin/env python3 # -*- coding: utf-8 -*- """check-contract-scan —— **契约 ↔ 代码** 对账扫描器。 🔴 为什么存在: `docs/contract.md` 的端点表原先是**散文表格**(§6.1–§6.5), 代码里的路由注册是**另一处**(`routes.rs` / `modules/*.rs`)⇒ 加端点、改路径、改守卫 ⇒ 契约与代码**各改各的** ⇒ 漂移没人发现。 本脚本把契约的机器可读区段 `[ENDPOINT]` / `[FACE]` 与**代码里真实注册的路由** 逐条对账,**双向**都查(契约多 / 代码多 / 方法不符 / 归属层不符 / 守卫不符)。 🔴 **只做静态检查**:不启动后端、不发请求。纯 `python3`(macOS 自带)。 用法: check-contract-scan.py --contract <契约文件> --src <后端 src 目录> check-contract-scan.py --self-test 输出协议(制表符分隔,逐行一条): CHECK\t\t\t<说明> WARN\t\t<说明> # 推不出守卫之类的「非失败但要看见」 退出码:0 = 扫完(可能有 DRIFT,看输出)/ 2 = 致命错误(契约读不出来等) """ import io import os import re import shutil import sys import tempfile HERE = os.path.dirname(os.path.abspath(__file__)) ROOT = os.path.dirname(HERE) if HERE not in sys.path: sys.path.insert(0, HERE) import contract_expect # noqa: E402 (同目录) # ---------------------------------------------------------------- Rust 源码扫描 # 路由注册:`.route("/api/x", get(handler))`(允许跨行) # 🔴 路径是**字符串字面量** ⇒ 在 masked 里是空白 ⇒ 只在 masked 里定位 `.route(`, # 再用**同一偏移**去原文取路径与方法。 ROUTE_CALL_RE = re.compile(r'\.route\(') # 路由后面的 handler 表达式:`sys::user_list` / `demo_item_list` / `|State(..)| ..`(闭包) HANDLER_RE = re.compile(r'\s*(?:([A-Za-z_][A-Za-z0-9_]*)::)?([A-Za-z_][A-Za-z0-9_]*)') # 契约表里 `{param}` ⇒ 代码里的通配 PARAM_RE = re.compile(r'\{[A-Za-z_][A-Za-z0-9_]*\}') # 测试用的固定路径前缀(**不在契约端点表里** ⇒ 全部扫描都排除) TEST_PATH_PREFIX = "/api/__test__/" # 🔴 业务包的路由声明(批次 12 交付物 ①):`PackRoute { … }` —— 纯数据,不认识 axum。 # 注意:`mask_rust` 会把字符串字面量挖空 ⇒ 只能**在 masked 里定位结构**, # 再用同一偏移去原文取值。 PACK_ROUTE_RE = re.compile(r'PackRoute\s*\{') # 🔴 一次扫全文的「函数定义」正则(见 `_fn_positions`): # 每份文件只跑一遍就能拿到**所有** `fn 名字(` 的位置,避免「查一个函数扫一遍全文」。 FN_DEF_RE = re.compile(r'\bfn\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(') def mask_rust(text): """把字符串字面量 / 注释**挖空**(保持长度不变)⇒ 结构扫描不会被注释/字面量骗。 挖空后拿到的偏移量与原文一一对应 ⇒ 需要字面量的值时,用同一偏移去原文里取。 """ out = list(text) n = len(text) def blank(a, b): for k in range(a, b): if out[k] != "\n": out[k] = " " i = 0 while i < n: c = text[i] if c == "/" and i + 1 < n and text[i + 1] == "/": j = text.find("\n", i) j = n if j < 0 else j blank(i, j) i = j continue if c == "/" and i + 1 < n and text[i + 1] == "*": depth, j = 1, i + 2 while j < n and depth: if text.startswith("/*", j): depth += 1 j += 2 elif text.startswith("*/", j): depth -= 1 j += 2 else: j += 1 blank(i, j) i = j continue if c == "r" and i + 1 < n and text[i + 1] in '#"': m = re.match(r'r(#*)"', text[i:]) if m: hashes = m.group(1) end = text.find('"' + hashes, i + m.end()) j = n if end < 0 else end + 1 + len(hashes) blank(i, j) i = j continue if c == '"': j = i + 1 while j < n: if text[j] == "\\": j += 2 continue if text[j] == '"': j += 1 break j += 1 blank(i, j) i = j continue if c == "'": m = re.match(r"'(\\.|[^\\'])'", text[i:]) if m: blank(i, i + m.end()) i += m.end() continue i += 1 # 生命周期(`'a`)不是字面量 ⇒ 留着 continue i += 1 return "".join(out) def read(path): with io.open(path, encoding="utf-8") as fh: return fh.read() def brace_span(masked, start): """从 `start`(`{` 的位置)开始做括号配对 ⇒ 返回 body 的 (开, 闭) 区间。""" depth = 0 i = start n = len(masked) while i < n: c = masked[i] if c == "{": depth += 1 elif c == "}": depth -= 1 if depth == 0: return start, i + 1 i += 1 return start, n def find_fn_body(masked, fname): """找 `fn (` 的函数体区间 ⇒ 返回 (start, end) 或 None。 🔴 **带缓存**:反自证要跑 13 次 `analyze`,每次都把**同一批文件**重新 `re.search` 一遍(实测 `re.search` 占单次分析 3.0s / 4.7s)。 缓存键用 `id(masked)`,但**同时把 masked 本体存进缓存值** ⇒ 只要缓存项还活着,那个 id 就不可能被别的对象复用 ⇒ **不会脏读**。 """ key = id(masked) entry = _FN_CACHE.get(key) if entry is None or entry[0] is not masked: entry = (masked, {}) _FN_CACHE[key] = entry table = entry[1] # 🔴 必须区分「没查过」与「查过但没有」—— 用哨兵,不能用 `dict.get` 的 None # (同一个文件要查很多个函数名,`get` 会把「没查到」当成「没查过」⇒ 反复重查)。 if fname in table: return table[fname] span = _find_fn_body_uncached(masked, fname) table[fname] = span return span _FN_CACHE = {} _FN_POS_CACHE = {} def _fn_positions(masked): """一次性扫出文件里所有 `fn <名字>(` 的位置 ⇒ `{名字: 左括号之后的位置}`。 🔴 **为什么需要这张表**(实测数据):原来的 `_find_fn_body_uncached` 每查 一个函数名就在**整份文件**上跑一次 `re.search`。同一个文件常被查十几次 (routes.rs 里几十个 handler 都在里面)⇒ 同一份文件被完整正则扫十几遍。 实测 362 次查找里 `re.search` 累计 1.4s,占单次分析的大头。 ⇒ 改成「每份文件只扫一遍」把位置全部拿到,查表 O(1)。  🔴 同名函数(不同 `impl` 块里各有一份)取**第一个**,与原 `re.search(...)` 的语义一致(`re.search` 也是返回第一个匹配)。 """ key = id(masked) entry = _FN_POS_CACHE.get(key) if entry is not None and entry[0] is masked: return entry[1] pos = {} for m in FN_DEF_RE.finditer(masked): name = m.group(1) if name not in pos: pos[name] = m.end() _FN_POS_CACHE[key] = (masked, pos) return pos def _find_fn_body_uncached(masked, fname): q = _fn_positions(masked).get(fname) if q is None: return None i = masked.find("{", q) if i < 0: return None return brace_span(masked, i) def paren_span(masked, start): """从 `start`(`(` 的位置)开始做括号配对 ⇒ 返回 `)` 的下标(失败返回末位)。 🔴 在 `masked` 上跑:字符串字面量已被挖空 ⇒ 参数里的 `(` / `)` 不会干扰配对。 """ depth = 0 i = start n = len(masked) while i < n: c = masked[i] if c == "(": depth += 1 elif c == ")": depth -= 1 if depth == 0: return i i += 1 return n - 1 def scan_routes(path, owner): """扫一个源文件里的 `.route(...)` ⇒ [{path, method, handler_mod, handler_fn, closure}]。""" orig = read(path) masked = mask_rust(orig) out = [] for m in ROUTE_CALL_RE.finditer(masked): p = m.end() while p < len(orig) and orig[p] in " \t\r\n": p += 1 if p >= len(orig) or orig[p] != '"': continue q = p + 1 while q < len(orig) and orig[q] != '"': if orig[q] == "\\": q += 1 q += 1 if q >= len(orig): continue route = orig[p + 1:q] p = q + 1 while p < len(orig) and orig[p] in " \t\r\n": p += 1 if p < len(orig) and orig[p] == ",": p += 1 while p < len(orig) and orig[p] in " \t\r\n": p += 1 if route.startswith(TEST_PATH_PREFIX): continue # 仅测试构建存在的端点 ⇒ 不在契约端点表里 # 🔴 一条 `.route(path, …)` 里可能有**多个**方法:`.route(p, get(a).post(b))` # —— axum 对同一 path **只准 `.route()` 一次**(重复会 panic # `Overlapping method route`),所以「列表 GET + 新建 POST」必然链在一起。 # 老实现只取**第一个**方法 ⇒ 后面的方法**静默消失**:契约里写 implemented, # 却报「代码里没有这条路由」(批次 14 踩到)。 cursor = p while True: mm = re.match(r"(get|post|put|delete)\s*\(", orig[cursor:]) if not mm: break if masked[cursor:cursor + len(mm.group(1))] != mm.group(1): break # 方法名其实落在字符串里(误报) method = mm.group(1).upper() name_start = cursor + mm.end() close = paren_span(masked, cursor + mm.end() - 1) rest = orig[name_start:name_start + 240] hm = HANDLER_RE.match(rest) mod, fn, closure = None, None, True if hm and hm.group(2): mod, fn = hm.group(1), hm.group(2) closure = False out.append({ "path": route, "method": method, "mod": mod, "fn": fn, "closure": closure, "owner": owner, # 🔴 `source` 区分「路由住在哪」:平台层 / 业务模块(面 A)/ 业务包(面 B)。 # owner 会撞(包与模块同 app_code)⇒ 守卫推导与台账范围**必须**看这个。 "source": "platform" if owner == "platform" else "module", "const": None, "file": path, }) # 顺着 `.` 走到下一个方法;遇到 `,` / `)` / 文件尾就停。 cursor = close + 1 while cursor < len(orig) and orig[cursor] in " \t\r\n": cursor += 1 if cursor < len(orig) and orig[cursor] == ".": cursor += 1 while cursor < len(orig) and orig[cursor] in " \t\r\n": cursor += 1 continue break return out, orig, masked def resolve_const(orig, masked, name): """`const NAME: &str = "value";` ⇒ value(取原文里的字面量)。 🔴 **带缓存**(同 [`find_fn_body`] 的理由):本函数在**整份文件**上跑正则, 362 条平台端点的守卫推导会反复查同一批常量名。 """ key = id(orig) entry = _CONST_CACHE.get(key) if entry is None or entry[0] is not orig: entry = (orig, {}) _CONST_CACHE[key] = entry table = entry[1] if name in table: return table[name] m = re.search(r"\bconst\s+" + re.escape(name) + r"\b[^=]*=\s*\"([^\"]*)\"", orig) value = m.group(1) if m else None table[name] = value return value _CONST_CACHE = {} def guard_of_platform(plat_files, mod, fn): """平台层 handler 的守卫 ⇒ 菜单 key / 点权限编码 / 登录 / 无;推不出 ⇒ None。 `plat_files` = {"sys": (orig, masked), "face_b": (orig, masked), ...} """ if mod == "auth" and fn == "login_handler": return "无" if mod is None: # routes.rs 里自己定义的 handler(如 `health`)⇒ 没有守卫调用 ⇒ 无 pair = plat_files.get("__routes__") if not pair: return None orig, masked = pair span = find_fn_body(masked, fn) if not span: return None body = masked[span[0]:span[1]] if re.search(r"require_(login|module|login_jnpf)\s*\(", body) or re.search(r"\bguard\s*\(", body): return None return "无" pair = plat_files.get(mod) if not pair: return None orig, masked = pair span = find_fn_body(masked, fn) if not span: return None body = masked[span[0]:span[1]] if mod == "sys": m = re.search(r"require_module\(\s*&state\s*,\s*&headers\s*,\s*([A-Z_][A-Z0-9_]*)\s*\)", body) if m: return resolve_const(orig, masked, m.group(1)) if re.search(r"require_login(_any)?\s*\(", body): return "登录" return None # 🔴 面 B 的实现文件 2026-10-26 从 `jnpf.rs` 改名为 `face_b.rs` # ⇒ 这里**两个名字都认**(只认旧名会让整片面 B 的守卫检查静默失效)。 if mod in ("jnpf", "face_b"): m = re.search(r"guard\(\s*&state\s*,\s*&headers\s*,\s*([A-Z_][A-Z0-9_]*)\s*\)", body) if m: return resolve_const(orig, masked, m.group(1)) # 🔴 官方的 `@SaCheckPermission(value={A,B}, mode=OR)` ⇒ 本仓 `guard_any(&[A,B])`: # 契约里写成 `A|B`(同一个分隔符,**顺序即代码里的顺序**)。 m = re.search(r"guard_any\(\s*&state\s*,\s*&headers\s*,\s*&\[([^\]]*)\]", body) if m: codes = [] for name in re.findall(r"\b[A-Z_][A-Z0-9_]*\b", m.group(1)): value = resolve_const(orig, masked, name) if value: codes.append(value) return "|".join(codes) if codes else None if re.search(r"require_login_(jnpf|face_b)\s*\(", body): return "登录" return None return None def guard_of_closure(orig, masked, rest): """闭包 handler(只有 `CurrentUser` 一处)⇒ 看它调了谁。""" if "auth::current_user" in rest: return "登录" return None def guard_of_module(orig, masked): """业务模块的守卫 ⇒ 它的 `EntitySpec.module_key`(None ⇒ 仅登录)。 🔴 在 **masked** 里定位 `module_key:`(注释里的假 mention 被挖空了), 再用**同一偏移**去原文取真值(字面量在 masked 里是空格)。 🔴 **spec 搬进包之后本函数会推不出**(批次 12 交付物 ②): `modules/asset.rs` 现在只做 `pub use sspf_pack_asset::DATA_RESOURCE_SPEC;` ⇒ 文件里**没有 `module_key` 字面量** ⇒ 返回 None ⇒ CC6 只能报「推不出」。 ⇒ 这不是「推不出」,是**真源搬走了** ⇒ 必须回落到包里的 spec。 见 [`guard_of_module_with_pack_fallback`]。 """ for m in re.finditer(r"module_key:", masked): tail = orig[m.end():m.end() + 60] if re.match(r"\s*None", tail): return "登录" mm = re.match(r'\s*Some\(\s*"([^"]*)"\s*\)', tail) if mm: return mm.group(1) return None def guard_of_module_with_pack_fallback(orig, masked, app, pack_orig, pack_masked): """面 A 的守卫:先看模块文件;**模块只是 re-export 时回落同 app 的包里的 spec**。 🔴 **为什么要回落**(而不是让 CC6 报「推不出」): 「推不出」是给**真的静态分析不了**的情况留的(比如 handler 里做了动态判断)。 而 asset 的 `module_key` 是**确定存在**的 —— 只是住在包里。 把它报成「推不出」⇒ 面 A 的守卫**从此不再被检查**(静默失效)⇒ 正是本仓最怕的那类退化:尺子还在跑,但已经瞎了。 🔴 **必须按 `app` 精确匹配,不能取「排序后第一个包」**(2026-11-01 修的真 bug): 只有一个包时「第一个」碰巧等于「同 app 的」⇒ 看起来对; 加第二个包(`probe`)后,`sorted()` 仍从 `asset` 开始 ⇒ **probe 的面 A 守卫被推成 `asset/DataResource`** ⇒ CC6 报「守卫漂移」, 而契约其实是**对的** ⇒ 假飘移 3 条 ⇒ 人会去改对的契约。 ⇒ 用 `app` 查对应的包;查不到就老老实实返回 `None`(= 推不出,人工核对)。 """ key = guard_of_module(orig, masked) if key is not None: return key if app not in pack_orig: return None specs = scan_entities(pack_orig[app], pack_masked[app]) if not specs: return None return specs[0]["module_key"] if specs[0]["module_key"] else "登录" def scan_pack_routes(path, owner): """扫业务包里的 `PackRoute` 声明 ⇒ [{path, method, entity, …}]。 🔴 **形状与 `.route()` 完全不同**(批次 12 交付物 ①): 业务包**不认识 axum** ⇒ 路由是**纯数据声明**: pub const DATA_RESOURCE_LIST_ROUTE: PackRoute = PackRoute { path: "/api/asset/DataResource/List", method: HttpMethod::Get, entity: "DataResource", action: RouteAction::List, }; ⇒ 扫描器要认得 `PackRoute { … }` 这个形状 ⇒ 把路径 / 方法 / 实体抽出来。 ⇒ 返回的条目与 `.route()` 扫出来的**同构** ⇒ 下游的 CC2–CC10 一行都不用改(这是「同构」的价值)。 """ orig = read(path) masked = mask_rust(orig) out = [] for m in PACK_ROUTE_RE.finditer(masked): body = orig[m.start():m.start() + 800] pm = re.search(r'path:\s*"([^"]+)"', body) mm = re.search(r"method:\s*HttpMethod::(\w+)", body) em = re.search(r'entity:\s*"([^"]+)"', body) am = re.search(r"action:\s*RouteAction::(\w+)", body) if not (pm and mm and em): continue out.append({ "path": pm.group(1), "method": mm.group(1).upper(), "mod": None, "fn": None, "closure": False, "owner": owner, # 🔴 **来源标记**:`pack` / `module` / `platform` —— # CC6 的守卫推导与 CC10 的台账范围**必须**按来源分派: # - 包路由是**面 B**(点权限),模块路由是**面 A**(菜单路径)⇒ # 两者**同 app_code 同 owner**(都叫 `asset`)⇒ 只看 owner 会串线。 "source": "pack", # 常量名(CC8 核对「声明了但没进 *_ROUTES 数组」用)⇒ 找不到就没这项。 "const": _pack_route_const(masked, m.start()), "entity": em.group(1), "action": am.group(1) if am else None, # 🔴 **守卫**(面 B 的点权限编码)—— 与 `.route()` 扫出来的条目**同构** # ⇒ CC6 的守卫对账对包路由**一行都不用改**。 "guard": _guard_of_pack_route(body), "file": path, }) return out, orig, masked def _pack_route_const(masked, at): """从 `PackRoute {` 的位置**往回**找最近的 `const NAME: PackRoute =` ⇒ NAME。 🔴 为什么要常量名:`DATA_RESOURCE_ROUTES` 数组是**按名字**收集这些常量的 ⇒ 「声明了常量但忘了加进数组」⇒ 路由**不注册**、**不报错**、**静默 404**。 CC8 用这个名字集合与数组做双向对账 ⇒ 把这个坑变成红的。 """ back = masked[max(0, at - 200):at] hits = re.findall(r"const\s+(\w+)\s*:\s*PackRoute\s*=", back) return hits[-1] if hits else None def pack_route_array(masked): """包的 `const XXX_ROUTES: &[PackRoute] = &[A, B, C];` ⇒ (数组名, [常量名])。 找不到(纯元数据包,没有路由)⇒ `(None, [])`。 """ m = re.search(r"const\s+(\w+)\s*:\s*&\[PackRoute\]\s*=\s*&\[", masked) if not m: return None, [] start = masked.find("[", m.end() - 1) depth = 0 end = -1 for k in range(start, len(masked)): if masked[k] == "[": depth += 1 elif masked[k] == "]": depth -= 1 if depth == 0: end = k break if end < 0: return m.group(1), [] names = re.findall(r"\b[A-Za-z_][A-Za-z0-9_]*\b", masked[start:end]) return m.group(1), names def _guard_of_pack_route(body): """`PackRoute { … guard: RouteGuard::EnCode("xxx") … }` ⇒ 守卫字符串。 🔴 `RouteGuard::Login` ⇒ `"登录"`;`EnCode("x")` ⇒ `"x"`; 缺 guard 字段 ⇒ `None`(**旧格式的包** ⇒ 让 CC6 报「推不出守卫」)。 """ m = re.search(r'guard\s*:\s*RouteGuard::EnCode\(\s*"([^"]*)"\s*\)', body) if m: return m.group(1) if re.search(r"guard\s*:\s*RouteGuard::Login", body): return "登录" return None def guard_of_pack(orig, masked, route): """**已废弃**:面 A 的守卫口径(`module_key`)—— 包路由走面 B,见 [`guard_of_pack_entity`]。""" raise AssertionError("guard_of_pack 已废弃:包路由是面 B,用 guard_of_pack_entity") # ---------------------------------------------------------------- 业务包的 spec / 菜单 # # 🔴 **为什么这些解析器住在扫描器里**(而不是 `pack-sync.py` 自己写一份): # 包里的 `EntitySpec` / `MenuSpec` 会被**两处**消费: # ① `scripts/pack-sync.py` —— 生成契约表的 `[MODULE]` / `[MENU]` / `[ENDPOINT]`; # ② 本扫描器 —— 从「实体 ⇒ module_key ⇒ 菜单 en_code」推导面 B 的守卫(CC6)。 # ⇒ 复制一份就会**产生第二份解析器** ⇒ 两份迟早分叉 ⇒ # 生成段与守卫对账的**口径不一致**(一类最难受的漂移:两边都"对",结论相反)。 # ⇒ 真源在这里,`pack-sync.py` 复用。 def const_body(orig, masked, name): """`const NAME: T = …;` 的**值部分**(原文)⇒ 找不到返回 None。 🔴 在 masked 里定位结构(避开注释里的假 mention),再用同一偏移去原文取值。 """ m = re.search(r"\b(?:pub\s+)?const\s+" + re.escape(name) + r"\b[^=]*=", masked) if not m: return None start = m.end() i = start while i < len(masked) and masked[i] in " \t\r\n": i += 1 if i >= len(masked): return None if masked[i] == "{": span = brace_span(masked, i) return orig[start:span[1]] if masked[i] == "[": depth = 0 j = i while j < len(masked): if masked[j] == "[": depth += 1 elif masked[j] == "]": depth -= 1 if depth == 0: break j += 1 return orig[start:j + 1] # 标量(`&str`)⇒ 找分号 j = orig.find(";", start) if j < 0: return None return orig[start:j] def str_field(body, field): """结构体字面量里的 `field: "value",` ⇒ value。 🔴 `(?/packs`)—— 不扫它 ⇒ 包路由不在「代码真实路由」 # 里 ⇒ CC2/CC3 判**假漂移**(契约有、代码说没有),这类假警报最耗费信任。 packs_dir = os.path.join(ROOT, "packs") i = 1 while i < len(argv): if argv[i] == "--contract" and i + 1 < len(argv): contract = argv[i + 1] i += 2 continue if argv[i] == "--src" and i + 1 < len(argv): src_dir = argv[i + 1] i += 2 continue if argv[i] == "--packs" and i + 1 < len(argv): packs_dir = argv[i + 1] i += 2 continue if argv[i] == "--self-test": # 🔴 反自证也要扫 `packs/`:不然「真实契约零漂移」这一关会因为 # 包路由只在契约里、不在代码侧而**假失败**。 return self_test(contract, src_dir, packs_dir) sys.stderr.write("check-contract-scan: 未知参数 %r\n" % argv[i]) return 2 try: rep = analyze(contract, src_dir, packs_dir) except contract_expect.ContractError as exc: sys.stderr.write("check-contract-scan: %s\n" % exc) return 2 for line in rep.lines(): print(line) return 0 if __name__ == "__main__": sys.exit(main(sys.argv))