Repository navigation
docs-gen: 模块 JSDoc 按行拆成段落,跨行的行内代码跨度被切断 —— 5 张参考页正文露出裸反引号和 \{ 转义痕迹 #5553
Description
在实施 #5452(.describe() 的花括号转义)时,给生成语料做配平扫描顺带发现的另一条独立缺陷。不同函数、不同根因,故单独立单:#5452 改的是 escapeMdxDescription 的定界符配对,本单在 getFileDescription。
现象(origin/main @ 5acb93add,#5452 的 PR #5550 重生成后依然如此)
packages/spec/scripts/build-docs.ts 的 getFileDescription 把模块级 JSDoc 的每一行用 \n\n 连接:
.map(line => line.replace(/^\s*\*\s?/, '').trim())
.filter(line => line)
.map(line => line.replace(/^@see\s+/, 'See also: '))
.join('\n\n') // ← 每个源码行 = 一个段落于是任何跨源码行的 Markdown 构造都被段落边界切断。行内代码跨度不能跨空行,所以两边的反引号都当字面量渲染出来。
扫描生成语料(排除围栏代码块,统计反引号数为奇数的行)得 10 行 / 5 张页面 = 5 个被切断的跨度:
content/docs/references/automation/flow-function.mdx:22,24
content/docs/references/security/explain.mdx:8,10
content/docs/references/shared/expression.mdx:16,18
content/docs/references/system/doc.mdx:24,26
content/docs/references/system/settings-client.mdx:10,12
最直观的一处,automation/flow-function.mdx:22-24:
variable so a later DECLARATIVE node persists it (`update_record fields: \{
ai_category: '\{aiResult.ai_category\}' \}`). Data I/O stays on the flow graph.
读者看到的是两个段落,中间一个孤立的反引号开头、另一个反引号结尾 —— 而源码里它本是一个完整的行内代码例子:
// packages/spec/src/automation/flow-function.zod.ts:13-15
* variable so a later DECLARATIVE node persists it (`update_record fields: {
* ai_category: '{aiResult.ai_category}' }`). Data I/O stays on the flow graph.security/explain.mdx:8 同理把 `explain(principal, object, operation)` 从中间劈开。
为什么 \{ 会露出来(次生现象)
同一函数末尾对花括号做无差别反斜杠转义:
.replace(/\{/g, '\\{').replace(/\}/g, '\\}') // Escape { } for MDX它不区分「在代码跨度里」还是「在正文里」。跨度没被切断时,\{ 落在行内代码内部,而代码跨度里反斜杠不是转义符,读者就会看到字面的 \{。上面 5 处因为跨度已经断了,\{ 反而当正文转义正常渲染成 { —— 两个缺陷互相掩盖,所以肉眼扫过去只觉得「反引号有点怪」。
注意这条转义路径和 #5452 修的是两条不同的路径:.describe() 走 escapeMdxDescription(包进行内代码),模块 JSDoc 走这里(反斜杠转义)。#5452 的修复不触及本单。
修法方向(未验证)
两点都在 getFileDescription 里:
- 段落切分应按 JSDoc 的空行切,而不是按每个源码行切 —— 即连续非空行合并为一段(用空格连接),空行才开新段。这同时修好跨行的链接、粗体等其它构造。
- 花括号转义应像
escapeMdxDescription那样感知反引号:已在行内代码里的花括号不需要任何转义(代码跨度天然不被 MDX 当表达式解析),不在代码里的才需要处理。
改完重跑 pnpm --filter @objectstack/spec gen:docs,验收:上面的奇数反引号扫描归零,且 flow-function.mdx 那句恢复成单个完整的行内代码例子、不含 \{。
影响面
5 张已发布参考页的正文段落,读者今天访问就能看到。纯展示层,无运行时/协议语义。
Activity
os-zhuang commentedon Aug 5, 2026
分诊:
pm:queue+domain:spec。packages/spec/scripts/build-docs.ts的getFileDescription(origin/main:211 实测仍在),连带重跑gen:docs的生成物 —— packages/spec 及其生成物归domain:spec。(注:domain:spec-tooling车道边界仍在决策箱 域标签词表有两个未入表条目:domain:spec-tooling(在用,文件面与 devx 完全重叠)与domain:ui(一例,与repo:objectui重复) #5469 待裁,现行域表下 spec 脚本归 spec 座位。)flow-function.mdx恢复完整行内代码),可直接派发。.describe()里的{{var}}在生成的参考文档里被转义成 `+ 游离的}`(main 上现存 3 处) #5452/PR fix(spec): docs-gen 把嵌套花括号整对包进行内代码,不再切成半对 (#5452) #5550 无重叠:两条不同转义路径(escapeMdxDescriptionvsgetFileDescription),fix(spec): docs-gen 把嵌套花括号整对包进行内代码,不再切成半对 (#5452) #5550 落地后本缺陷实测仍在,issue 正文已自证。getFileDescription/ docs-gen 段落切分相关影子单。本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
os-zhuang commentedon Aug 6, 2026
疑似域误标：本单落点在 docs-gen 生成器（
packages/spec/scripts/**，C 包 #5163 文件面），不触packages/spec/src/**/*.zod.ts，建议改标domain:spec-tooling——交分诊座位定夺。背景：维护者 2026-08-06 拍板 spec 车道缩盘方案，见 #5837。Generated by Claude Code
os-zhuang commentedon Aug 6, 2026
标签落实（维护者 2026-08-06 指示，session_01LeEfA7CFwbJb7JJmXm2KM3）：按 08-06 转席建议执行
domain:spec→domain:spec-tooling（缩盘方案 #5837 已拍板，落点 docs-gen 生成器）。Generated by Claude Code
os-zhuang commentedon Aug 7, 2026
认领:PM 循环第 5 轮(spec-tooling 车道,座位登记 #6018)
会话:
session_014wsZeReNTqiceBfLb5Pyf5分支:
claude/issue-5553-file-description-renderingWorktree:
objectstack-issue-5553域:
domain:spec-tooling与 #6136 打包为同一次派发(一个 PR,双
Fixes):落点核实后两单同落packages/spec/scripts/lib/file-description.ts(#6134 今日新建的描述提取/渲染模块),且同属一条渲染链上的两个独立缺陷。分开派会各付一次content/docs/references/**重生成并互相埋 diff——打包成本更低,duplicate-fix-guard 只拦「两个 PR 声明同一 issue」,一个 PR 声明两个 issue 合规。文件面:
packages/spec/scripts/lib/file-description.ts+packages/spec/scripts/file-description.test.ts+content/docs/references/**重生成 +.changeset/*.md。⛔ 不碰build-docs.ts(#5853 下轮)、lib/format-type.ts(#5340 本轮并行)、build-schemas.ts(#5371 本轮并行)、zod 文件。(越界即停,报告说明)Generated by Claude Code
chore(docs): 合入 main 后整体重跑 gen:schema && gen:docs (#5553, #6136)