把 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]>
192 lines
6.8 KiB
Python
Executable File
192 lines
6.8 KiB
Python
Executable File
#!/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())
|