fix(spec): 参考页里写在括号中的裸源码路径重新成链接 —— 删掉 tokenizer 之后已无事可做的前后瞻对

[os-project-manager]

Fixes#6420

问题

参考页开篇那段模块描述由 packages/spec/scripts/lib/file-description.ts 渲染。其中把 JSDoc 里裸写的 *.zod.ts 路径改写成站内链接的那一步(renderProse()),正则两端各挂着一个前后瞻 —— 「前面不是左括号」和「后面不是右括号」。

这对前后瞻是 tokenizer 出现之前的产物,本意是「别去动已经是链接目标的路径」:](route) 恰好把那个路径夹在这两个字符中间。它从来表达不了这件事(前后瞻说不出「不在链接内部」—— 该文件模块注释里就写着这句),而 #6136 之后它更是无事可做:成形的链接是独立的 link token,这一步只会拿到 text token。

它仍在做的,是把作者自己写在普通括号里的每一个路径一并拒掉。那是散文,不是链接,于是这些路径既没成链接、也没回退成代码段,以纯文本发布在三张参考页上:

页面	原样
references/automation/etl:16	- **Enterprise Connector** (integration/connector.zod.ts) - …
references/integration/connector:17	- **ETL Pipeline** (automation/etl.zod.ts) - …
references/shared/mapping:16	- Integration connectors (integration/connector.zod.ts)
references/shared/mapping:17	- External lookups (data/external-lookup.zod.ts)

变更

删掉这对前后瞻,它们原本想守的不变量交还给 tokenizer 守。渲染成链接的前提没有放宽 —— 目标没有页面的路径照旧回退成代码段,所以括号位置永远不会产出 404。

四处的前后对照:

- **Enterprise Connector** (integration/connector.zod.ts) - System integrators
+ **Enterprise Connector** ([integration/connector.zod.ts](/docs/references/integration/connector)) - System integrators

放宽的实测半径:就是这四处,别无其他

分诊座位点名这是本单最需要量出来的数,也定了一条 stop-and-report。在修好的生成器上重跑 pnpm --filter @objectstack/spec gen:docs:

✅ Generated 231 files
content/docs/references/automation/etl.mdx | 2 +-
content/docs/references/integration/connector.mdx | 2 +-
content/docs/references/shared/mapping.mdx | 4 ++--
3 files changed, 4 insertions(+), 4 deletions(-)

231 个产物,3 个文件,4 行 —— 新成链接的位置全语料共 4 处,与 issue 点名的四处完全重合,零附带。三条新路由 /docs/references/{integration/connector, automation/etl, data/external-lookup} 均对应真实存在的 .mdx;顺带把 content/docs/references/** 里发出的全部 214 条站内路由逐条核了一遍,无死链(其中 14 条是分类首页,落在 分类/index.mdx)。

stop-and-report 条件未触发。

反向验证 —— 方向是先预言再跑的

预言:把守卫放回去,四条括号用例 + 语料条转红,其余全绿。实测三种放法结果一致:

放回的东西	结果
整对前后瞻	Tests 5 failed | 41 passed (46)
只放回前瞻	Tests 5 failed | 41 passed (46)
只放回后瞻	Tests 5 failed | 41 passed (46)

红的恒是同一组:四条括号用例 + 语料条。未括号用例、#6229 整块、以及「成形链接的目标不被二次改写」那条,三种放法下全绿 —— 最后这条正是本 PR 的立论:守不变量的现在是 tokenizer,不是被删掉的守卫,所以删它不会重开 #6136。

这一点也单独量过,没有只靠推断:把 bare-path 那步的 token 白名单从「只含 text」改成「text 加 link」(即模拟 tokenizer 保护失效),#6136 的两条与这条一起转红,输出正是注释里写下的那个形状(下面去掉了 vitest 的外层引号):

Expected: See [the fallback](../nowhere/absent.zod.ts) for now.
Received: See [the fallback](`../nowhere/absent.zod.ts`) for now.

测试

packages/spec/scripts/file-description.test.ts 新增 6 条单测(与 #6229 的 7 条并列)+ 1 条语料级断言:

• 括号内路径成链接 —— automation/etl 已发布那行的逐字输入;
• 括号收尾于行末 —— shared/mapping 形状(与上一条的闭合方式不同,后瞻两者都拒);
• 括号内带 ../ 前缀 —— docs-gen: 正文里裸露的 ../x.zod.ts 路径,../ 前缀被漏在链接外面 —— 2 张已发布参考页 #6229 与本单可组合;
• 括号内无路由路径回退成代码段,绝不发死链;
• 反空过守卫:同一条路径在括号外仍成链接,把唯一变量钉死在括号上(否则前四条大可围着代码段回退去写,写成全绿却什么都没证明);
• 成形链接的目标不被二次改写 —— 被删守卫真正的用意所在,现由 tokenizer 承担;
• 语料级:凡本步能匹配的路径,不得以裸文本留在括号里(在渲染结果上判,不读 .mdx —— check:docs 会忠实复制产物,三处已发布症状正是这样一路绿过来的)。

与在飞 #6473 的同页相撞

#6473(#6383)在本单实施途中于 01:38Z 落地,与本单同改 content/docs/references/integration/connector.mdx。⛔ 未做文本合并:合 main 后在合并树上整体重跑 gen:schema 与 gen:docs(#4675 第四步,#6224 / #5552 有先例)。仓库自带的 regen merge driver 也正是这样拒绝文本合并并给出这条指令的。packages/spec/src/integration/connector.zod.ts 本单一字未碰。

合并后同页实测两侧效果俱在:#6473 的「What this layer does NOT provide」一节在第 27-43 行;本单的第 17 行已成链接。并逐行复核 #6473 新增散文里的路径(第 43 / 54 / 80 / 106 / 113 行)全在反引号内,是 code token,本单放宽够不着 —— 此处为实测,非假定。

门禁(全部前台执行,持容器级 flock 锁,--filter 限定范围)

在合并后的树上:

pnpm --filter @objectstack/spec test → Test Files 339 passed (339) / Tests 8706 passed (8706)
pnpm --filter @objectstack/spec typecheck → tsc --noEmit + check:scripts-typecheck + check:test-typecheck 全绿
pnpm --filter @objectstack/spec check:docs → 231 generated files in sync with packages/spec
pnpm --filter @objectstack/spec check:generated → All 10 generated artifacts are up to date
node scripts/check-nul-bytes.mjs → OK(6095 tracked text files,无裸 ASCII 控制字节)
pnpm docs:build → 全语料 MDX 编译通过,390+ 路由预渲染
eslint(两个改动文件,--no-inline-config) → exit 0
check:doc-authoring / docs-audit-scope / role-word / quick-reference-counts
/ empty-changeset / release-notes / adr-anchors → 全 PASS

Tests 8706 对得上账:main 上是 8699,本单新增 6 + 1 = 7 条。

check:generated 首跑曾报 api-surface/ 陈旧 —— 那是新 worktree 未 build 的假红(gen:api-surface 直接以 Could not resolve module symbol … Is the package built? 失败)。pnpm --filter @objectstack/spec build 后复跑 10 项全绿,api-surface/ 一个字节未变 —— 本单不碰 packages/spec/src,结构上不可能影响它。

另在构建产物里核了终态:.next/server/app/en/docs/references/shared/mapping.html 与 automation/etl.html 里,这几处已是真正的 a href 锚点。

交付物取舍

• 带 changeset(patch,@objectstack/spec):有读者可见的产物 —— 三张已发布参考页上四处纯文本变成可点链接。
• ⛔ 未碰 content/docs/releases/。
• 生成物为 gen:docs 纯输出,未手改一个字节;源码修改与重生成分属不同 commit(合并树上的重跑再单列一个)。

顺带扫出、未在本 PR 修

#6484 —— 同目录裸路径(无分类段,如 auth.zod.ts)从来不成链接:改写正则与 sourcePathToDocsRoute() 两侧都要求路径里有一个 /,所以这类路径带不带括号都以纯文本落地。实测模块描述管线内 9 处 / 4 张已发布页,另有 2 处在 schema 级 description 那条别的管线里。已按 Prime Directive #10 独立立单(未认领、未打标,留给分诊),不在本 PR 内顺手修 —— 它要动的是 FileDescriptionContext 的入参契约,本单一个字节都不碰那个接口。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01AZgRyPVwi1jLb1mNNuUQ9o

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 8, 2026 1:51am

[github-actions]

📓 Docs Drift Check

No hand-written docs reference the 0 changed package(s). ✅

[os-project-manager]

PM 验收:通过,转 ready for review。(domain:spec-tooling 座位,session_01AZgRyPVwi1jLb1mNNuUQ9o,派单见 #6420)

不取信实施报告,以下四项由本座位独立复核:

1. 放宽半径与主张自洽。 整个 PR 6 个文件,生成物恰好 3 张 / 4 行(etl +1/−1、connector +1/−1、mapping +2/−2)—— 与「新成链位置全语料共 4 处、与 issue 点名的四处完全重合」这个主张互相印证。stop-and-report 条件未触发,三条新路由指向真实页面。
2. docs(spec): connector.zod.ts 模块 JSDoc 停止宣传已退役的出站限流与映射转换 #6473 同页相撞按派单要求收口。integration/connector.mdx 在 diff 里只有 1 行变化 —— 若发生过文本合并,docs(spec): connector.zod.ts 模块 JSDoc 停止宣传已退役的出站限流与映射转换 #6473 的整节散文会以增删行的形式出现在本 PR 的 diff 里;它没有,说明那部分已在 base 中,合并树上整体重跑是真的跑了。packages/spec/src/integration/connector.zod.ts 零改动,与派单一致。
3. 测试不是空过。 「同一路径在括号外仍成链接」这条反空过守卫在位 —— 没有它,前四条大可围着代码段回退去写,全绿却什么都没证明。语料条判在渲染结果而非 .mdx 上(理由正确:check:docs 忠实复制产物,三处已发布症状正是这样一路绿过来的),且排除 ]( 开头的链接目标,不会自我豁免。反向验证的方向是先预言后跑,三种放法(整对 / 只前瞻 / 只后瞻)红同一组 5 条,而 docs-gen: 正文里裸露的 ../x.zod.ts 路径,../ 前缀被漏在链接外面 —— 2 张已发布参考页 #6229 整块与「成形链接目标不被二次改写」恒绿 —— 后者正是删守卫安全性的承重证据,且它自身还用「把 token 白名单改成 text+link」的变异单独量过,不是推断。
4. 交付物边界。 未碰 content/docs/releases/(硬规则),未碰 packages/spec/src/**(本座位 scope 外),changeset 在位(patch,@objectstack/spec),生成物为纯输出、源码改动与重生成分属不同 commit。

CI 26/26 全绿,含 ESLint job 携带的那组家族门禁(本地 pnpm test 看不到)。

一处记录在案的假红,值得其他座位复用:新 worktree 首跑 check:generated 报 api-surface/ 陈旧,成因是 gen:api-surface 读的是已构建的 dist/*.d.ts,未 build 时直接以 Could not resolve module symbol … Is the package built? 失败;pnpm --filter @objectstack/spec build 后 10 项全绿且 api-surface/ 一字节未变。不是漂移。

顺带扫出的 #6484 处理正确:独立立单、未认领未打标留给分诊,且明确不在本 PR 内顺手修 —— 它要动 FileDescriptionContext 的入参契约,本单一个字节都不碰那个接口。该卡与本 PR 同文件同函数,本座位已登记为须待本 PR 合入后方可派发。

---

Generated by Claude Code