Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 5495b8d

Browse files
claude[bot]os-samclaude
authored
feat(scripts): report-only component surface parity checker (objectui#4631) (#9551)
Fixes #4631 Lands `pnpm check:component-surface-parity` — a **report-only** checker that prints, per registered component type, where the four declared surfaces disagree. It repairs nothing it finds, and it exits `0` with findings. > **Round 2.** The instrument review ([verdict](#9551 (comment))) > returned FAIL with four repairs — all seven of the round-1 claims reproduced exactly, so the > FAIL was about what the census did not disclose, plus one rule that fired on correct code. > All four are fixed, every repair in the matcher; `origin/main` is merged in and the census > re-taken on the merged tree. The round-2 numbers are below and they replace the round-1 ones. ## The rule, which is the ruling's and not the script's From the director-seat ruling on this card (batch #112 item 2, 2026-09-10), quoted rather than paraphrased: > **裁定**:一个组件类型的权威序是 **spec 的 `ComponentPropsMap`(有声明时)> 渲染器实际读的键(实现)> TS 接口与注册表 `inputs`(实现的说明书,跟随)**。 > 门:`check:component-surface-parity`——TS 接口键集 = spec 键集 ∪ 渲染器读键集;`inputs` ⊆ 该集合;`defaultProps` 中作为设计器种子而非默认值的行须登记理由。report-only 起步,零分歧后翻阻断。 So: interface key set = spec ∪ renderer-reads; `inputs` ⊆ that union (an **omission is legal**); a `defaultProps` row that is a designer seed rather than a default claim carries a registered reason. Report-only first; the flip to blocking is a separate card on a measured zero, and repairing any row below is governed by the same ruling's ordering note (先判协议对不对 — the spec card goes first where the protocol is the thing that is wrong). ## How this divides the work with the gate that already exists `apps/console/src/__tests__/registry-inputs-spec-parity.test.ts` owns registry `inputs` ↔ spec `ComponentPropsMap`, in both directions, from the **live registry**, with its own exemption discipline — and it is one of a family: `git ls-tree -r --name-only origin/main` filtered on `spec-parity|inputs-spec` lists 36 paths, 34 of them `*.test.ts(x)`. This checker neither repeats nor contradicts that family: - it judges `inputs` against the **union** (spec ∪ renderer reads), which is the ruling's accept set and is strictly *wider* — so a key this checker passes may still be judged there, and those tests stay the authority on the spec-only direction; - it reads the two surfaces a live registry cannot hold: the TS interface in `packages/types`, and what the renderer actually **reads**; - it reads **source**, not a runtime registry, so a lazily registered block (a stub at runtime) is a full member of this population. The two populations differ on purpose. `scripts/check-handler-key-read-sites.mjs` is the same read-site question narrowed to `on*` keys and judged against the zod arms; it blocks. This checker reuses that gate's extraction primitives rather than growing a fourth copy of "which files ship" and "which registrations exist", and judges every key against the TS interface instead. ## Acceptance notes ### Corpus — stated so every number below is reproducible from this text alone Measured at `e9dc38ee9e`, which is this branch **with `origin/main` merged in** (`8d50bc2bf4`, merge commit `0a1fda0402`). ⚠️ **The census moves with the base, and must always be quoted with its ref.** It is a reading of two trees at once — this branch's matcher against `main`'s declarations — so a declaration landing on `main` moves it with nothing here changing. Two things moved it this round, and they are **separable**; both legs were measured, the second by ablating the F3 guard on the merged tree: | step | census | moved by | |---|---|---| | `e085c14f3b` — round 1, pre-merge | 95 / 151 / 107 / 0 = **353** | — | | + the base merge alone (F3 guard reverted) | 91 / 153 / 107 / 0 = **351** | **the base**: 6 rows, all on `UIActionSchema`, because `main` widened `packages/types/src/ui-action.ts` in flight (#9543) — 4 left, 2 arrived, net −2 | | + the F3 repair → `e9dc38ee9e` | 91 / 153 / 95 / 0 = **339** | **this branch**: 12 artifact rows, the `input-outside-keyset` findings the unguarded rule manufactured | So the `107 → 95` leg is the F3 repair, not the base; the base moved the census by **2**, in the `interface-*` columns only. ⛔ A ratchet card must nonetheless quote a **ref**, never 339 as a fixed floor — the base can move it again tomorrow with nothing here changing. - **Registration corpus**: every file the checker walks — `packages/PKG/src/**` (every workspace package), excluding `.d.ts` and the tooling pattern `(^|/)(__tests__|__mocks__|__benchmarks__)/|\.(test|spec|bench|stories)\.[cm]?[jt]sx?$`. **1443 files across 40 packages.** Registrations read from that corpus: **212**. - ⚠️ **Not the whole registered tree**, and this is the largest exclusion in the census. **5 call sites register dynamically** — `ComponentRegistry.register(variable, …)` inside a loop — and their types exist only at run time, so this reader can name none of them. They are printed as a coverage bucket (below), and the families behind them (the `ui:HTML-TAG` blocks from `html-elements.tsx` + `semantic.tsx`, the `field:*` widgets from `fields/src/index.tsx`, and the `placeholders.tsx` vocabulary) are outside every number here. Membership probe against the 212: `ui:h1`, `ui:p`, `ui:img`, `field:text`, `field:select`, `field:lookup` all **absent**; same-corpus controls `nav:menu`, `ui:toast`, `ui:sonner` all **present**. - ⚠️ Nor the same as the raw text count. `git grep -o "ComponentRegistry\.register(" HEAD -- packages | wc -l` → **507 occurrences** in **301 files** (`git grep -l … | wc -l`); 148 of those files match the tooling pattern, 19 are `.md`, 134 are in population. Absent-token control in the same corpus: `qqzz_absent_token_9999` → **0 files**. - **Spec surface**: `ComponentPropsMap` from the installed `@objectstack/spec/ui`, read through a dynamic `import()`. **45 entries** (44 object shapes, 1 `z.never()` read as declared-with-no-keys); **30** of the 212 registrations have one. - **Interface surface**: `packages/types/src/**` excluding `zod/` and `__tests__`. **448** declarations indexed; **92** registrations resolve to one, of which **9** are annotated `BaseSchema` itself and so have no OWN members at all. - ⚠️ **spec ∩ interface = 0.** Only a type with *both* can produce a spec-caused finding, and no type has both: every spec-declared registration takes `schema: any` or no annotation. So on this corpus the spec arm of `interface-missing-key` fires on **nothing** and the spec half can only ever *suppress* (it widens the accept set). Per-finding attribution confirms it: `spec=0 spec+renderer=0 renderer=91`. The authority order is mechanised and pinned by the suite; it is not doing work on **this** tree. The run prints this line and shouts when it is zero. - **Ambient key set**: **33 keys**, derived from `BaseSchema`'s own members plus the render loop's own reads and injected props in `packages/react/src/SchemaRenderer.tsx`. Nothing is listed; both halves are re-derived every run. ### The census, split by the caveat the findings already carry | | total | named-read | rest-spread | |---|---|---|---| | `interface-missing-key` — the interface does not declare a key the spec declares or the renderer reads | **91** | 91 | 0 | | `interface-extra-key` — the interface declares a key neither the spec declares nor the renderer reads | **153** | 26 | 127 | | `input-outside-keyset` — `inputs` publishes a key outside (spec ∪ renderer reads) | **95** | 32 | 63 | | `read-of-tombstoned-key` — a renderer reads a key the interface refuses by name (`: never`) | **0** | 0 | 0 | | **TOTAL** | **339** | **149** | **190** | **rest-spread** means the instrument does **not** claim the row is a defect: 117 of 210 resolved renderers forward their unnamed props with a rest spread, so the key may be honoured without a named read (`ui:switch.checked` is the specimen — declared, published in `inputs`, honoured through the spread, named nowhere). ⛔ Quoting 339 without this split is quoting 190 rows the gate itself hedges. `interface-missing-key` is deliberately never tagged: there the key **is** read, and a spread forward does not soften a missing declaration. `defaultProps` vs renderer fallback, over the same 212 registrations: **77 comparable pairs, 68 agreeing, 9 diverging**, all 9 carrying no registered designer-seed reason (the ledger ships empty — populating it would be adjudicating these rows, which this card does not do): | row | `defaultProps` | renderer fallback | |---|---|---| | `action:bar.variant` | `"outline"` | `"ghost"` | | `action:button.size` | `"md"` | `"default"` | | `action:group.size` | `"sm"` | `"default"` | | `ui:pagination.totalPages` | `10` | `1` | | `ui:data-table.selectable` | `true` | `false` | | `ui:data-table.exportable` | `true` | `false` | | `ui:data-table.rowActions` | `true` | `false` | | `ui:file-upload.buttonText` | `"Choose files"` | `"DROP PAYLOAD OR CLICK TO UPLOAD"` | | `plugin-markdown:markdown.content` | a sample document | `""` | A *comparable pair* is a `defaultProps` key whose renderer also has a **literal** fallback for the same key (`schema.k || LIT`, `schema.k ?? LIT`, or a destructured `{ k = LIT }`). A fallback that is not a literal is recorded as "has a fallback, not comparable" rather than as agreement. ⚠️ Read 77/9 as bounded by that pattern, not as a repo total. This table is unchanged by the base merge. ⭐ `layout:flex.align` — the first row of the 2026-09-07 census on this card — does **not** appear, because #7735 / #8229 repaired it. That reading is superseded by this one. ### Coverage gaps — four named buckets, reported, never counted as agreement - **2** registrations whose component body the walk could not reach (`plugin-list:list-view`, `view:list` — `elementDataSourceBlock(React.forwardRef(…))`, a double wrap the HOC hop does not follow). **The `inputs` rule is skipped for these**, exactly as both interface rules are skipped when the interface does not resolve. - **120** with no resolvable TS schema interface (`schema: any`, no annotation, or a props type this reader cannot hop through); - **12** with an `inputs` entry this reader cannot name (a spread); - **5** dynamically typed registration call sites, each printed with its file, line and the expression it registers under. A zero read set or a zero key set read as truth would report every declared key as extra, so each of these is a named bucket rather than a silent pass — and each rule is guarded against its own bucket. ### Two premises re-measured, and one the checker confirms by staying silent - **#7316 (`toast` / `sonner` omit `buttonVariant` from `inputs`) is NOT flagged.** Under the ruling's `inputs ⊆ keyset` an omission is legal. `node scripts/check-component-surface-parity.mjs --type ui:toast` prints `buttonVariant` in both `reads` and `interface` and absent from `inputs`, with no finding for it. The suite pins that shape executably, so widening the rule into a two-way mirror cannot happen silently. - **The `registry-inputs` uniqueness premise did not hold as written.** As a *content* grep, `git grep -l "registry-inputs" origin/main | wc -l` → **50 files**, not one; as a *path* match exactly one file is named `registry-inputs-spec-parity.test.ts`. The division-of-work section above is written against the whole family. ## Non-vacuity — three controls that fire, three ablations that prove they can `scripts/__tests__/check-component-surface-parity.test.ts`, **42 tests**, all passing. Three of them fire rather than prove silence, and each has a mutation behind it: | ablation (matcher mutated on disk, from the committed state) | mutated suite | restored | |---|---|---| | disable the `inputs ⊆ keyset` rule | `1 failed, 31 passed` — `expected [] to include 'input-outside-keyset:ghostKey'` | 32/32 (round 1) | | stop pushing to the dynamic-registration bucket (F1) | `2 failed, 40 passed` — the bucket test and its real-tree twin | 42/42 | | remove the `renderer.unresolved` guard on the `inputs` rule (F3) | `1 failed, 41 passed` — *does NOT report inputs for a registration whose renderer body it cannot reach* | 42/42 | Round-2 legs ran against blob `204c904083306c119e48cc35cf7e91e7dc799a96`; each mutation was proved on disk by hash (`1c5aa857…`, `a1931ee6…`) before the suite was run, and each restore leg returned the file to `204c9040…` with `git diff HEAD` empty and the injected marker at 0 occurrences. A `trap … EXIT INT TERM` with absolute paths was in place throughout. The suite also carries the five ways a parity gate can be invisibly vacuous, as executable assertions: no registration read, no renderer body resolved, no interface found, an empty ambient set (a confident **red** over a broken instrument), and a wrongly resolved spec. Each is an `ExtractionError`, never a pass. ## Verification | check | result | |---|---| | `pnpm exec vitest run --disable-console-intercept=true scripts/__tests__/check-component-surface-parity.test.ts` | 42 passed (42), exit 0 | | `pnpm type-check:scripts` | exit 0 | | `pnpm exec eslint --no-inline-config` on both new files | 0 errors, 0 warnings | | `pnpm check:component-surface-parity` | exit 0 (report-only, with the census above) | | `node scripts/check-entry-guard.mjs` | exit 0 | | `node scripts/check-changeset-presence.mjs` | exit 0 — no published source or contract moved; the changeset is the explicit empty-frontmatter "no release" declaration | | `node scripts/check-new-cross-file-line-citations.mjs` | exit 0, 0 new citations | | `node scripts/check-pre-install-import-graph.mjs` | exit 0 | | `node scripts/check-test-path-roots.mjs` | exit 0 | | `node scripts/check-lint-coverage.mjs` | exit 0 | | `node scripts/check-control-bytes.mjs` | exit 0 | | `node scripts/check-vi-mock-override-shape.mjs` | exit 0 | All re-run on the merged tree at `e9dc38ee9e`. Repo-wide `pnpm lint` and the full `pnpm test` farm are CI's run, not claimed here. ## Out of scope — left alone on purpose, each its own card - **Every one of the 339 disagreements above.** Not one is repaired here. The ruling's ordering note governs them: decide whether the protocol is right first. - Flipping this to blocking, or wiring it into CI as a required check. - `BaseSchema`'s `body`/`children` twins and its `[key: string]: any` index signature — the ruling puts these on their own card in so many words. The ambient set reads `BaseSchema`'s member NAMES only, so that a key every type inherits is not billed to one block; it reports, widens and narrows nothing there. - Any edit to a TS interface, a registry `inputs` array, or a renderer. In particular ⛔ nothing in `packages/plugin-list` moved for F3 — the repair is the matcher's guard, and the row stays in the coverage bucket where an unreadable renderer belongs. - Enumerating the dynamic registration families. A half-enumerated `TAGS` loop is a census nobody can reconstruct; naming the exclusion is the honest answer, and extending the reader to resolve them is its own card. `Clause-②: no` — a report-only checker plus its tests adds a build-time reading and no authorable key, no published type and no accepted spelling. Nothing in any published `.d.ts` moves. Implemented-by: claude/issue-4631-component-surface-parity-gate --- _Generated by [Claude Code](https://claude.ai/code)_ --------- Co-authored-by: os-sam <sam@objectstack.ai> Co-authored-by: Claude <noreply@anthropic.com>
1 parent 009f92d commit 5495b8d

4 files changed

Lines changed: 2600 additions & 0 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
---
3+
4+
Add `pnpm check:component-surface-parity` — a **report-only** checker that prints, per
5+
registered component type, where the four declared surfaces disagree: the spec's
6+
`ComponentPropsMap`, the keys the renderer actually reads, the TS schema interface in
7+
`packages/types`, and the registry `inputs` / `defaultProps` of the `register()` meta
8+
(objectui#4631).
9+
10+
The rule it mechanises is the ruling's, not the script's: the TS interface key set is the
11+
union of the spec key set and the renderer-read key set, `inputs` is a subset of that union
12+
(so an omission is legal), and a `defaultProps` row that is a designer seed rather than a
13+
default claim has to carry a registered reason.
14+
15+
It exits `0` with findings — the ruling's own sequencing is report-only first, blocking once
16+
the census reads zero — and it repairs nothing it finds. Tooling only: no published package
17+
source, manifest or contract moves, so no package is released by this change.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
"check:spec-symbols": "node scripts/check-spec-symbol-derivation.mjs",
4444
"check:action-forward-parity": "node scripts/check-action-forward-parity.mjs",
4545
"check:designer-field-key-parity": "node scripts/check-designer-field-key-parity.mjs",
46+
"check:component-surface-parity": "node scripts/check-component-surface-parity.mjs",
4647
"check:icon-record-names": "node scripts/check-lucide-icon-record-names.mjs",
4748
"check:phantom-deps": "node scripts/check-phantom-dependencies.mjs",
4849
"check:unused-deps": "node scripts/check-unused-dependencies.mjs",

0 commit comments

Comments
 (0)