feat(spec)!: DashboardWidgetSchema.strict() — 拒绝未声明的 widget 键 (framework#3251)#3316
Merged
Merged
Conversation
…t keys (framework#3251) The ADR-0021 analytics endpoint. DashboardWidgetSchema now rejects any undeclared top-level key instead of silently stripping it, moving a class of author error (a hallucinated or legacy key that renders as a silent no-op) from fallible human review to deterministic CI. options: z.unknown() stays the escape hatch for renderer-specific extras. - A custom error map names the offending key(s) and, when a key is a removed pre-ADR-0021 inline-analytics key (object/categoryField/valueField/aggregate, pivot rowField/columnField) or an objectui-internal prop (component, inline data), points the author at the dataset shape (dataset + dimensions + values). - Recorded as protocol-16 migration step16 (dashboard-widget-strict-unknown-keys), mirroring protocol-15 step15's strict flip on the form/page schemas (ADR-0089 D3a). PROTOCOL_VERSION is NOT bumped here — the release train's Version-Packages PR sets it to 16.0.0; until then step16 is inert (composeMigrationChain caps at PROTOCOL_MAJOR). - lint: the widget-legacy-analytics-* rules are kept as the friendly bridge on the raw-config lint/doctor paths (strict preempts them on parsed paths); doc comment updated. Shipped as minor per the launch-window policy, riding the pending 16.0.0 train. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T4qmiXd4wjnJMLt18Cir1Y
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 103 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 19, 2026 18:06
Closed
5 tasks
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.
Closes #3251
背景
ADR-0021 分析迁移的终点。平台模式是「AI 写元数据、人类审核」，而被静默剥离的未声明键正是人类审核最容易漏掉的静默 no-op。本 PR 让
DashboardWidgetSchema拒绝任何未声明的顶层键，把这类错误从易错的人工审核移到确定性的 CI 硬报错。options: z.unknown()仍是渲染器额外配置的逃生舱。改动
packages/spec/src/ui/dashboard.zod.ts—DashboardWidgetSchema加.strict()+ 自定义 error map。错误信息会指名违规键，并在键属于已移除的 pre-ADR-0021 内联分析键（object/categoryField/valueField/aggregate，透视表rowField/columnField）或 objectui 内部 prop（component、内联data）时，引导作者改用 dataset 形态（dataset+dimensions+values）。packages/spec/src/migrations/registry.ts— 新增 protocol-16 迁移项step16（dashboard-widget-strict-unknown-keys），对齐 protocol-15step15对 form/page schema 的 strict 翻转（ADR-0089 D3a）。内联分析形态本身已在 protocol 9（single-form cutover）移除，因此无机械转换，残留即 strictness 本身，交由作者处理。packages/lint/src/validate-widget-bindings.ts—widget-legacy-analytics-*规则保留为原始配置路径（lint/doctor）的友好桥（strict 会在已解析的compile/validate路径先行拦截）；更新文档注释说明二者关系。dashboard.test.ts— 新增拒绝用例：合法 dataset widget 携带遗留键、component/data、typo 键；并验证options逃生舱仍可用。PROTOCOL_VERSION：protocol-version.test.ts要求PROTOCOL_MAJOR == @objectstack/spec 包主版本（当前 15.1.1），在本 PR 里改 16.0.0 会挂 CI。PROTOCOL_VERSION = '16.0.0'应由发布列车的 Version-Packages PR 设置。在此之前step16是惰性且安全的（composeMigrationChain会截到PROTOCOL_MAJOR；已跑check:spec-changes/check:upgrade-guide均无 drift）。minor（@objectstack/spec）：按发布窗口政策，破坏性变更以 minor 搭乘已在待发的 16.0.0 列车（.changeset/console-*.md已声明@objectstack/console: major），不单独 burn major。no-major guard 对本 changeset 通过（其 exit 1 来自既有的 console major，需发布 PR 的allow-major标签处理，与本 PR 无关）。必须在 objectstack-ai/objectui#2703 合并之后 再合并本 PR，且需先把
.objectui-shabump 到 objectui 的合并 commit（pnpm objectui:refresh，本 PR 暂未包含该 bump —— 因为 objectui 合并 commit 尚不存在）。顺序反了会让新 strict schema 拒绝旧 console 生成的遗留键（Studio 保存 422）。验证
@objectstack/spec全量 6797 passed；dashboard/migrations/protocol-version 定向通过。@objectstack/lintvalidate-widget-bindings40 passed。check:api-surface/check:spec-changes/check:upgrade-guide/check:docs均 in-sync（strict 只在构建期给 JSON schema 加additionalProperties:false，产物为 gitignore 构建物）。🤖 Generated with Claude Code
Generated by Claude Code