fix(spec): variant/doc 闸门对 YAML 是瞎的,而一条豁免正把这个盲区记录成文档缺口 - #4287
Merged
Conversation
…was recording that as a doc gap Audit of the seven `generated-reference-only` exemptions in variant-docs.json. That class is the weaker of the two the ledger uses: it does not claim a variant is un-authorable, only that nobody has written a guide for it — so each one is either a real gap or a mis-filing, and none had been re-checked since it was written. One was neither. protocol/objectui/widget-contract.mdx carries a 'Widget Source' section documenting all three of inline / npm / remote, and has all along — but in YAML examples, and the coverage matcher only accepted `type: 'npm'` or ``npm``. YAML does not quote scalars, so the gate saw nothing and the ledger recorded a doc gap that did not exist while the real gap — a matcher blind to half the repo's example dialect — stayed invisible. The matcher now accepts a whole YAML mapping line; that entry is governed, and the page is under the ratchet (5 → 6 governed). Two more were mis-labelled rather than gapped: tenant isolation strategy and settings-manifest handler are not-authorable, which their own reasons already said (operator-set, consumed by Setup/Studio). The rest are genuine gaps and now say so instead of naming the generated page as if that settled it. Connector authentication is called out as the one worth acting on: ADR-0097 makes it tenant-authored, and the repo has no hand-written connector page at all. Verified the new form bites and stays tight: removing one YAML variant line fails the gate; the same variant as a bare word in prose, or embedded mid-sentence, still does not count. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0147tNF4Snk7Ry1KGt4a5PY4
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 31, 2026 03:14
This was referenced Jul 31, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
起因
审计
variant-docs.json里 7 条generated-reference-only豁免。这是 ledger 两种豁免里较弱的一种 —— 它并不主张变体不可授权,只说「还没人给它写指南」。所以每一条要么是真缺口、要么是错归档,而它们自写下之后从未复核过。发现
一条两者都不是。
content/docs/protocol/objectui/widget-contract.mdx有一节 Widget Source,把inline/npm/remote三个变体逐个写了完整示例 —— 而且一直都有。但写法是 YAML,闸门的覆盖匹配器只认type: 'npm'(带引号)和`npm`(反引号)。YAML 不给标量加引号,所以闸门什么也看不见,ledger 于是记录了一个并不存在的文档缺口,而真正的缺口 —— 一个对仓库半数示例方言视而不见的匹配器 —— 始终不可见。这条豁免掩盖的是闸门自己的 bug,不是文档的问题。
改动
1. 匹配器补 YAML 形式(
scripts/check-variant-docs.mts)新增第三种「已提及」形式:整行的 YAML 映射(允许尾随
# 注释)。锚定到行首行尾,和带引号形式一样紧。2. widget implementation → governed,绑定
widget-contract.mdx。治理数 5 → 6,该页正式进入棘轮。3. 两条重分类为
not-authorable—— tenant isolation strategy 与 settings-manifest handler。它们自己的 reason 早就写着operator-set和consumed by Setup/Studio,只是标签跟内容不一致。4. 其余豁免把缺口写实,不再拿生成参考页当作已经回答了问题:
connectors:成为租户手写内容,auth type 明确是作者写的,但仓库里根本没有任何手写的连接器页(唯一的散文是flows.mdx里关于connector_action节点的一段)。另外顺手纠正了一处:窄版 union(EnvironmentArtifactSchema.metadata.connectors[].auth)缺oauth2是因为 authorization-code/refresh 属企业层(ADR-0015),不是因为部署产物做了收窄 —— 我最初的推断是错的,查了connector-auth.zod.ts才写实。flows.mdx里的schedule: { type: 'cron' }是另一个面(flow start 节点自己的 config;flow.zod.ts还专门给顶层schedule立了墓碑),既不记录也不治理这个 union,免得下一个人重复我刚做的排查。5. ledger 顶部
$comment增加审计说明,记录这次复核的结论与判据,让下一次复核有起点。验证
check:variant-docs通过:20 个 union → 6 governed / 14 exempt(此前 5 / 15)type: inline一行 → 闸门报1 variant(s) … never mentions: inline✅type: inline→ 仍然报缺失 ✅(证明没有宽到把散文当数据)@objectstack/spec276 文件 / 7169 用例全过packages/spec12 个闸门全 OK;check:role-word/check:doc-authoringOKcheck:api-surface与check:skill-examples一度报defineHook缺失 —— 查证是本地dist/陈旧:defineHook()已由 feat(spec): 补上 defineHook() 作者侧工厂,并修正 object.zod.ts 两处错误处方 (#4269) #4273 落地(即我在 补上 defineHook():hook 的作者侧工厂(defineDatasource 范式),并修正 object.zod.ts 两处引用不存在函数的错误处方 #4269 提的那份),pnpm build后两项恢复 OK。未提交任何重新生成的快照。范围说明
写一份完整的连接器授权指南远超本次审计 PR 的范围,所以我把它作为结论写进 ledger(连同「写好后绑上并删掉这条豁免」的指示),而不是顺手补一份半成品。
关联:#4001(母 issue)、#4177(闸门本体)、ADR-0097 / ADR-0015。
Generated by Claude Code