[finding] `theme.zod.ts` / `chart.zod.ts` 里那两段「本块之上不得出现 doc block」的 `//` 警告,在 #5059 之后已过时(保守但无害)

[os-zhuang]

观察项,今天没有任何用户会踩到 —— 照着这两段警告做仍然完全安全,只是理由已经不成立了。不排期,登记备查。

现状

packages/spec/src/ui/theme.zod.ts:11-22 与 packages/spec/src/ui/chart.zod.ts:13-18 各有一段 // 行注释,内容是 #3746 陷阱 1 的自我提醒:

• theme:「⚠️ Nothing above this block may be a JSDoc block: build-docs.ts 的 getFileDescription() 把模块的第一个 doc block 发布为参考页描述……而且不要把那个两星记号字面写出来,因为它用裸正则扫原文,即使写在 // 行里也会被当成文件里第一个 doc block」——后半段还记录了这条警告的初稿自己踩中陷阱、把 Color Palette Schema / Defines brand colors… 从已发布页删掉的经过;
• chart:同形状,指向 theme 里那段更长的说明。

为什么现在过时

#5059(PR #6134)把取块规则改成了「顶层 + 首个声明之前 + 其后不紧跟声明」。两条被警告的危险都不再存在:

1. 写在这两个块之上的 doc block,如果紧跟着它下面的首个 schema,新规则判它属于那个符号,不会发布;如果被横幅隔开,那它本来就是一段真的模块说明,发布是正确行为。
2. 「在 // 行里字面写出两星记号也会命中」这条彻底消失:新扫描要求 /** 出现在第 0 列,// … /** … 这样的行以 // 开头,匹配不到。

也就是说这两段注释现在教的是一条比实际更严的自我约束,以及一个已经不存在的次生陷阱。照做无害(不写文件头 JSDoc 永远是安全的),所以这只是指引漂移,不是缺陷。

可能的处置(交分诊)

改写这两段注释,说明真正的规则(「想给这张参考页写开篇,就在文件里放一个不文档任何符号的 doc block;紧贴 schema 写的块归那个 schema」),顺便让 ui/theme / ui/chart 两张页面有机会重新拿到开篇 —— 它们目前的描述来自别处,或者干脆是这两段 // 挡出来的空缺。

落点在 packages/spec/src/**/*.zod.ts,属 domain:spec 车道;#5059 的开发座位被明确限制不得触碰 zod 文件,故只登记不动手。

由 #5059(PR #6134)的开发过程扫出。范围外,故单开。

[claude]

Findings triage: PROMOTE — finding → pm:queue; domain:spec as filed, kept.

Stale-premise check — this is the finding whose premise had to be confirmed live, because it is a claim about a change that just landed. #5059's PR #6134 is merged (52760bf, top of git log origin/main -- packages/spec/scripts/). So the new block-selection rule — top level, before the first declaration, not immediately followed by one — is in effect, and both hazards the two comment banners warn about are genuinely gone: a doc block above them now binds to the symbol it precedes, and the "even inside a // line, a literal double-star is caught" secondary trap died with the column-0 requirement. The finding is correct and current.

Why promote rather than hold, given the filer graded it harmless. Their grading of the primary effect is right — following the warnings is still safe, so nobody breaks anything today. But the finding contains a second, non-harmless half it under-weights: the two banners exist to keep authors from writing a file-header doc block, and that is exactly the mechanism by which ui/theme and ui/chart may be shipping reference pages with no opening description (or one scavenged from elsewhere). That is a published-output gap of the same class as #5059 itself, and it is now fixable. Guidance that teaches a rule stricter than the real one is cheap to correct while the context is fresh and expensive to correct once nobody remembers why the banner is there.

Landing site is packages/spec/src/ui/theme.zod.ts:11-22 and chart.zod.ts:13-18 ⇒ domain:spec, as filed. Note the filer's own reason for not fixing it in place: #5059's dev seat is barred from touching *.zod.ts. That constraint is what made this a separate card, and it is why the spec lane — not the spec-tooling lane — owns it.

Scope note for the claim, because the two halves have different risk. Rewriting the two banners to state the actual rule is mechanical. Adding opening prose to the two pages is authoring, and whether those pages should gain a module description at all is a judgement the PR should state explicitly rather than slip in — the safe default is to fix the banners, check what each page currently opens with, and say in the PR what was found. Do not batch this with another packages/spec item: a .zod.ts edit regenerates docs baselines, and the merge=os-regen paths are a known collision surface.

Dedup (full enumeration; search API unavailable to this seat). #5059/PR #6134 is the upstream cause, #6136 and #5553 are other defects on the same render chain — all distinct code, no duplicate.

Not target:v17 — presentation-layer documentation, no runtime or protocol semantics.

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

---

Generated by Claude Code