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

Commit 317dbce

Browse files
claude[bot]claude
andauthored
fix(core): narrow validateSchema's published parameter to unknown (objectui#8416) (#8880)
`validateSchema(schema: any)` was a bare `any` on a published parameter. The declaration moves by one token to `schema: unknown`, and every value is still assignable, so no call site outside `@object-ui/core` had to move: the function is not generic and returns the concrete `SchemaNodeValidationResult`, which names no parameter type. The half with teeth is the implementation. `validateSchema` calls four rules unconditionally and only `validateBaseSchema` ever checked that it had an object, so `validateFormSchema` (`schema.type`) and `validateChildren` (`schema.children`) read straight through and `validateSchema(null)` threw a raw `TypeError` instead of returning the `INVALID_SCHEMA` result its own contract promises. The single guard now runs once, in `validateSchema`, before any rule reads a key; the four rules take a narrowed `SchemaNodeUnderValidation` whose keys are `unknown`. A `null` entry inside a form's `fields` array threw the same way and is now reported as `MISSING_FIELD_NAME`. No verdict that already existed changes: the guard's accept set is the one it replaces, spelled the same way, and a 29-case matrix diffed before and after shows every difference is a value that used to throw. `scripts/check-doc-example-types.mjs`: the two `schema-validator.ts` ledger rows are re-derived (490 -> 550, 515 -> 575) because their keys carry a line number and this diff moved those JSDoc blocks. Verdicts unchanged. Claude-Session: https://claude.ai/code/session_01611D6ZaRaMmwTNQmSbk8MH Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7e247e2 commit 317dbce

4 files changed

Lines changed: 312 additions & 32 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/core': patch
3+
---
4+
5+
`validateSchema` takes `unknown` instead of `any`, and narrows the value before it reads a
6+
key off it (objectui#8416). The published declaration moves by exactly one token —
7+
`validateSchema(schema: any, path?: string)` becomes `validateSchema(schema: unknown,
8+
path?: string)` — and no call site has to move with it: every value is assignable to
9+
`unknown`, the function is not generic, and its return type is the concrete
10+
`SchemaNodeValidationResult`, which names no parameter type. Nothing outside the package
11+
needed a cast or an edit.
12+
13+
**The half that is not a type annotation: `validateSchema(null)` no longer throws.**
14+
`validateSchema` calls four rules unconditionally and only one of them — `validateBaseSchema`
15+
— ever checked that it had an object. `validateFormSchema` read `schema.type` and
16+
`validateChildren` read `schema.children` regardless, so `validateSchema(null)` and
17+
`validateSchema(undefined)` threw `TypeError: Cannot read properties of null (reading
18+
'type')` instead of returning the `INVALID_SCHEMA` result the function's own contract
19+
promises; `isValidSchema(null)` threw instead of answering the `false` its docblock
20+
documents, and `assertValidSchema(null)` threw that `TypeError` in place of its own
21+
`Schema validation failed:` refusal. The single guard now runs once, in `validateSchema`,
22+
before any rule reads a key. The same one-level-down defect is closed with it: a `null`
23+
entry inside a form's `fields` array threw the same `TypeError` and is now reported as
24+
`MISSING_FIELD_NAME`.
25+
26+
**No verdict that already existed changes.** The guard's accept set is the one it replaces,
27+
spelled the same way (`!value && typeof value !== 'object'` refuses `null`, `undefined` and
28+
every primitive; arrays and plain objects pass), so an array node keeps its
29+
`MISSING_REQUIRED`, a primitive keeps its single `INVALID_SCHEMA`, `null` holes inside
30+
`children` are still skipped, and no new error `code` is emitted. A 29-case accept-set
31+
matrix was diffed before and after: every difference is a value that used to THROW and now
32+
returns a result. The one exception is a corner JSON cannot express — a *named function* as
33+
a `fields` entry used to satisfy `field.name` through `Function.prototype.name` and now
34+
reports `MISSING_FIELD_NAME`; function values on this mirror are already refused
35+
(objectui#6124).
Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
/**
2+
* ObjectUI
3+
* Copyright (c) 2024-present ObjectStack Inc.
4+
*
5+
* This source code is licensed under the MIT license found in the
6+
* LICENSE file in the root directory of this source tree.
7+
*/
8+
9+
/**
10+
* objectui#8416 — `validateSchema`'s published parameter was a bare `any`.
11+
*
12+
* ## The acceptance criterion is a CLASS predicate, not a diff
13+
*
14+
* Two halves, and the second is the one with teeth:
15+
*
16+
* 1. the published parameter is no longer a bare `any`, and
17+
* 2. the implementation NARROWS the value before it reads a key off it.
18+
*
19+
* Half 1 alone is a type annotation, and a type annotation is erased. It is
20+
* pinned here anyway — by a compile-time refusal that `tsc -p tsconfig.test.json`
21+
* evaluates, since vitest cannot see it — but half 2 is what this file mostly
22+
* asserts, because half 2 is where the parameter's old `any` was actually
23+
* costing something.
24+
*
25+
* ## What half 2 was costing (measured on 256c709e2, before the change)
26+
*
27+
* `validateSchema` calls four rules unconditionally, and only ONE of them had a
28+
* guard: `validateBaseSchema` refused a non-object and returned. The other
29+
* three read straight through, so on `null` and `undefined` the third one
30+
* (`validateFormSchema`, `schema.type === 'form'`) threw
31+
*
32+
* TypeError: Cannot read properties of null (reading 'type')
33+
*
34+
* — from a function whose declared contract is a `SchemaNodeValidationResult`
35+
* with an `INVALID_SCHEMA` error in it, and whose `isValidSchema` face is
36+
* documented "@returns True if the value is a valid schema". `assertValidSchema`
37+
* threw that `TypeError` in place of its own `Schema validation failed:` refusal.
38+
* `SchemaRenderer` (`@object-ui/react`) wraps its call in a `try`/`catch`
39+
* commented "Validator itself failed — surface but don't crash render", which is
40+
* where the crash was landing in the one shipped consumer.
41+
*
42+
* That is why these are BEHAVIOUR tests: revert the narrowing and they go red
43+
* by name, which a signature-only pin could never do.
44+
*
45+
* ## Caller compatibility (the card's premise, and its own falsifier)
46+
*
47+
* The card's argument for grading this cheap is that for a PARAMETER, `any` ->
48+
* `unknown` is caller-compatible: every value is assignable to `unknown`, so no
49+
* call site breaks and the cost lands inside the implementation. Its falsifier
50+
* was that the function's return type or generics might thread the parameter's
51+
* `any` outward. They do not — `validateSchema` is non-generic and returns the
52+
* concrete `SchemaNodeValidationResult`, which names no parameter type — and the
53+
* first `describe` below is that reading, written as an executable one: every
54+
* probe is passed WITHOUT a cast.
55+
*/
56+
57+
import { describe, it, expect } from 'vitest';
58+
import {
59+
validateSchema,
60+
assertValidSchema,
61+
isValidSchema,
62+
} from '../schema-validator.js';
63+
64+
/** `true` only for `any` — the `1 & T` distributes to `any` for nothing else. */
65+
type IsAny<T> = 0 extends 1 & T ? true : false;
66+
67+
describe('objectui#8416 — the published parameter', () => {
68+
it('is not a bare `any` — a compile-time refusal, erased at runtime', () => {
69+
// If `validateSchema`'s first parameter goes back to `any`, `IsAny<...>`
70+
// becomes `true`, the annotation below resolves to `never`, and the
71+
// initializer stops compiling. vitest proves nothing about this line; the
72+
// package's `type-check` (`tsc -p tsconfig.test.json`) is what evaluates it,
73+
// the same mechanism objectui#3181 established for this package.
74+
const parameterIsNotAny: IsAny<Parameters<typeof validateSchema>[0]> extends false
75+
? true
76+
: never = true;
77+
expect(parameterIsNotAny).toBe(true);
78+
});
79+
80+
it('takes every value UNCAST, which is what makes the narrowing caller-compatible', () => {
81+
// Not one `as any` in this list. That is the whole caller-compatibility
82+
// claim, executed rather than asserted: `unknown` accepts what `any`
83+
// accepted, so no call site outside this package had to move.
84+
const probes: unknown[] = [null, undefined, 0, '', false, 42, 'str', [], {}, () => {}];
85+
for (const probe of probes) {
86+
const result = validateSchema(probe);
87+
expect(typeof result.valid, `probe ${String(probe)}`).toBe('boolean');
88+
}
89+
});
90+
});
91+
92+
describe('objectui#8416 — the implementation narrows BEFORE it reads', () => {
93+
it('`validateSchema(null)` returns INVALID_SCHEMA instead of throwing a raw TypeError', () => {
94+
const result = validateSchema(null);
95+
expect(result.valid).toBe(false);
96+
// Named, not merely `valid === false`: a validator that broke outright and
97+
// a validator that reported nothing would both satisfy the boolean.
98+
expect(result.errors.map((e) => e.code)).toEqual(['INVALID_SCHEMA']);
99+
expect(result.errors[0].path).toBe('schema');
100+
});
101+
102+
it('`validateSchema(undefined)` returns INVALID_SCHEMA instead of throwing a raw TypeError', () => {
103+
const result = validateSchema(undefined);
104+
expect(result.valid).toBe(false);
105+
expect(result.errors.map((e) => e.code)).toEqual(['INVALID_SCHEMA']);
106+
});
107+
108+
it('`isValidSchema(null)` answers `false`, which is the boolean its docblock promises', () => {
109+
expect(isValidSchema(null)).toBe(false);
110+
expect(isValidSchema(undefined)).toBe(false);
111+
});
112+
113+
it("`assertValidSchema(null)` throws the validator's OWN refusal, not a TypeError", () => {
114+
// The distinction is the point. Both spellings "throw", so a bare
115+
// `.toThrow()` would have passed before this change too — the pin is on
116+
// WHICH error, because a `TypeError` from inside the validator is the
117+
// failure and `Schema validation failed:` is the contract.
118+
expect(() => assertValidSchema(null)).toThrow(/Schema validation failed:/);
119+
expect(() => assertValidSchema(null)).not.toThrow(TypeError);
120+
});
121+
122+
it('a `null` entry inside `fields` is REPORTED, not thrown on', () => {
123+
// The same defect one level down: `fields` is authored data too, and its
124+
// entries were read with `field.name` before anything checked them.
125+
const result = validateSchema({ type: 'form', fields: [null, { name: 'ok' }] });
126+
expect(result.valid).toBe(false);
127+
expect(result.errors.map((e) => e.code)).toContain('MISSING_FIELD_NAME');
128+
expect(result.errors.find((e) => e.code === 'MISSING_FIELD_NAME')?.path).toBe(
129+
'schema.fields[0]',
130+
);
131+
});
132+
133+
it('a `null` entry inside `children` is still SKIPPED, as it always was', () => {
134+
// The counterpart, and the reason the narrowing is not a licence to start
135+
// reporting things: `validateChildren` already guarded each child, so a
136+
// `null` hole stays silent. Only the guard's SPELLING moved.
137+
const result = validateSchema({ type: 'form', children: [null, { type: 'input' }] });
138+
expect(result.valid).toBe(true);
139+
expect(result.errors).toHaveLength(0);
140+
});
141+
});
142+
143+
describe('objectui#8416 — every verdict that already existed is unchanged', () => {
144+
it('primitives keep their single INVALID_SCHEMA error', () => {
145+
for (const probe of [42, 'str', true, 0, '', false]) {
146+
const result = validateSchema(probe);
147+
expect(result.errors.map((e) => e.code), `probe ${String(probe)}`).toEqual([
148+
'INVALID_SCHEMA',
149+
]);
150+
}
151+
});
152+
153+
it('an ARRAY node keeps its MISSING_REQUIRED verdict — `typeof [] === "object"` still passes', () => {
154+
// Deliberately inside the narrowed type. An array is not a schema, but the
155+
// guard this replaces let it through to the `type` rule and reported the
156+
// missing key, and that is the message an author already gets.
157+
const result = validateSchema([]);
158+
expect(result.errors.map((e) => e.code)).toEqual(['MISSING_REQUIRED']);
159+
});
160+
161+
it('a retired type nested under `children` is still refused, with its own path', () => {
162+
const result = validateSchema({ type: 'form', children: [{ type: 'crud' }] });
163+
const refusal = result.errors.find((e) => e.code === 'RETIRED_TYPE');
164+
expect(refusal).toBeDefined();
165+
expect(refusal?.path).toBe('schema.children[0].type');
166+
});
167+
168+
it('duplicate field names still warn, once per offending field', () => {
169+
const result = validateSchema({
170+
type: 'form',
171+
fields: [{ name: 'a' }, { name: 'a' }],
172+
});
173+
expect(result.warnings.map((w) => w.code)).toEqual([
174+
'DUPLICATE_FIELD_NAME',
175+
'DUPLICATE_FIELD_NAME',
176+
]);
177+
expect(result.warnings[0].message).toBe('Duplicate field name: a');
178+
});
179+
});

0 commit comments

Comments
 (0)