#!/usr/bin/env bash # tdc-rs 平台层 / 业务层**边界静态自检**(v3 spec §2.3.2 的 4 个接触点) # # 用法: # bash scripts/check-boundary.sh # 自检(绿 = 0) # bash scripts/check-boundary.sh --report # 只出报告,不判红(排障用) # # 退出码:0 = 绿 / 1 = 有越界(或账本里有失效条目)/ 2 = 前置错误 # # 🔴 **纯静态**:不起后端、不连库、不需要 cargo ⇒ 可以在任何一秒钟跑一遍。 # 🔴 **账本制(ratchet)**:越界不是"一律红",而是"**必须被记账**"—— # `scripts/boundary-ledger.txt` 里逐条列出「已知越界 + 为什么 + 谁负责清」。 # 没记账的越界 ⇒ 红(当场抓新增泄漏);记账已失效的条目 ⇒ 红(账本只许变短)。 # ⇒ B1b 的 C1–C12 做完,账本必须清空。 # # 扫描口径(**接触点的判定规则,写死在这里,避免"尺子随实现漂移"**): # ① 只扫**非测试代码**:每个文件里第一处 `#[cfg(test)]` 之后的内容不计入 # (单元测试必须引用具体实体/端点才有意义;生产代码不许)。 # ② 注释不计入(`//` 行注释、`/* */` 块注释都先剥掉)。 # ③ 平台层 = `src/platform/**`(新布局)或旧布局的平台件清单(见 `PLATFORM_LEGACY`)。 # ④ 通用 CRUD 引擎 = `src/tdc/{mapper,service/crud,controller/crud}.rs`(新布局) # 或 `src/crud.rs` + `src/routes/crud.rs`(旧布局)。 # # 🔴 **CP5 是 C9 之后补的第 5 条**(v3 spec §2.3.2 的 4 条接触点之外): # 「平台层不得 import 业务层」—— 拆 `AppState` 之前 `src/platform/state.rs` # 直接 `use crate::tdc::service::account::AccountStore` ⇒ 依赖方向反了, # 而 CP1(只查表名/端点前缀)查不出来 ⇒ 补这条钉住。 set -u if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//' exit 0 fi ROOT="$(cd "$(dirname "$0")/.." && pwd)" LEDGER="${ROOT}/scripts/boundary-ledger.txt" PY_BIN="${PY_BIN-$(command -v python3 2>/dev/null || true)}" REPORT_ONLY=0 [ "${1:-}" = "--report" ] && REPORT_ONLY=1 [ -n "${PY_BIN}" ] || { echo "❌ 前置错误:找不到 python3。"; exit 2; } [ -f "${LEDGER}" ] || { echo "❌ 前置错误:账本 ${LEDGER} 不存在。"; exit 2; } TMP="$(mktemp -d)" trap 'rm -rf "${TMP}"' EXIT cat >"${TMP}/check.py" <<'PYEOF' import os import re import sys ROOT = sys.argv[1] LEDGER = sys.argv[2] REPORT_ONLY = sys.argv[3] == "report" # ---- 布局判定 ------------------------------------------------------ NEW_LAYOUT = os.path.isdir(os.path.join(ROOT, "src/platform")) if NEW_LAYOUT: PLATFORM_FILES = [] for dirpath, _dirs, files in os.walk(os.path.join(ROOT, "src/platform")): for f in files: if f.endswith(".rs"): PLATFORM_FILES.append(os.path.relpath(os.path.join(dirpath, f), ROOT)) ENGINE_FILES = [ "src/tdc/mapper.rs", "src/tdc/service/crud.rs", "src/tdc/controller/crud.rs", ] AUTH_FILE = "src/platform/auth.rs" LAYOUT = "新布局(src/platform + src/tdc)" else: PLATFORM_FILES = [ "src/auth.rs", "src/db.rs", "src/session.rs", "src/envelope.rs", "src/cipher.rs", "src/ids.rs", "src/protocol.rs", "src/state.rs", "src/config.rs", "src/routes/mw.rs", "src/routes/fallback.rs", "src/routes/body.rs", ] ENGINE_FILES = ["src/crud.rs", "src/routes/crud.rs"] AUTH_FILE = "src/auth.rs" LAYOUT = "旧布局(src/*.rs + src/routes/*)" # 业务实体名(18 个)——从注册表源码里抽,抽不到就用兜底清单 REGISTRY_CANDIDATES = ["src/registry.rs"] if os.path.isdir(os.path.join(ROOT, "src/tdc/entity")): for dirpath, _dirs, files in os.walk(os.path.join(ROOT, "src/tdc/entity")): for f in files: if f.endswith(".rs"): REGISTRY_CANDIDATES.append( os.path.relpath(os.path.join(dirpath, f), ROOT)) ENTITY_FALLBACK = [ "ApiConsumeLog", "AuditLog", "Contract", "Credential", "DataInterface", "Dataset", "Datasource", "DeliveryLog", "DeliveryTask", "DestroyLog", "Identity", "Notification", "Order", "Policy", "PolicyCheckLog", "PolicyTemplate", "Product", "Resource", ] def read(path): p = os.path.join(ROOT, path) if not os.path.isfile(p): return None with open(p, encoding="utf-8", errors="replace") as fh: return fh.read() def strip_comments(text): """剥掉行注释与块注释,**但保留字符串字面量里的 // 与 /* ** (白名单里就有 "/api/ssw/tdc/P2P/Transfer/*/Chunk" 这种串 ⇒ 用朴素的 正则剥注释会把它误判成块注释开头,把后面的行整片吃掉)。""" out = [] i = 0 n = len(text) in_str = False in_block = False in_line = False while i < n: ch = text[i] if in_line: if ch == "\n": in_line = False out.append(ch) i += 1 continue if in_block: if ch == "*" and i + 1 < n and text[i + 1] == "/": in_block = False i += 2 continue if ch == "\n": out.append(ch) i += 1 continue if in_str: out.append(ch) if ch == "\\" and i + 1 < n: out.append(text[i + 1]) i += 2 continue if ch == '"': in_str = False i += 1 continue if ch == "/" and i + 1 < n and text[i + 1] == "/": in_line = True i += 2 continue if ch == "/" and i + 1 < n and text[i + 1] == "*": in_block = True i += 2 continue if ch == '"': in_str = True out.append(ch) i += 1 continue out.append(ch) i += 1 return "".join(out) def code_lines(path): """只返回**非测试、非注释**的代码行(行号从 1 开始)。""" text = read(path) if text is None: return None lines = text.split("\n") cut = len(lines) for i, l in enumerate(lines): if re.match(r"\s*#\[cfg\(test\)\]", l): cut = i break stripped = strip_comments("\n".join(lines[:cut])) return [(i + 1, l) for i, l in enumerate(stripped.split("\n"))] def entity_names(): names = set() for path in REGISTRY_CANDIDATES: text = read(path) if text is None: continue names.update(re.findall(r'api_name:\s*"([A-Za-z0-9_]+)"', text)) return sorted(names) if names else ENTITY_FALLBACK # ---- 账本 ---------------------------------------------------------- def load_ledger(): rows = [] if not os.path.isfile(LEDGER): return rows with open(LEDGER, encoding="utf-8") as fh: for raw in fh: line = raw.rstrip("\n") if not line.strip() or line.lstrip().startswith("#"): continue parts = line.split("\t") if len(parts) < 4: continue rows.append({ "rule": parts[0].strip(), "file": parts[1].strip(), "pattern": parts[2].strip(), "note": parts[3].strip(), "owner": (parts[4].strip() if len(parts) > 4 else "B1b"), }) return rows def ledger_file_matches(ledger_file, actual_file): """账本里的文件字段按**路径后缀**匹配 ⇒ 搬家(src/auth.rs → src/platform/auth.rs) 不会让账本条目失效。""" if not ledger_file: return False return actual_file == ledger_file or actual_file.endswith("/" + ledger_file) # ---- 采集发现 ------------------------------------------------------ findings = [] # (rule, file, line, text, token) def add(rule, path, lineno, text, token): findings.append((rule, path, lineno, text.strip(), token)) ENTITIES = entity_names() # CP1:平台层不得出现 tdc_ 表名前缀 / /api/ssw/tdc/ 端点前缀 for path in PLATFORM_FILES: lines = code_lines(path) if lines is None: continue for lineno, s in lines: for pat in ("tdc_", "/api/ssw/tdc/"): if pat in s: add("CP1", path, lineno, s, pat) # CP5:平台层**不得 import 业务层**(平台 → 业务的反向依赖) # # 🔴 这条是 C9 之后补上的:拆 `AppState` 之前,`src/platform/state.rs` 直接 # `use crate::tdc::service::account::AccountStore` / `use crate::tdc::client::tds::TdsClient` # ⇒ 平台层被迫认识业务类型 ⇒ 依赖方向反了。 # CP1 只查「表名前缀 / 端点前缀」,查不出 `crate::tdc::` 这种**模块引用** ⇒ 补这条。 for path in PLATFORM_FILES: lines = code_lines(path) if lines is None: continue for lineno, s in lines: for m in re.finditer(r"\buse\s+(?:crate|super)::tdc\b", s): add("CP5", path, lineno, s, m.group(0)) # CP2:平台层不得出现具体实体名 for path in PLATFORM_FILES: lines = code_lines(path) if lines is None: continue for lineno, s in lines: for ent in ENTITIES: if re.search(r"\b" + re.escape(ent) + r"\b", s): add("CP2", path, lineno, s, ent) # CP3:通用 CRUD 引擎不得按实体名分支 ENGINE_PATTERNS = [ r"match\s+api_name", r"match\s+spec\.api_name", r"api_name\s*==", r"api_name\.eq\(", r"api_name\.starts_with\(", r"api_name\.as_str\(", r"find\(\s*\"[A-Za-z]+\"\s*\)", ] for path in ENGINE_FILES: lines = code_lines(path) if lines is None: continue for lineno, s in lines: for pat in ENGINE_PATTERNS: if re.search(pat, s): add("CP3", path, lineno, s, pat) # CP4:平台 auth 不得出现字面量端点路径("/api/" + 至少一段) auth_lines = code_lines(AUTH_FILE) if auth_lines is None: print("❌ 前置错误:找不到平台 auth 文件(%s)。" % AUTH_FILE) sys.exit(2) for lineno, s in auth_lines: for m in re.finditer(r'"(/api/[^"]+)"', s): add("CP4", AUTH_FILE, lineno, s, m.group(1)) # ---- 分类 ---------------------------------------------------------- ledger = load_ledger() new_findings = [] known = [] matched_rows = set() for f in findings: hit = None for i, row in enumerate(ledger): if row["rule"] != f[0]: continue if not ledger_file_matches(row["file"], f[1]): continue if row["pattern"] and row["pattern"] not in f[3]: continue hit = i break if hit is None: new_findings.append(f) else: # 🔴 一条账本条目可以覆盖**多处**发现(如 auth.rs 的整张白名单)⇒ 不做一对一消耗。 matched_rows.add(hit) known.append((f, ledger[hit])) stale = [row for i, row in enumerate(ledger) if i not in matched_rows] # ---- 报告 ---------------------------------------------------------- print("布局:%s" % LAYOUT) print("平台层文件 %d 个 · 引擎文件 %d 个 · 业务实体 %d 个" % (len(PLATFORM_FILES), len(ENGINE_FILES), len(ENTITIES))) print("账本条目 %d 条" % len(ledger)) print() RULE_DESC = { "CP1": "平台层不得出现 tdc_ 表名前缀 / /api/ssw/tdc/ 端点前缀", "CP2": "平台层不得出现具体业务实体名", "CP3": "通用 CRUD 引擎不得按实体名分支(只能读 TableSpec 字段)", "CP4": "平台 auth 不得出现字面量端点路径(只能引用业务层清单)", "CP5": "平台层不得 import 业务层(平台 → 业务的反向依赖)", } for rule in ("CP1", "CP2", "CP3", "CP4", "CP5"): rs = [f for f in findings if f[0] == rule] print("%s:%d 处发现 —— %s" % (rule, len(rs), RULE_DESC[rule])) for f in rs: print(" %s:%s %s" % (f[1], f[2], f[3][:96])) print() if known: print("已记账(%d 处)—— 账本里写明为什么可接受:" % len(known)) for f, row in known: print(" %s %s:%s ← 账本[%s]:%s(%s)" % (f[0], f[1], f[2], row["owner"], row["pattern"] or "<该文件全部>", row["note"])) print() if new_findings: print("❌ 未记账的越界 %d 处(**当场红**):" % len(new_findings)) for f in new_findings: print(" %s %s:%s %s" % (f[0], f[1], f[2], f[3][:96])) print() if stale: print("❌ 账本里 %d 条已失效(越界已消失,账本只许变短 ⇒ 请删行):" % len(stale)) for row in stale: print(" %s %s [%s] %s" % (row["rule"], row["file"], row["pattern"], row["note"])) print() pending = [r for r in ledger if r["owner"] != "永久"] print("账本待清账(B1b 责任)%d 条 · 永久豁免 %d 条" % (len(pending), len(ledger) - len(pending))) ok = (not new_findings) and (not stale) if ok: print("边界自检通过 ✅(0 处未记账越界,0 条失效账本条目)") sys.exit(0) if REPORT_ONLY: print("(--report:只报告,不判红)") sys.exit(0) sys.exit(1) PYEOF "${PY_BIN}" "${TMP}/check.py" "${ROOT}" "${LEDGER}" "$([ "${REPORT_ONLY}" -eq 1 ] && echo report || echo check)" rc=$? if [ "${rc}" -eq 2 ]; then exit 2 fi exit "${rc}"