ci(docs): 符号锚点必须真实存在 —— #857 换过去之后没人看的那一格(21/21 起点绿,三种坏法各自见红)

[vansin]

ci(docs): 符号锚点必须真实存在 —— 补上 #857 换过去之后没人看的那一格

#857 把 docs 里的行号 pin 换成了符号锚点。换得对:那 13 条行号逐条对下来
13 条全错 —— loadProfile 实际在 cli.ts:1274(doc 写 228),runCommand
在 5812(doc 写 2044),ensureMcpJson 指的那一行是空行。而它们全都长得像
有效引用:格式对、行号在文件范围内、点开能打开,所以读的人不会怀疑。

但换完之后留了一格没人看:符号锚点不会因为「上面插了几行」失效,却会因为
改名而失效,而失效之后同样没有任何东西会喊。 #843 那道门在数行号 pin(守住
不再变多),符号锚点在变多,一直没有对应的门。

判据:每一条 搜 \X`` 里的 X,必须在它左边最近的那个源码链接指向的文件里
逐字存在。两类失败都报 —— 找不到(改名/删除/写错),以及前面根本没有链接
(无法判定它指哪个文件,这本身就是缺陷)。

起点(与手工核对一致)

checked 21 symbol anchor(s) across 262 tracked doc(s); 21 resolved
every symbol anchor exists in the file it names.

21 这个数是先手工数出来的,再让脚本跑 —— 两边对上才用。

见红(三种坏法,三种输出,互不相同)

A 改一个锚点为源码里不存在的名字   → rc=1  "not found in 'agent-network/bin/cli.ts'"
B 去掉锚点前面的链接               → rc=1  "no source link precedes this anchor"
C 把扫描范围改成一个不存在的目录   → rc=2  "0 tracked .md … 扫描范围塌了"

三份输出的 md5 两两不同。C 是分母承重:🔴 这道门最可能的坏法不是判据写错,
是一条都没扫到然后打印一片绿 —— 那种假绿和真绿逐字相同。所以扫到 0 个 md
或 0 条锚点一律 exit 2,让「没问题」和「没有看」在输出上长得不一样。

变异做完全部还原:cmp docs/architecture.md 与 main 逐字节相同。

🔴 刻意不加 paths 过滤

这道门的主要失效场景是有人在 cli.ts 里把一个函数改名,不是有人改了 doc。
按 docs/** 过滤的话,改源码的 PR 不会触发它 —— 门在、判据也对,但在最需要它
的那一类改动上永远不会被触发。整个脚本跑完不到一秒,省这点没有意义。

--selftest 8 条,含「无锚点文本 → 计数必须为 0」。job 名 doc-symbol-anchors
全仓唯一(25 个 job,25 个不同的名字)。

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[vansin]

CI 里这道门真的跑了,而且数字对得上(日志已滤掉命令回显,下面是程序输出):

selftest: 8/8 ok
checked 21 symbol anchor(s) across 262 tracked doc(s); 21 resolved to a readable source file
every symbol anchor exists in the file it names.

21 这个数是我先手工 grep 数出来的,再让脚本跑 —— 两边对上才用。🔴 新工具的第一次输出必须对照一个已知答案,否则「它说 21」和「它只会说 21」在输出上是一样的。

合了。