#!/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"(? 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())