docs-gen: 括号里的裸源码路径既不成链接也不成代码 —— 4 处、3 张已发布参考页(#6224 之后残留的 lookaround 对)

[os-zhuang]

在实施 #6229(PR #6408,../ 前缀漏在链接外面)时顺带扫出,非本单范围,按 Prime Directive #10 独立记录。⛔ 未自我认领。

观察

packages/spec/scripts/lib/file-description.ts 的 bare-path 改写步骤,正则两端各带一个前后瞻:

/(?<!\()( … )\b(?!\))/g

它们的作用是「前面不是左括号、后面不是右括号」。于是任何写在圆括号里的裸源码路径一律不被改写 ——
既不成链接,也不成行内代码,原样落成纯文本。而语料里其它位置的裸路径都会变成链接或代码段。

已发布的 4 处(路由都存在,不是死链问题,是根本没链)

页面	行	文本	对应参考页
content/docs/references/automation/etl.mdx	16	- **Enterprise Connector** (integration/connector.zod.ts) - …	/docs/references/integration/connector ✅ 存在
content/docs/references/integration/connector.mdx	17	- **ETL Pipeline** (automation/etl.zod.ts) - …	/docs/references/automation/etl ✅ 存在
content/docs/references/shared/mapping.mdx	16	- Integration connectors (integration/connector.zod.ts)	/docs/references/integration/connector ✅ 存在
content/docs/references/shared/mapping.mdx	17	- External lookups (data/external-lookup.zod.ts)	/docs/references/data/external-lookup ✅ 存在

源分别在 packages/spec/src/automation/etl.zod.ts:18、integration/connector.zod.ts:20、
shared/mapping.zod.ts:15-16。

讽刺的是 etl.mdx 同一页上,{@link} 写法的那条是链接(#6136 修的那条),而正上方括号里的同一个
integration/connector.zod.ts 是纯文本 —— 同一页、同一个目标、两种待遇。

为什么这对 lookaround 现在是残留

它们是 #6136 之前的防嵌套手段:那时改写器直接跑在已含 markdown 链接的整串上,只能靠「前面不是 (、
后面不是 )」勉强躲开链接的 ](route) 部分。PR #6224 把这一步改成分词器方案后,已成形的链接是
link 段、行内代码是 code 段,本步骤根本看不到它们 —— 该文件模块注释自己写着「lookaround 表达不了
『不要嵌在链接里』」。防嵌套的职责已经整体转移,这对 lookaround 只剩下误伤圆括号里的正常散文这一个
实际效果。

(?<!\() 与 (?!\)) 是一对,#6229 只动中间的前缀与 \b,两端一字未改,所以 PR #6408 落地后这条依旧成立。

复现

// 现状:无匹配,整串保持纯文本
'see (system/cache.zod.ts) here'.replace(/(?<!\()((?:\.\.\/)*\b[\w-]+\/[\w.-]+\.zod\.ts)\b(?!\))/g, 'X')

为什么没有随 #6229 一起修

不同的输入形态、不同的成因(#6229 是匹配起点,这条是匹配两端的守卫),而且删掉这对 lookaround
是放宽改写器的行为面 —— 会让此前从不成链接的一类位置开始产出链接,超出 #6229 的验收范围。契约优先:
该在产出侧(改写器)裁决要不要放宽,不该在别处兜底。

影响面(据实,不夸大)

无运行时影响,check:docs / check:generated / 全语料 MDX 编译在现状下全绿 —— 产物忠实复现了
改写器的行为,门禁看不见这类「本该有链接却没有」。代价是 3 张已发布页上 4 个导航出口缺失。
不自评级别,留待分诊。

去重

已翻过三仓 336 条 open issue/PR,按 file-description、docs-gen、lookahead/lookbehind、裸露、
链接 本地匹配。同族三单都是别的输入形态,不重复:#6136(untitled {@link} 嵌套链接)、
#6229(../ 前缀,本单母体)、#5853(getCategoryTitle() 大小写)。

⚠️ 与 #6373 方向相似但不是一回事:那条是手写的 quick-reference.mdx 表格里缺链接目标,
本条是生成器在参考页上系统性地漏掉一类位置。修法与文件面零重叠。

[claude]

Triage: pm:queue. domain:spec-tooling confirmed (not re-applied — it was already correct); no target:<major>.

This card entered the sweep through disjunct 3 — it carried a routing label but no pm-state, so it was invisible to both views (the queue reads pm-state, lane claiming reads domain:*) for ~5.5 hours. The routing label is right and stays: the fix lands in packages/spec/scripts/lib/file-description.ts, which is machinery around the contract, not the contract's own text or accepted set — standing instruction ③ routes generators/gates/lint to domain:spec-tooling, not spec or spec-surface. Nothing in packages/spec/src/** changes, so no accepted-face question arises. Filing sessions should leave domain:* to this seat (single producer) even when they know the answer; the half-labelled state is what costs the hours.

Classification — concrete defect, one-line landing site, executable repro. Confirmed verbatim on origin/main just now (file-description.ts:390):

s.replace(/(?<!\()((?:\.\.\/)*\b[\w-]+\/[\w.-]+\.zod\.ts)\b(?!\))/g, …)

The lookaround pair is intact, and both published symptoms reproduce on main: content/docs/references/automation/etl.mdx:16 still reads - **Enterprise Connector** (integration/connector.zod.ts) - … as plain text, and shared/mapping.mdx:16-17 still carries both bare paths. Four sites, three published pages, all four target routes exist.

Stale-premise check — the premise survives its own parent. git log origin/main -- packages/spec/scripts/lib/file-description.ts shows exactly one commit since filing: e8dc61e (#6229 via PR #6408, "../ 前缀回到链接里面"). That PR moved the match start; both guards are byte-identical to what the body quotes, so #6229 landing does not retire this.

Dedup — four near neighbours checked, none overlapping. #6136 (untitled {@link} nesting), #6229 (the parent, now merged), #5853 (getCategoryTitle() casing) are different input shapes in the same rewriter. #6373 is the closest call and is genuinely a different issue: it is a hand-written quick-reference.mdx table missing link targets, whereas this is the generator systematically skipping a position class; zero overlap in file面 or fix. #6383 / #6413 are prose-face cards in packages/spec source and belong to the surface lane.

One note for the implementing seat, from the body's own reasoning. Deleting the guards widens the rewriter — positions that never produced links start producing them corpus-wide. #6224's tokenizer already makes the guards redundant for their original anti-nesting purpose (link and code segments are separate tokens this step never sees, as that file's own module comment states), so the widening is the intended restoration rather than a new behaviour. It still needs verifying at that scope: regenerate and check that every newly linkified bare path resolves to a real reference route, not just the four named here. If regeneration turns up bare paths whose routes do not exist, that is a stop-and-report, not a judgement call to make in the PR.

target:<major> withheld. Four missing navigation links on three reference pages is a presentation defect on a shipped surface: no data is wrong, nothing silently drops, no documented instruction fails when followed, and check:docs / check:generated / full-corpus MDX compilation are green because the artifacts faithfully reproduce the generator. That is the "坐下一班车" side of the binary criterion.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

认领 · domain:spec-tooling 座位派单

• 会话:session_01AZgRyPVwi1jLb1mNNuUQ9o(C 包 program card C 包 program card:协议工具链/门禁车道(domain:spec-tooling)—— 整包移交待接收 #5163 在任 PM 座位,座位贴 [PM seat] domain:spec-tooling — 🟢 在任 (session_01AZgRyPVwi1jLb1mNNuUQ9o) #6018)
• 分支:claude/issue-6420-docs-gen-bare-path-parens
• 状态:pm:queue → pm:dispatched,assignee 归本座位;实施交由 os-dev 子座位在专属 worktree 内完成。

派单前三查(01:1x Z 实测,均在分诊 22:53Z 之后重跑)

1. 陈旧前提(逐路径 list_commits):packages/spec/scripts/lib/file-description.ts 最新提交仍是 e8dc61e(17:20Z,docs-gen: 正文里裸露的 ../x.zod.ts 路径,../ 前缀被漏在链接外面 —— 2 张已发布参考页 #6229 via PR fix(spec): 正文里裸露的源码路径,../ 前缀回到链接里面 (#6229) #6408)—— 即分诊已计入的那一条,此后零新提交;content/docs/references/automation/etl.mdx 与 shared/mapping.mdx 最新提交同为 95c4227(12:50Z,fix(spec): docs-gen 按 JSDoc 原有行布局渲染模块描述,并让裸路径改写跳过已成型链接 (#5553, #6136) #6224)。前提未被任何后续合入retire。
2. 竞态复读:本条评论写入前重读全部评论,仅有 22:53Z 分诊那一条且明示「不构成认领」;无更早的其他会话认领,assignee 此前为空。
3. 文件不相交:本座位在飞 dev 为 0。跨座位扫描发现一处生成物重叠,已写入派单简报而非阻断 —— 见下。

⚠️ 生成物重叠告知(不构成阻断)

在飞草案 PR #6473(01:08Z 开,作者 qq9340100)改 packages/spec/src/integration/connector.zod.ts 的模块 JSDoc,并随动重生成 content/docs/references/integration/connector.mdx。本单要重跑 gen:docs 全语料,而 integration/connector.mdx 正是「另见」行带路径的那类页面(#6136 点名过它),两侧极可能同页相撞。

处置按本仓既有成规,已写进派单:生成物不做文本合并。若 #6473 先落地,合 main 后在合并树上整体重跑 gen:schema && gen:docs(#4675 第四步,#6224/#5552 均有先例),而不是把两边产物拼接;connector.zod.ts 源文件本单一字不碰。#6473 新增散文里的路径全部带反引号(码段 token),不受本单放宽影响,但合并后需实测复核。

分诊那条 stop-and-report 原样保留:放宽后重生成,若出现「新成链但目标路由不存在」的裸路径,停下报告,不在 PR 内自行判断。

---

Generated by Claude Code