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

Commit 33da643

Browse files
feat(cli): objectui check refuses a ${…} on a text key its node never evaluates (objectui#4795) (#11126)
Fixes #4795 Clause-②: yes — `objectui check` newly refuses `${…}` in the four closed keys where `expressionBindableTextKeysFor(type)` excludes the key, as ruled (`5406135987`, `5479466110`). The PR waits as a draft for the director seat's contract review. Ruling item 2 of #4795 (maintainer, 2026-08-31, comment `5479466110`), built in `objectui check` as ruled. Draft for the director seat's contract review. ## The repository's own `pnpm check`: red in round 1, resolved by the seat's answer A `.github/workflows/lint.yml` runs `pnpm check` on this repository (step "Verify the CLI's own check command passes on this repository"). Measured with the CLI built from each tree: | tree | `pnpm check` exit | refusals | warnings | |:--|:--|:--|:--| | `main` `d1e683fa1` (no gate) | 0 | 0 | 0 | | round 1, `ed32e7c6b` | 1 | 1 | 0 | | this branch, `c985c4d7d` | 0 | 0 | 0 | **The round-1 refusal.** It was `examples/schema-catalog/src/schemas/plugin-editor/javascript-editor.json`: a root `code-editor` whose `value` was a JavaScript sample using template literals. That is literal content, not a misplaced expression, and it had no mechanical channel move. **The fix.** The seat chose A under ruling `5479466110`: 「no-row types included」, and 「A row can always be added later with a named need + its own measurement」. The sample now builds the same strings by concatenation. Run, it still logs `Hello, Developer!` and returns `Welcome, Developer`. **Nothing pinned the old content.** No test, snapshot or docs fence reproduces it: - the catalog registers the file by import; - `safe-validate-corpus-6318.test.ts` asserts only that it validates; - `catalog-gallery-render.test.tsx` skips it, because Monaco cannot load under happy-dom; - `plugin-editor.mdx` embeds it by id through `SchemaExample`. The run's closing tally is the same as on `main`: `265 validated, 167 recognised but not validated, 1 did not validate`. ## What it does `findUnbindableTextExpressions` (new, `packages/cli/src/utils/unbindable-text-expressions.ts`), called by `check` on every recognised file, from either recognition arm: - **The rule.** Each of the four keys `EXPRESSION_BINDABLE_TEXT_KEYS` on a component node is judged against `expressionBindableTextKeysFor(type)`. Both are imported from `@objectstack/spec/ui`: the vocabulary and the carriage map are consumed, not copied. - **Component nodes (sub-rule i).** The document root, plus every node `children` holds (an array or a single node), recursively. A root of type `page` is not judged itself, because its `title` is a page key; its `children` still are. - **Expression.** The evaluator's own interpolation pattern, as `ExpressionEvaluator.evaluate` matches it. A lone `${` or an empty `${}` is not an expression there, so it is not one here. - **Refusal vs warning (sub-rule ii).** A registered type (the `isKnownSchemaType` universe) is refused: a red `x Unevaluated expression in FILE at PATH: …` line plus a channel line, and it counts toward the run's `Found N errors`, so the exit code is 1. A type no registered component answers to gets a yellow `⚠️ Expression not judged in …` line, and the run still passes. - **Message.** It follows the `describeFirstIssue` shape objectui#11007 / PR #11053 gave `check`. The path is spelled by `formatIssuePath`, the formatter `objectui validate` prints with. It names the key, the path, the type, the keys that type does evaluate, and the channels `SchemaRenderer` evaluates: the type's own evaluated keys, `content`, `properties.KEY` (evaluated, then hoisted onto the node), or resolving the value in the host. `@objectstack/spec` becomes a declared dependency of `@object-ui/cli` at `^17.1.0`. That is the range `@object-ui/react` declares, and `@object-ui/react` is the runtime consumer of the same lookup. The lockfile gains only the importer entry, which resolves the installed version. Docs: `content/docs/utilities/cli.mdx` gains the rule, the two sub-rules and the real output. It also says a refused expression now fails the run, where the page used to say only unreadable JSON did, and that a literal `${…}` has no escape spelling (the changeset says so too). Changeset: `@object-ui/cli` minor. ## Premises re-derived on `main` `d1e683fa1` 1. **Spec floor and carriage map.** The lockfile carries a single `@objectstack/spec`, and the installed `node_modules/@objectstack/spec/package.json` reads 17.4.0. It exports both symbols. Its answers: `statistic` gives `label` / `value` / `description`; `card` gives `title` / `description`; `button` gives `label`; `text`, `action:button`, `ui:card` and `page` give the empty set. `check:spec-floors` fetched the declared-floor tarball and passed: the CLI artifact's two `./ui` symbols are present at the floor. Nothing here depends on 17.5.0. 2. **Type keying.** The evaluation memo in `SchemaRenderer` calls `expressionBindableTextKeysFor(typeof newSchema.type === 'string' ? newSchema.type : '')`, verbatim, with no prefix stripping. The comment "keys on the bare registry name" describes the spec map's keys; it does not describe a normalization. The gate passes `node.type` verbatim. - **Measured once through the real `SchemaRenderer` (at `e2f8e48d9`; the gate's code is unchanged since):** every one of the 649 registered types was rendered with the four keys set to `${data.total}`. On every type, the keys it left unevaluated equalled the gate's refusals, 0 disagreements. The types it evaluated anything on were exactly those with a row. - **Not committed, for one reason:** a CLI test importing `@object-ui/react` turns the CLI's generated-source allowance for that dependency stale in `check:unused-deps` (`DECLARED_WITHOUT_IMPORT`). That ledger is outside this claim's file surface. - **What is committed instead:** the unit-tier table. It pins the gate against the verbatim lookup on every registered type, and derives the namespaced spellings a prefix-stripping gate would get wrong. The runtime half stays pinned by the `@object-ui/react` suite `SchemaRenderer.bindableTextKeys.test.tsx` ("a namespaced spelling is not silently normalized"). 3. **Sub-rule (i) premise: holds.** - `SchemaRenderer` does not recurse on its own. Each renderer hands keys back through `renderChildren` / `renderNodeSlot` / a direct `SchemaRenderer`. - A form's `fields[]` entries are rendered by the form's `renderFieldComponent` (field widgets under `field:*`), never through `SchemaRenderer`. - `check` judged the root only before this change. - The walk follows `children` alone. That is the one composition key `BaseSchema` declares, and the same single spelling core's `validateChildren` and the SDUI parser's `CHILD_LIST_KEY` follow. - Census of the recognised corpus: objects with a string `type` that are not nodes sit under `form` `fields[]`, `filter-builder` `fields[]`, `grid` `columns[]`, `dashboard` `widgets[]` / `globalFilters[]`, and even `object-grid`'s `columns[].summary` (`{ "type": "count_unique" }`) and `selection` (`{ "type": "multiple" }`). A walk over every typed object would judge all of them. 4. **Corpus.** See the table above: one offender in round 1, not mechanical. It was resolved in round 2 by rewriting the sample, the seat's answer A. 5. **Sub-rule (ii).** Pinned: `stat-card` warns and the run passes. `text.value`, `action:button.label`, `card.label` and `ui:card.title` are refused. `statistic.value`, `card.title` and `button.label` pass. 6. **Message format.** See above. 7. **PR #11069.** Not read from and not edited toward. The second of the two to land merges `main`. ## Tests - `packages/cli/src/__tests__/check-unbindable-text-expression-4795.test.ts` (unit tier, 28 tests). Expected text is derived from the command's own formatters, fed from the gate's real findings. It covers: - the refusals, with the key, path, type, channels and exit code; - the passes, including a lone `${` and an empty `${}`; - the walk through `children` (array and single node) and multiple refusals per file; - the page-root `title` exclusion, with the page's children still judged; - the form-field `label` non-refusal, with a control: the same object under `children` IS refused; - the `stat-card` warning; - validity-arm files judged and unrecognised files not; - the verbatim-lookup agreement table over every registered type. - Whole package, `pnpm exec vitest run packages/cli/` at `c985c4d7d`, under the verify lock: `Test Files 23 passed (23)`, `Tests 330 passed (330)`. - The catalog the rewritten sample lives in, `pnpm exec vitest run examples/schema-catalog/` at `c985c4d7d`, under the verify lock: `Test Files 34 passed (34)`, `Tests 2199 passed (2199)`. Within it, `safe-validate-corpus-6318.test.ts` passes `plugin-editor/javascript-editor validates unchanged`. ## Ablations Each direction was predicted before the run. Mutations went through `ablation-replace.mjs`: in each run the anchor went 1 to 0, the marker 0 to 1, and the restore proved blob == HEAD with `git diff HEAD` empty. All three were re-run on `ed32e7c6b`. Round 2 touched neither the gate nor its tests, so these readings stand. 1. **Refusal removed** (severity forced to `warning`). Predicted: the refusal pins go red. Observed: `15 failed | 13 passed`. The passes, the page-root exclusion, the `stat-card` warning and the unrecognised-file pins stayed green. 2. **Walk widened** to every object with a string `type`. Predicted: only the form-field pin goes red. Observed: exactly that, `1 failed | 27 passed`, and the failure prints the refusal at `fields → 0 → label`. 3. **Namespace stripped** before the lookup. Predicted: the two agreement cases and `ui:card.title` go red. Observed: 5 red, those 3 plus `action:button.label` and "refuses every offending node". `action:button` strips to `button`, which has a `label` row. The direction matched the prediction, with two more reds than predicted, both explained. ## Gates (exit codes; at `c985c4d7d` unless noted) Heavy runs (builds, test suites, `pnpm check`, the doc compile gates, `check:node-esm-load`) went through the shared verify lock in round 2. - **CLI package:** `type-check` 0 · `lint` 0 (0 errors; 5 warnings, all in files this PR does not touch) · tests 0 (above). - **Repo check:** `pnpm check` **0**: 0 refusals, 0 warnings. - **Changesets:** `check-changeset-presence` 0 · `check-changeset-no-major` 0 · `check-changeset-overwrite` 0 · `check-changeset-fixed` 0 · `check:changeset-claims` 0 (report-only; it names the same five pending changesets as round 1, and none is falsified by this diff) · `check:pending-changeset-literals` 0. - **Bytes and citations:** `check:control-bytes` 0 · `check:new-line-citations` 0. - **Dependencies and lockfile:** `check:phantom-deps` 0 · `check:unused-deps` 0 · `check:lockfile-integrity` 0 · `check:lockfile-dedupe` 0. At `ed32e7c6b` (round 2 moved no manifest and no CLI source): `check:spec-floors` 0 · `check:installed-pin-claims` 0 · `check:esm-specifiers` 0 · `check:spec-symbols` 0 · `check:self-import` 0. - **Docs:** `check:doc-snippets` 0 (681 of 681 blocks) · `check:doc-examples` 0 · `check-doc-component-types` 0 · `check-prompt-component-keys` 0 · `check-doc-example-ids` 0 · `check-doc-fence-languages` 0 · `check-doc-links` 0 · `check-doc-expression-carriage` 0 (report-only) · `toc-anchor-parity.test.tsx` 15 passed. - **Test shape and dist, at `ed32e7c6b`** (round 2 touched no source or test file): `check-lint-coverage` 0 · `check:test-path-roots` 0 · `check:vi-mock-*` (three) 0 · `type-check:coverage` 0 · `check:unreferenced-sources` 0 · `check:dist-completeness` 0 · `check:published-dist` 0 · `check:shell-escape-residue` 0. - **Governed surface:** `check-governed-queue-guard --test` over the eight paths: NOT GOVERNED · `check:governed-queue-guard` self-test 0 (at `ed32e7c6b`). - **`check:node-esm-load`: 1, left to CI.** Under the lock at `c985c4d7d`, it again refused `@object-ui/auth` and `@object-ui/react-runtime` on provenance: the turbo cache is shared across worktrees and replayed another tree's build. The `@object-ui/cli` entry was among the 32 graded loads. CI builds fresh. ## Acceptance notes - **Known limitation: no escape spelling.** - A literal `${…}` in a closed key of a type with no carriage row is refused, and nothing lets it through. That covers a code sample in a `code-editor` `value` and shell `${VAR}` text. - A carve-out for literal content is a spec-first decision, reopened on the first named user need. None is built here, and there is no local key list. - The docs page and the changeset say this. This repository's own sample was the only measured instance, and the runtime dev diagnostic already reported it. - **Walk boundary.** Nodes a renderer reaches through a key of its own are not walked: `trigger`, `header`, `footer`, a page's `regions[].components[]`, a tab's `items[].content`, `panels[].content` and carousel `items`. No declaration of per-renderer node slots exists to derive them from. The boundary fails quiet in the safe direction: it never produces a false refusal. - **Keys outside the four** (e.g. `badge.text`) are not judged. `5479466110` set item 2's scope to the carriage map, which narrows `5406135987`'s "any key outside that closed list". The `props`-envelope blank render is outside that scope too. - **`check` reads `.json` only.** `.yaml` / `.yml` are globbed and never read, as `check.ts` already stated. - **Two rulings meet in `check.ts`.** The objectui#11007 triage ruling declined a nested *validation* walk in `check`. Its pin "no nested walk of its own" stays green, because this walk validates nothing and reads only the four keys. Named here so the reviewer sees both rulings. - **The channel line says "evaluated", not "read back".** It mirrors the runtime diagnostic's vocabulary (objectui#7849). For `text.value`, which `TextSchema` retired and whose renderer reads `content` alone, `properties.value` is evaluated and hoisted but not rendered. The seat kept this wording (answer A, one vocabulary with the runtime diagnostic); the contract review may still choose B, which would be a one-line change in `workingChannels`. - **Runtime agreement.** The real `SchemaRenderer` was measured once over all 649 registered types, with 0 disagreements. The committed pins are the two verbatim-lookup halves. The seat chose not to add the DOM suite (answer A), so the CLI's `@object-ui/react` allowance in `check:unused-deps` is untouched. Session: `https://claude.ai/code/session_012UwY3ahMixEFkfTUxMVkYm` --- _Generated by [Claude Code](https://claude.ai/code/session_012UwY3ahMixEFkfTUxMVkYm)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 957f695 commit 33da643

8 files changed

Lines changed: 654 additions & 8 deletions

File tree

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
'@object-ui/cli': minor
3+
---
4+
5+
feat(cli): `objectui check` refuses a `${…}` on a text key its node never evaluates
6+
7+
`SchemaRenderer` evaluates an expression on the closed text keys `title`,
8+
`label`, `value` and `description` only where `@objectstack/spec`'s
9+
`expressionBindableTextKeysFor(type)` lists that key for the node's type.
10+
Anywhere else the expression is never resolved, so the user sees
11+
`${data.total}` as literal text, or nothing at all — and no step before the
12+
browser said so.
13+
14+
`objectui check` now refuses such an expression in every file it recognises as
15+
an ObjectUI schema, and the run exits non-zero. The refusal names the key, the
16+
path to it (spelled as `objectui validate` spells paths), the keys that type
17+
does evaluate, and the channels `SchemaRenderer` evaluates. Types with no row in
18+
the carriage map are refused too: `text.value` and `action:button.label` are
19+
never evaluated.
20+
21+
- **Component nodes only**: the file's root node and every node its `children`
22+
hold. Objects under other keys, such as a form's `fields` entries, are
23+
definitions rather than nodes and are not judged. A root of type `page` keeps
24+
its own `title`, which is a page key; its `children` are still judged.
25+
- **The type is matched as written**, as the runtime matches it: `ui:card` has
26+
no row, and is not read as `card`.
27+
- **A type no registered component answers to** gets a warning instead of a
28+
refusal, because a custom renderer may evaluate its own keys.
29+
- **There is no escape spelling**: a `${…}` meant as literal text on one of
30+
these keys, such as a code sample in a `code-editor`'s `value`, is refused
31+
too. Write it without `${`.
32+
33+
The key vocabulary and the per-type carriage map are read from
34+
`@objectstack/spec`, now a declared dependency of `@object-ui/cli`, so a row
35+
added upstream moves this check and the runtime together.

‎content/docs/utilities/cli.mdx‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -224,13 +224,41 @@ distinction matters:
224224
Issue at map: Unrecognized key: "latitudeFieId"
225225
```
226226

227-
A run with no parse errors ends on a tally rather than a pass: how many
228-
recognised files validated, how many were recognised by a structural key and not
229-
validated, and how many did not validate, followed by a pointer to
230-
`objectui validate` for the verdict.
227+
#### Expressions on text keys that are never evaluated
228+
229+
`SchemaRenderer` evaluates a `${…}` expression on the closed text keys `title`,
230+
`label`, `value` and `description` only where `@objectstack/spec`'s
231+
`expressionBindableTextKeysFor(type)` lists that key for the node's type. On any
232+
other type, the expression is never resolved: the user sees its literal text, or
233+
nothing. `objectui check` refuses it in every recognised file:
234+
235+
- **Component nodes only.** The file's root node and every node its `children`
236+
hold, at any depth. Objects under other keys (a form's `fields`, a grid's
237+
`columns`) are definitions, not nodes, and are not judged. A root whose `type`
238+
is `page` keeps its own `title`: that is a page key, while its `children` are
239+
still judged.
240+
- **The type is matched as written.** `ui:card` is not `card`, exactly as at
241+
render time.
242+
- **A type no registered component answers to** is warned about, not refused: a
243+
custom renderer may evaluate its own keys.
244+
- **There is no escape spelling.** A `${…}` meant as literal text on one of
245+
these keys — a code sample in a `code-editor`'s `value`, a shell `${VAR}` — is
246+
refused too. Write the text without `${`, for example with string
247+
concatenation in a code sample.
231248

232-
Only unreadable JSON makes `objectui check` exit non-zero; everything above is a
233-
report. Use `objectui validate` when you want a failing exit code.
249+
```text
250+
x Unevaluated expression in dashboard.json at children → 0 → title: "statistic" never evaluates `title` (it evaluates only `label`, `value`, `description`), so the expression is never resolved: the user sees its literal text, or nothing.
251+
Channels SchemaRenderer evaluates: `label`, `value`, `description`, `content`, `properties.title` (evaluated, then hoisted onto the node); or resolve the value in the host before the schema reaches SchemaRenderer.
252+
```
253+
254+
A run with no parse errors and no refused expression ends on a tally rather than
255+
a pass: how many recognised files validated, how many were recognised by a
256+
structural key and not validated, and how many did not validate, followed by a
257+
pointer to `objectui validate` for the verdict.
258+
259+
Unreadable JSON and a refused expression make `objectui check` exit non-zero;
260+
everything else above is a report. Use `objectui validate` when you want a
261+
failing exit code on a document that does not validate.
234262

235263
### `objectui doctor`
236264

‎examples/schema-catalog/src/schemas/plugin-editor/javascript-editor.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"type": "code-editor",
3-
"value": "function greet(name) {\n console.log(`Hello, ${name}!`);\n return `Welcome, ${name}`;\n}\n\ngreet('Developer');",
3+
"value": "function greet(name) {\n console.log('Hello, ' + name + '!');\n return 'Welcome, ' + name;\n}\n\ngreet('Developer');",
44
"language": "javascript",
55
"theme": "vs-dark",
66
"height": "300px"

‎packages/cli/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@
5656
"@object-ui/components": "workspace:*",
5757
"@object-ui/react": "workspace:*",
5858
"@object-ui/types": "workspace:*",
59+
"@objectstack/spec": "^17.1.0",
5960
"@tailwindcss/postcss": "^4.3.3",
6061
"@types/glob": "^9.0.0",
6162
"@vitejs/plugin-react": "^6.0.5",

0 commit comments

Comments
 (0)