gen:docs 内联形状里的长枚举不省略,单个类型单元格可达约 900 字符(BulkActionDef.params 实例)

[os-zhuang]

PM 复核 PR #5339(#4912)时记录的观察类发现,未认领,按 PD#10 立案。不是该 PR 造成的缺陷,但被它放大到可见。

现象

formatType 渲染内联对象时,对已声明键做了数量省略(超过 4 个印 …),但对单个键的类型宽度不做任何约束。当某个键的类型是长枚举时,整段形状会撑爆表格单元格。

实例(#4912 修复后的 content/docs/references/ui/bulk-action.mdx,BulkActionDef.params 行):

({ name: string; label?: string; help?: string; type: Enum<'text' | 'textarea' | 'email' |
'url' | 'phone' | 'password' | 'secret' | 'markdown' | 'html' | 'richtext' | 'number' |
'currency' | 'percent' | 'date' | 'datetime' | 'time' | 'boolean' | 'toggle' | 'select' |
… 共约 50 个字段类型 … | 'vector'>; … } & Record<string, any>)[]

单个单元格约 900 字符。同一页的 BulkActionParam.type 行已经完整印过一次这份词表,所以内联位置的这一份是第二份拷贝。

定性(为什么不是 #4912 的返工项)

#4912 之前该单元格是 Record<string, any>[] —— 更短,但把已声明键整个抹掉,那是实打实的错误信息。修复后的单元格是正确但冗长的。净变化是正向的:作者现在能读到 name 与 type 是必填(且这两个键就排在最前面)。所以复核判为 ACCEPT,把宽度问题独立记录,而不是让一个正确的修复回退。

长枚举内联本身早于 #4912(任何带枚举键的内联形状都如此,如 gallery 的 coverFit),只是那些枚举短,没撑爆。

可能的修法(未验证,留给分诊)

• 内联位置的枚举超过 N 个值时印 Enum<'text' | 'textarea' | … +47>,并保留指向该 schema 自己那一行/页的完整词表(该页通常已有);
• 或对内联形状整体设字符预算,超出即退化为 object(与嵌套对象保持 opaque 的既有策略同源)。

两种都要逐页确认重生成 diff,与 #4912 同一文件面(packages/spec/scripts/lib/format-type.ts),⛔ 不得手改生成的 .mdx。

相关

#4912 / PR #5339(内联形状恢复声明键)、#5338(同一渲染器的数组括号缺陷,164 处)。三单同文件面,须串行,不得同批并行。

[claude]

发现分诊轮判级(#4949 纪律):持有(finding 留)。

为什么还留着:症状是正确但冗长,不是错误信息 —— PM 复核 #5339 时已定性:修复前该单元格是 Record<string, any>[](抹掉已声明键,实打实的错误),修复后是完整但约 900 字符。净变化正向,不构成返工项;长枚举内联本身早于 #4912,只是那些枚举短、没撑爆。今天没有用户被误导(信息是对的,只是难读)。

重启条件 / 顺带收的机会(本轮新增,请一并读):本单与 #5729(z.literal(2) 被渲染成带引号的 '2')同落 packages/spec/scripts/lib/format-type.ts 的 formatType,而 #5729 本轮已晋级 pm:queue(那一条是会被 AI 作者照抄的错误类型,不是宽度问题)。

⚠️ 因此:① 两单不得同轮派发(step 3 同文件串行);② #5729 的 dev 进到该文件后,顺带做内联位置的枚举省略(超过 N 个值印 Enum<'text' | 'textarea' | … +47> 并保留指向该 schema 的锚点)成本极低,建议在 #5729 的派发词里列为可选顺带项 —— 若顺带收了,本单直接关闭;若没收,本单继续持有,等下一次有人动 format-type.ts。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

Findings triage (#4949 discipline): promoted — finding → pm:queue. domain:spec-tooling unchanged.

The hold's own restart condition fired, and resolved against holding

The 2026-08-06 04:03Z hold made this issue's fate conditional on #5729: "若顺带收了,本单直接关闭;若没收,本单继续持有,等下一次有人动 format-type.ts". Both halves are now decidable:

• 参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 landed — PR fix(spec): 参考文档生成器按 typeof 决定字面量是否加引号,数值字面量不再被记成字符串 (#5729) #6127, merged 2026-08-07T03:14:32Z, commit 880d343 on origin/main.
• The optional side-task was not taken. Verified on origin/main, not from the PR description: packages/spec/scripts/lib/format-type.ts:195 still reads
  return \Enum<${prop.enum.map((e: unknown) => formatLiteral(e)).join(' | ')}>` — every member joined, no count cap, no elision. #6127 changed *quoting* (formatLiteralbytypeof`), not width.

So by the hold's own terms it "continues to hold, waiting for the next person to touch format-type.ts". The reason I am not applying that outcome: that condition has now been tested twice and failed twice. format-type.ts has had two riders since the width problem was recorded — 6e82972 (#5606 / PR #6058, retiredKey() tombstones) and 880d343 (#5729 / PR #6127) — and neither picked it up. A restart condition that two consecutive qualifying events did not trigger is not a restart condition; it is an indefinite hold with a plausible-sounding exit, which is the shape #4949 exists to drain ("囤积不是免费存档,是负利息存款").

Why promote rather than close (not planned)

The alternative to an unworkable hold is a verdict, and the verdict is not "won't fix":

• The audience makes width a correctness-adjacent property, not cosmetics. Reference pages are the authoritative input for AI authors (ADR-0033) — the same premise fix(spec): 参考文档生成器按 typeof 决定字面量是否加引号,数值字面量不再被记成字符串 (#5729) #6127 was just merged on. A ~900-character single cell is not wrong, but it is unreadable at the point of use, and the page already prints the full 50-term word list once on BulkActionParam.type, so the inline copy is a second copy of a list the reader can reach anyway.
• The direction is effectively settled, so this is not a decision card. The prior grader already assessed the elision option as 成本极低 and sketched it concretely (Enum<'text' | 'textarea' | … +47> plus the anchor to the schema's own row). The body's second option (a whole-shape character budget degrading to object) remains available to the implementer; both are local to one function, neither changes any contract.

Serialization: now clear, which is the other half of what changed

At hold time this file had two queued siblings. Both are gone:

• 参考文档生成器把数值字面量 z.literal(2) 渲染成带引号的 '2',数值型联合被记成字符串型 #5729 — closed/completed (PR fix(spec): 参考文档生成器按 typeof 决定字面量是否加引号,数值字面量不再被记成字符串 (#5729) #6127 merged).
• gen:docs 给「元素是联合类型」的数组少了括号,164 处参考页单元格声明了另一种类型(string | number[] ≠ (string | number)[]) #5338 (array-bracket defect, 164 cells, same renderer) — closed/completed.

origin/main (ee3bde1) shows no other open issue landing in format-type.ts. So the step-3 same-file constraint that partly justified the hold no longer applies, and the claiming lane has no predecessor to serialize behind.

For whoever claims it

• Landing site: packages/spec/scripts/lib/format-type.ts, the prop.enum branch at :195 (and, if the character-budget route is taken instead, the inline-object path that already caps key count at 4 but not per-key type width).
• ⛔ Regenerated .mdx only via pnpm --filter @objectstack/spec gen:schema && gen:docs — never hand-edit generated pages. Expect the diff to touch every page carrying a long enum inline, so review it page-by-page the way fix(spec): 参考文档生成器按 typeof 决定字面量是否加引号,数值字面量不再被记成字符串 (#5729) #6127 did.
• Not target:v17: docs-generator readability, not a shipped runtime surface.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-zhuang]

认领:PM 循环第 5 轮(spec-tooling 车道,座位登记 #6018)
会话:session_014wsZeReNTqiceBfLb5Pyf5
分支:claude/issue-5340-inline-enum-width
Worktree:objectstack-issue-5340
域:domain:spec-tooling
文件面:packages/spec/scripts/lib/format-type.ts(内联形状里的长枚举省略)+ packages/spec/scripts/format-type.test.ts + content/docs/references/** 重生成 + .changeset/*.md。⛔ 不碰 lib/file-description.ts(#5553+#6136 本轮并行)、build-docs.ts、build-schemas.ts、lib/zod-graph.ts、zod 文件。(越界即停,报告说明)

定价输入:#5729(PR #6127)已把成员渲染集中到 formatLiteral(),该 dev 的定价答复是「本单基本无影响、边际略易——成员字符串已归一化后交给你」;#5606(PR #6058)另已加入「内联摘要剔除墓碑」逻辑,与本单同处摘要装配面,读现状再定修法,⛔ 不沿用立单时的行号。

同文件让行:本单是 format-type.ts 的当前唯一在飞。

---

Generated by Claude Code

[os-zhuang]

验收:ACCEPT → PR #6211(转 ready 入队)

亲核:24 检查零非绿(ESLint / TypeScript Type Check / Check Changeset 均 success);文件面 3 代码 + 42 页重生成,零越界。

四点值得记:

1. 实测把缺陷放大了 7 倍:issue 举的 BulkActionDef.params 是 ~900 字符,而 261 成员的 error-code 词表被内联进 13 张 api 页的 80 行、单格 6242 字符。阈值(80)由语料测量定,不是拍脑袋——这正是派发令要求的形状。
2. 省略是位置感知的:只在 shape summary 内省略(新增 ctx.inShapeSummary,由装配处设置),词表自己的行、顶层 union 变体、Record<string, Enum<…>>、顶层枚举数组照旧印全。位置状态复用了 expanding 已有的机制,不是新发明。
3. 信息保全给了两层证据 + 一条诚实边界:计数明说隐藏了多少(⛔ 非静默截断);805 处内联中 457 处同页别处仍有完整列表(如 BulkActionParam.type 就在被省略行下两节);其余 348 处由计数承载、json-schema/ 为权威。并说清为什么标记不能做锚点——Zod 内联枚举,节点无 $ref、无名字可链。
4. 重生成方向单调且机器验证:42 页 144 行,每行都变短(0 行变长),共减 462,140 字符;每个改动行都带标记(0 例外)。>900 字符单元格 76→4,p99 643→247。

反向验证两个方向都跑了,两次预测都错、dev 把实测数字而非预测写进注释——继 #5729 之后本车道第二次这种自我更正,值得保持。

必答题回答得比问题更准:先纠正了问题的前提(三个关注点共享文件而非同一个装配处,#5729 的 formatLiteral 根本不在装配里),裁 A 不抽取,并给出未来抽取的触发条件是 ctx 包出现第二个位置标志,而不是关注点数量——采纳。

范围外另立两单,均 finding 未入队、且注明同文件必须串行:#6225(顶层长枚举 6092 字符单格,且该页无 ErrorCode 段,省略会真丢信息)、#6226(union 变体逐个印全)。⚠️ 两单与 #5553+#6136(PR #6224,173 页重生成)同属 docs-gen 面,下轮统筹串行。

---

Generated by Claude Code