refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619） - #6804
Draft
os-project-manager wants to merge 3 commits into
Draft
refactor(spec): 三个手写 unrecognized_keys 错误映射折叠进 strictObject 的按集合取键 guidance（#6619）#6804os-project-manager wants to merge 3 commits into
os-project-manager wants to merge 3 commits into
Conversation
…bject guidance (#6619) - strictUnknownKeyError grows a set-keyed guidance form (KeySetGuidance + guidanceSets): one prescription per named key family, exact entry wins, declaration order among sets, one bullet per message, rename suppressed. - strictVisibilityError -> VISIBILITY_STRICT_OPTIONS (pattern-keyed set); strictWidgetAnalyticsError -> WIDGET_GUIDANCE_SETS (three sets); strictTenancyError -> exact guidance + history-slot explainer. - strictObjectError split out of strictObject so FormFieldBaseSchema registers with the audit WITHOUT closing the base (acceptance unchanged); spelled as a literal z.object so the strictness ledger keeps its site. - alias-integrity gains set-member/dead-entry, pattern-example and fold-closure checks (#6416 blind spot closed). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
This was referenced Aug 8, 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.
Fixes #6619（#6416 方向 2）
做了什么
把
packages/spec里仅存的三个手写$ZodErrorMap折叠进共享strictObject/strictUnknownKeyError模板，删除手工维护的模板副本，并让它们的别名指针与处方进入alias-integrity.test.ts的审计视野（#6416 命名的盲区，就此闭合）：252f71bd6）strictVisibilityErrorshared/visibility.ts:113VISIBILITY_STRICT_OPTIONS—— 模式取键的 guidance 集合（VISIBILITY_KEY_PATTERN）strictWidgetAnalyticsErrorui/dashboard.zod.ts:163WIDGET_GUIDANCE_SETS—— 三个枚举集合，按声明顺序strictTenancyErrordata/object.zod.ts:442guidance（两块墓碑）+history槽位承载常驻解释句核心决策：guidance 的按集合取键形态
dashboard.zod.ts的分支按集合成员资格取键（11 个退役 analytics 键共享一条迁移处方），精确键形态无法表达，visibility 的家族甚至不可枚举（模式匹配visibleWhenn/visibleIf/hiddenWhen/conceal…）。因此共享模板新增KeySetGuidance/guidanceSets：keys: 枚举列表 或RegExp（模式必须携带examples，审计据此判定模式没写错、没被 shape 遮蔽）；name: 具名（LEGACY_WIDGET_ANALYTICS_KEYS等）——刻意不渲染进消息：面向作者的拒绝应点名键，不点名装键的数组；每条处方在文案里自己把家族拼出来，这才是可读性所在。名字供声明处与审计失败文本使用。优先级规则（
strict-object.test.ts逐条钉住）：guidance条目永远胜过集合——更具体者裁决，新增集合永远偷不走已有手写答案的键；keySetMatches用String#search而非RegExp#test（/g模式下test有状态，同一键会交替命中/不命中；已有测试钉住）。盲区闭合的实测证据
同一探针矩阵在折叠前后各跑一次（
strictObjectDeclarations()全量强制遍历后计数）：252f71bd6）this view/page schemathis dashboard widget`tenancy`alias-integrity.test.ts新增三项：集合成员死条目检查（成员是已声明键 / 与精确 guidance 重复 / 两集合争抢一键均报错）、模式 examples 检查（必须命中自身模式且不是已声明键）、以及折叠闭合钉——把任何一个映射还原成手写$ZodErrorMap会直接红在门上。反向验证已实测：注释掉 widget 的guidanceSets→ 8 个测试红（含闭合钉），方向与预测一致（红），恢复后全绿。13 个顺序钉的处置（#6453 遗产）
零删除，全部随代码迁移：
view.test.ts4 个、dashboard.test.ts7 个、object.test.ts3 个（其中 1 个"无修复分支全消息钉"换了夹具键并新增同类钉，净增不减）。发射顺序契约（前言 → 修复通道 → 解释句最后）在模板里天然成立，钉子原样验证它。消息字节的刻意变化（顺序契约不变，逐处说明）
\n •bullet（原为内联空格拼接）——与包内所有已折叠面的处方通道一致；单行渲染器（os validate、CI 日志）本就把换行拍平，前言→修复→解释的顺序不动。tenantfield原答"is not atenancykey."（说了问题、没给修复），现答"Did you meantenantfield→tenantField?"；titel→title、colourVariant→colorVariant、labell→label同理。对读者严格变好。categoryField+component会静默丢弃隔离判词）——本折叠唯一的行为向变化，按声明顺序各一条 bullet，dashboard.test.ts有专钉。zzzzis not atenancykey." 的信息量已由前言"Unrecognized key(s) ontenancy"承载，解释句照常收尾（全消息钉）。七个 #6453 全消息变体中，处方文本本身逐字节保留；变的只是装配（bullet 化）与新增的修复通道。
objectUnknownKeyErrorImpl惰性构建的处置#5593 已经在
object.zod.ts里用声明顺序替代了 TDZ 惰性构建（UNKNOWN_KEY_GUIDANCE上移到ObjectSchemaBase之前）。本折叠照搬同一解法：TENANCY_MODES_EXPLAINER/TENANCY_RETIRED_KEY_GUIDANCE均在TenancyConfigSchema之前声明，无新增惰性表；OS_EAGER_SCHEMAS=1全量构建（check:generated→gen:schema）绿。一处刻意不机械折叠：
FormFieldBaseSchema它是 module-private base，唯一消费者
FormFieldSchema = base.extend({fields}).strict()在门口关门——#4001 批 18 刻意不关 base（关了就是接受面变化，超出本卡）。因此从strictObject拆出strictObjectError(options, shape)：只构建错误映射并注册进审计，不.strict()。该点位保持字面z.object(拼写，strictness ledger 的 AST 读数器继续看得见它（ui/view.zod.ts的 strip 计数 3 不动，counts 工件零再生）；extraKeys: ['fields']补上扩展层声明的键，feilds→fields的建议因此可用。接受面
逐字节不变——所有 schema 接受/拒绝的输入集合与折叠前完全一致（探针矩阵 32 个用例逐一比对；变的只有消息文本）。
strictObject的公共行为由既有测试全量回归。公开导出面（
./shared，gen:api-surface已再生）strictVisibilityError (const)（手写映射，本卡的删除对象）VISIBILITY_STRICT_OPTIONS (const)、KeySetGuidance (interface)、keySetMatches (function)、strictObjectError（经strict-object.ts，不在./sharedbarrel）验证
pnpm --filter @objectstack/spec test：346 文件 / 8877 用例全绿（合并origin/main@9b86cf696，含 [finding][spec]lifecycle.storageguidance says "Rotation does not reap by age … DROPs the oldest shard whole (O(1) reclaim)" — true only on SQLite; Postgres/MySQL take the age-basedrotation-fallbackleg #6631 后复跑）pnpm --filter @objectstack/spec typecheck：绿（test-typecheck 债务台账 58 文件 / 266 错，未新增）pnpm check:generated：10 个生成工件全部最新（含check:api-surface、check:strictness-ledger、eager schemas）check:exported-any/check:dual-source-exports：绿node scripts/check-type-check-coverage.mjs --re-measure（先 turbo 全量 build 闭包）：34 条台账复测，无一超上限node scripts/check-nul-bytes.mjs：绿guidanceSets→ 8 红（方向符合预测），恢复全绿消费半径清扫
按 #5046 的教训沿规则消费半径清扫：spec 之外（packages/、apps/、examples/）对三个旧符号名与全部旧消息字节的引用为零（唯一命中是 spec 自身注释与 ledger 证据行，均已更新）。changeset：
.changeset/fold-unrecognized-key-error-maps.md（patch）。🤖 Generated with Claude Code
https://claude.ai/code/session_018ffcE95NaMJcL9XJ9VDYgk
Generated by Claude Code