Files
tdc-rs/scripts/check-citations.py
T
adminandClaude Code 2e7f9b1975 feat(b5): 工程化外壳(文档层)—— 契约四件套 + 两本手册 + 第四把尺子
把 v3 spec §11.2 要求的整套文档层补齐,并把 spec §11.1 欠下的
「浏览器验收重跑」在真实上游 SPA 上补做完(内核浏览器 aix 驱动)。

新增文档:

- `docs/contract.md`(重写):**132 端点全表** + 4 种响应形状 + 数据模型 + 时间口径,
  唯一真源。端点表由 `scripts/check-contract.sh` 与源码注册路由**逐条对账**。
- `docs/decisions.md`(重写):逐条裁决 D1–D21。
- `docs/known-limitations.md`(重写):L1–L7,含 §5.4 权限敞开的显式条目(L4)。
- `docs/runbook.md`(新):怎么起 / 怎么冒烟 / 常见故障。
- `MIGRATION.md`(新):Java TDC ⇄ Rust 逐件翻译表 + 口令换算 + 数据 ETL。
- `HOWTO_ENTITY.md`(新):加一个实体(含子表挂载面)。
- `docs/ACCOUNT-LAYER.md`(新):`base_user` 账号层(官方双 md5 公式)。
- `docs/CONSOLE-ACCEPTANCE.md`(重写):**B5 重跑版**浏览器验收。

新增尺子(第四把 + 两把专项):

- `scripts/check-contract.sh`:端点表 vs 实际注册路由对账(132 == 132)。
- `scripts/check-citations.py`:文档里 `文件:行号` 引用逐条校验(139 条 0 失效)。
- `scripts/upstream-action-census.py`:上游动作端点普查(只读上游克隆,可复算)。
- `scripts/contract_probe.py`:动作端点形状探针(109 条逐条打过,零偏差)。

影响:

- **L5 数字纠正**:原先记的「111 条上游动作端点未实现」口径错了
  (`grep -rhoE` 只抓带参数的映射、且跨了全部 31 个控制器)
  ⇒ 真实数字 **109**(122 声明 − 11 CRUD 基线 − 2 聚合详情 = 26 形态 A + 83 形态 B)。
- **L7(新增)**:**26 条**上游动作端点**不会 404** ⇒ 被通用详情路由 `/{Entity}/{id}`
  吞掉(`src/tdc/controller/crud.rs:65-93`)⇒ GET 返回 **200 + `code:400`**、
  POST 返回 **405** ⇒ 上游前端下拉框静默变空。**只判 HTTP 状态码会误判成成功**。
- **CONSOLE-ACCEPTANCE §4 纠正**:服务目录 / 我的账单**已实现**(P4),
  失败点在**连接器身份闸门**(`f_tds_space_id` / `f_tds_connector_id` 为空 ⇒ 出向前 fail-closed),
  **不是** TDS NOOP 降级、也不是代理 404。
- `CLAUDE.md` 同步:目录树、红线、坑位表(「上游动作端点不 404」新增一行)。

实测:cargo test **246** 项全绿 0 failed(1 ignored)· smoke.sh PASS=80 FAIL=0 ·
check-boundary.sh exit 0 · check-entity.sh PASS=13 FAIL=0 ·
check-contract.sh 132 条端点一致 · check-citations.py 139 条引用 0 失效 ⇒ **六把尺子全绿**。

⚠️ 口径更正:此前(B4 提交信息与记忆文件)记的「172 lib + 62 集成 = 236」是**误数**
—— `src/` 与 `tests/` 自 B4 起未变,逐二进制实测就是 246 ⇒ 从本批起统一用 246。

Co-Authored-By: Claude Code <[email protected]>
2026-10-27 00:56:09 +08:00

192 lines
6.8 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
"""文档引用自检:B5 文档里的 `文件:行号` 引用是否**真的指向那个文件的那一行**。
用法:
python3 scripts/check-citations.py # 跑全部
python3 scripts/check-citations.py --docs a.md b.md
🔴 **查什么**(机械层):
① 引用的文件**存在**吗?
② 引用的行号**在文件范围内**吗?
③ 行号那行的内容**与引用上下文**有词面交集吗?(可选,靠 `--strict`)
🔴 **不查什么**:语义是否真的一致(那要人读)—— 本脚本只保证「不会指到空气」。
语义抽查由人做(v3 spec §8 B5 验收:「抽查 5 条属实」)。
"""
import argparse
import os
import re
import sys
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
# 上游只读克隆(Java TDC 真源)。文档里常写**相对片段**(如 `entity/ProductEntity.java`),
# ⇒ 建一张「片段 → 真实路径」的索引来解析。
UPSTREAM_ROOT = "/tmp/sswtdc-probe"
# 上游 j7 框架 jar 内的文件 —— **不在克隆里**(jar 是编译产物)⇒ 引用合法但查不了行号。
UPSTREAM_IN_JAR = {
"PasswordTokenGranter.java",
"AuthTokenSupport.java",
"InternalTokenSupport.java",
}
# 引用模式:`路径:行号` 或 `路径:行号/行号` 或 `路径:行号-行号`
# 路径里允许 `/ . _ -` 与字母数字;行号部分是数字。
REF = re.compile(
r"(?<![\w/])((?:[\w.\-]+/)*[\w.\-]+\.(?:rs|sh|md|sql|py|toml|ts|vue|java|yml|yaml))"
r":(\d+)(?:\s*[-/]\s*(\d+))?"
)
# 这些路径是「仓库外的上游真源」⇒ 只做存在性检查,不查行号(上游会变)。
UPSTREAM_PREFIXES = ("/tmp/", "~/")
_upstream_index = None
def upstream_index():
"""(片段 → 真实路径) 索引:按**路径后缀**匹配。"""
global _upstream_index
if _upstream_index is not None:
return _upstream_index
idx = {}
if os.path.isdir(UPSTREAM_ROOT):
for dirpath, _d, files in os.walk(UPSTREAM_ROOT):
for f in files:
full = os.path.join(dirpath, f)
rel = os.path.relpath(full, UPSTREAM_ROOT)
idx[rel] = full
# 也允许只写文件名
idx.setdefault(f, full)
_upstream_index = idx
return idx
def resolve_upstream(path_text):
"""在上游克隆里解析一个**相对片段**;找不到返回 None。"""
idx = upstream_index()
if path_text in idx:
return idx[path_text]
# 后缀匹配:`entity/ProductEntity.java` ⇒ 任何以它结尾的路径
cands = [p for rel, p in idx.items() if rel.endswith("/" + path_text)]
if len(cands) == 1:
return cands[0]
if cands:
return sorted(cands)[0]
return None
DEFAULT_DOCS = [
"docs/contract.md",
"docs/decisions.md",
"docs/known-limitations.md",
"docs/runbook.md",
"docs/ACCOUNT-LAYER.md",
"docs/CONSOLE-ACCEPTANCE.md",
"MIGRATION.md",
"HOWTO_ENTITY.md",
"CLAUDE.md",
]
def resolve(path_text):
"""把文档里写的路径解析成仓库内的真实路径。
文档里的路径常写成 `src/tdc/entity/mod.rs`(仓库根相对),
也可能写成 `../src/tdc/entity/mod.rs`(相对 `docs/`)⇒ 两种都试。
"""
cands = [
os.path.join(ROOT, path_text),
os.path.join(ROOT, "docs", path_text),
]
if path_text.startswith("../"):
cands.append(os.path.join(ROOT, "docs", path_text))
for c in cands:
if os.path.isfile(c):
return c
return None
def main():
ap = argparse.ArgumentParser()
ap.add_argument("--docs", nargs="*", default=None)
args = ap.parse_args()
docs = args.docs if args.docs else DEFAULT_DOCS
total = 0
bad = []
per_doc = {}
for doc_rel in docs:
doc_path = os.path.join(ROOT, doc_rel)
if not os.path.isfile(doc_path):
print("❌ 文档不存在:%s" % doc_rel)
bad.append((doc_rel, 0, doc_rel, "文档不存在"))
continue
with open(doc_path, encoding="utf-8") as fh:
lines = fh.read().splitlines()
n_ok = 0
for lineno, line in enumerate(lines, 1):
# 跳过代码块里的示意性引用?—— 不跳过,代码块里的引用同样要真。
for m in REF.finditer(line):
path_text, a, b = m.group(1), int(m.group(2)), m.group(3)
total += 1
if path_text.startswith(UPSTREAM_PREFIXES) or path_text.startswith("/"):
if not os.path.exists(os.path.expanduser(path_text)):
bad.append((doc_rel, lineno, m.group(0), "上游路径不存在"))
else:
n_ok += 1
continue
real = resolve(path_text)
if real is None:
# 上游片段(`TdcCrudController.java:83` 这种)⇒ 去上游克隆里找
base = os.path.basename(path_text)
if base in UPSTREAM_IN_JAR:
n_ok += 1 # j7 jar 内 ⇒ 行号查不了,但引用合法
continue
up = resolve_upstream(path_text)
if up is None:
bad.append((doc_rel, lineno, m.group(0), "文件不存在(仓内与上游都没有)"))
continue
real = up
else:
# 仓内命中 ⇒ 但同名上游文件也可能存在(`.java` 不会同名,忽略)
pass
with open(real, encoding="utf-8", errors="replace") as fh:
n_lines = sum(1 for _ in fh)
hi = int(b) if b else a
if a < 1 or hi > n_lines or hi < a:
bad.append(
(
doc_rel,
lineno,
m.group(0),
"行号越界(该文件共 %d 行)" % n_lines,
)
)
continue
n_ok += 1
per_doc[doc_rel] = (n_ok, len(lines))
print("文档引用自检")
print("-" * 60)
for doc_rel, (n_ok, n_lines) in per_doc.items():
print(" %-32s 引用 %3d 条 ✅(文档 %d 行)" % (doc_rel, n_ok, n_lines))
print("-" * 60)
print("合计 %d 条引用,%d 条失效" % (total, len(bad)))
if bad:
print("\n❌ 失效 %d 处:" % len(bad))
for doc_rel, lineno, ref, why in bad[:80]:
print(" - %s:%d %s → %s" % (doc_rel, lineno, ref, why))
if len(bad) > 80:
print(" … 还有 %d 处" % (len(bad) - 80))
sys.exit(1)
print("✅ 全部引用都指向真实存在的文件与行号")
return 0
if __name__ == "__main__":
sys.exit(main())