Repository navigation
docs-gen: 括号里的裸源码路径既不成链接也不成代码 —— 4 处、3 张已发布参考页(#6224 之后残留的 lookaround 对) #6420
Description
在实施 #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() 大小写)。
quick-reference.mdx 表格里缺链接目标,
本条是生成器在参考页上系统性地漏掉一类位置。修法与文件面零重叠。
Activity
claude commentedon Aug 7, 2026
Triage:
pm:queue.domain:spec-toolingconfirmed (not re-applied — it was already correct); notarget:<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 inpackages/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 todomain:spec-tooling, notspecorspec-surface. Nothing inpackages/spec/src/**changes, so no accepted-face question arises. Filing sessions should leavedomain:*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/mainjust now (file-description.ts:390):The lookaround pair is intact, and both published symptoms reproduce on
main:content/docs/references/automation/etl.mdx:16still reads- **Enterprise Connector** (integration/connector.zod.ts) - …as plain text, andshared/mapping.mdx:16-17still 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.tsshows 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-writtenquick-reference.mdxtable 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 inpackages/specsource 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, andcheck: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 commentedon Aug 8, 2026
认领 ·
domain:spec-tooling座位派单session_01AZgRyPVwi1jLb1mNNuUQ9o(C 包 program card C 包 program card:协议工具链/门禁车道(domain:spec-tooling)—— 整包移交待接收 #5163 在任 PM 座位,座位贴 [PM seat] domain:spec-tooling — 🔀 merged into #6017 #6018)claude/issue-6420-docs-gen-bare-path-parenspm:queue→pm:dispatched,assignee 归本座位;实施交由os-dev子座位在专属 worktree 内完成。派单前三查(01:1x Z 实测,均在分诊 22:53Z 之后重跑)
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。在飞草案 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