diff --git a/.github/scripts/gen-settings-schema.ts b/.github/scripts/gen-settings-schema.ts index 5b2b5405e..8fc29eff8 100644 --- a/.github/scripts/gen-settings-schema.ts +++ b/.github/scripts/gen-settings-schema.ts @@ -20,25 +20,21 @@ import { join } from "node:path"; import { z } from "zod"; import { SettingsFile } from "../../src/schema.js"; import { SCHEMA_DESCRIPTIONS } from "../../src/sections/docs-registry.js"; +import { schemaNode } from "../../src/sections/shared/schema-node.js"; import { attachDescriptions, type JsonSchemaNode } from "./lib/schema-descriptions.js"; import { SCHEMA_ID } from "./lib/schema-id.js"; const ROOT = join(import.meta.dir, "..", ".."); -interface ZodDefView { - type?: string; - catchall?: unknown; -} - const generated = z.toJSONSchema(SettingsFile, { target: "draft-7", io: "input", override(ctx) { - const def = (ctx.zodSchema as unknown as { _zod: { def: ZodDefView } })._zod.def; + const node = ctx.zodSchema instanceof z.ZodType ? schemaNode(ctx.zodSchema) : null; const json = ctx.jsonSchema as Record; // The runtime passes unknown keys of a plain object through to GitHub, and the published schema must not reject // what the runtime accepts. Strict objects carry a catchall (z.never) and keep their false. - if (def.type === "object" && def.catchall === undefined) { + if (node?.kind === "object" && node.catchall === undefined) { delete json.additionalProperties; } // The published schema carries no format keyword, so this covers ajv-formats grammars the runtime does not share @@ -48,7 +44,7 @@ const generated = z.toJSONSchema(SettingsFile, { delete json.format; } // z.record's propertyNames: {type: "string"} is a no-op in JSON (keys are always strings). - if (def.type === "record" && JSON.stringify(json.propertyNames) === '{"type":"string"}') { + if (node?.kind === "record" && JSON.stringify(json.propertyNames) === '{"type":"string"}') { delete json.propertyNames; } // z.int()'s implicit safe-integer bounds are a JS implementation detail, not part of the documented file diff --git a/src/engine/canonical.ts b/src/engine/canonical.ts index 17a8a2580..320c11f2e 100644 --- a/src/engine/canonical.ts +++ b/src/engine/canonical.ts @@ -21,7 +21,7 @@ import { stringify as stringifyYaml } from "yaml"; import type { z } from "zod"; import { isPlainObject, own, put } from "../plain-data.js"; import { SECTION_KEYS, SettingsFile } from "../schema.js"; -import { defOf, detectKnobUnion } from "../sections/contract/module.js"; +import { schemaNode } from "../sections/shared/schema-node.js"; /** * The identity field of every mapping list the walk sorts, by list path: the section key, `[]` per entry level, @@ -179,30 +179,36 @@ function sortEntries(path: string, entries: readonly unknown[]): unknown[] { /** Whether a value could be an instance of the option, by shape alone; the walk parses only when two options could. */ function admits(schema: z.ZodType, value: unknown): boolean { - const def = defOf(schema); - switch (def.type) { + const node = schemaNode(schema); + switch (node.kind) { case "array": return Array.isArray(value); case "object": case "record": return isPlainObject(value); - case "optional": - case "default": - return value === undefined || admits(def.innerType as z.ZodType, value); - case "nullable": - return value === null || admits(def.innerType as z.ZodType, value); - case "null": - return value === null; - case "string": - return typeof value === "string"; - case "number": - return typeof value === "number"; - case "boolean": - return typeof value === "boolean"; + case "wrapper": + switch (node.wrap) { + case "optional": + case "default": + return value === undefined || admits(node.inner, value); + case "nullable": + return value === null || admits(node.inner, value); + default: + return true; + } case "union": - return (def.options ?? []).some((option) => admits(option, value)); - default: - return true; + return node.options.some((option) => admits(option, value)); + case "leaf": + switch (node.type) { + case "null": + return value === null; + case "string": + case "number": + case "boolean": + return typeof value === node.type; + default: + return true; + } } } @@ -223,18 +229,15 @@ function canonicalNode(value: unknown, schema: z.ZodType | undefined, path: stri if (schema === undefined || value === null || value === undefined) { return unknownNode(value); } - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - return canonicalNode(value, def.innerType as z.ZodType, path); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + return canonicalNode(value, node.inner, path); case "object": { if (!isPlainObject(value)) { return unknownNode(value); } - const shape = def.shape ?? {}; - return mappingNode(value, shape, Object.keys(shape), (key) => `${path}.${key}`); + return mappingNode(value, node.shape, Object.keys(node.shape), (key) => `${path}.${key}`); } case "array": if (!Array.isArray(value)) { @@ -242,7 +245,7 @@ function canonicalNode(value: unknown, schema: z.ZodType | undefined, path: stri } return sortEntries( path, - value.map((item) => canonicalNode(item, def.element as z.ZodType, `${path}[]`)), + value.map((item) => canonicalNode(item, node.element, `${path}[]`)), ); case "record": { if (!isPlainObject(value)) { @@ -250,13 +253,12 @@ function canonicalNode(value: unknown, schema: z.ZodType | undefined, path: stri } const out: Record = {}; for (const key of orderedKeys(value, [])) { - put(out, key, canonicalNode(value[key], def.valueType as z.ZodType, `${path}.*`)); + put(out, key, canonicalNode(value[key], node.value, `${path}.*`)); } return out; } case "union": { - const options = def.options ?? []; - const knob = detectKnobUnion(options); + const { knob } = node; if (knob !== null) { if (Array.isArray(value)) { return canonicalNode(value, knob.list, path); @@ -264,18 +266,18 @@ function canonicalNode(value: unknown, schema: z.ZodType | undefined, path: stri if (!isPlainObject(value)) { return unknownNode(value); } - const shape = defOf(knob.wrapper).shape ?? {}; + const { shape } = knob.wrapper; // The wrapper is transparent to the list path, so `labels` names the entries under both forms. return mappingNode(value, shape, Object.keys(shape), (key) => key === "entries" ? path : `${path}.${key}`, ); } - const fits = options.filter((option) => admits(option, value)); + const fits = node.options.filter((option) => admits(option, value)); const option = fits.length > 1 ? (fits.find((o) => o.safeParse(value).success) ?? fits[0]) : fits[0]; return option === undefined ? unknownNode(value) : canonicalNode(value, option, path); } - default: + case "leaf": // The scalar leaves; a mapping under z.unknown has no declared order. return unknownNode(value); } diff --git a/src/sections/contract/module.ts b/src/sections/contract/module.ts index 13da2412f..3e3e11d46 100644 --- a/src/sections/contract/module.ts +++ b/src/sections/contract/module.ts @@ -15,6 +15,7 @@ import type { UndeclaredPolicyList, } from "../../types.js"; import { type Layering, rule, type UNDECLARED_POLICIES } from "../shared/schema-helpers.js"; +import { schemaNode } from "../shared/schema-node.js"; import { type EndpointDecl, endpointKind, @@ -796,29 +797,6 @@ export function requirePlainMapping(shape: z.ZodType): z.ZodType { .pipe(shape); } -/** The zod internals a schema walk reads, one view for every walk in the tree. */ -export interface ZodDef { - type: string; - shape?: Record; - catchall?: z.ZodType; - element?: z.ZodType; - innerType?: z.ZodType; - options?: readonly z.ZodType[]; - valueType?: z.ZodType; - checks?: readonly unknown[]; -} - -export function defOf(schema: z.ZodType): ZodDef { - return (schema as unknown as { _zod: { def: ZodDef } })._zod.def; -} - -function cloneWith(schema: z.ZodType, patch: Partial): z.ZodType { - return z.util.clone( - schema as unknown as Parameters[0], - { ...defOf(schema), ...patch } as never, - ) as unknown as z.ZodType; -} - /** * Every plain (strip) object becomes a passthrough looseObject, so unknown keys ride through to GitHub and the * rules reading undeclared keys can see them. Preserved as authored: @@ -826,87 +804,46 @@ function cloneWith(schema: z.ZodType, patch: Partial): z.ZodType { * strictObject -> stays strict * a node's own checks -> survive on the clone (rule() gates each beside a failed nested value); one on the knobbed union itself throws * knobbed-section union -> rewrapped as a container-routed check, so a failing entry keeps its path (`labels[2].name`) - * unrecognized CONTAINER -> throws, rather than ship a shape that silently skipped loosening */ export function loosen(schema: z.ZodType): z.ZodType { - const def = defOf(schema); - switch (def.type) { + const node = schemaNode(schema); + switch (node.kind) { case "object": { - const shape = def.shape ?? {}; - const loosened = Object.fromEntries( - Object.entries(shape).map(([key, value]) => [key, loosen(value)]), + const shape = Object.fromEntries( + Object.entries(node.shape).map(([key, value]) => [key, loosen(value)]), ); // z.never stays never (strict stays strict); an absent catchall means strip, which becomes passthrough. - const catchall = def.catchall === undefined ? z.unknown() : loosen(def.catchall); - return cloneWith(schema, { shape: loosened, catchall }); + const catchall = node.catchall === undefined ? z.unknown() : loosen(node.catchall); + return z.clone(node.schema, { ...node.schema.def, shape, catchall }); } case "array": - return cloneWith(schema, { element: loosen(def.element as z.ZodType) }); + return z.clone(node.schema, { ...node.schema.def, element: loosen(node.element) }); case "record": - return cloneWith(schema, { valueType: loosen(def.valueType as z.ZodType) }); - case "optional": - case "nullable": - case "default": - return cloneWith(schema, { innerType: loosen(def.innerType as z.ZodType) }); + return z.clone(node.schema, { ...node.schema.def, valueType: loosen(node.value) }); + case "wrapper": + return z.clone(node.schema, { ...node.schema.def, innerType: loosen(node.inner) }); case "union": { - const options = def.options ?? []; - const knob = detectKnobUnion(options); + const { knob } = node; if (knob !== null) { - if ((def.checks?.length ?? 0) > 0) { + if ((node.schema.def.checks?.length ?? 0) > 0) { throw new Error( "BUG: loosen(): a knobbed-section union carries its own refinements, which the routed rewrap would silently drop - attach them to the entry array or the wrapper", ); } - return routedListShape(loosen(knob.list), loosen(knob.wrapper)); + return routedListShape(loosen(knob.list), loosen(knob.wrapper), knob.wrapper); } - return cloneWith(schema, { options: options.map(loosen) }); + return z.clone(node.schema, { ...node.schema.def, options: node.options.map(loosen) }); } - default: - if (!LOOSEN_LEAF_TYPES.has(def.type)) { - throw new Error( - `BUG: loosen(): unhandled schema type "${def.type}" - teach loosen() its runtime derivation before authoring it in src/schema.ts`, - ); - } + case "leaf": return schema; } } -const LOOSEN_LEAF_TYPES: ReadonlySet = new Set([ - "string", - "number", - "boolean", - "enum", - "literal", - "unknown", - "never", - "null", -]); - -/** The knobbed() and layeredList() unions (../shared/schema-helpers.ts): the entry array beside a strict wrapper with `entries`; engine/canonical.ts walks them by this detector too. */ -export function detectKnobUnion( - options: readonly z.ZodType[], -): { list: z.ZodType; wrapper: z.ZodType } | null { - if (options.length !== 2) { - return null; - } - const list = options.find((option) => defOf(option).type === "array"); - const wrapper = options.find((option) => { - const def = defOf(option); - return ( - def.type === "object" && - def.catchall !== undefined && - defOf(def.catchall).type === "never" && - def.shape?.entries !== undefined - ); - }); - return list !== undefined && wrapper !== undefined ? { list, wrapper } : null; -} - /** A transform, not a union, so a failing entry keeps its precise issue path and the output is the routed shape's parsed data. */ -function routedListShape(list: z.ZodType, wrapper: z.ZodType): z.ZodType { +function routedListShape(list: z.ZodType, wrapper: z.ZodType, authored: z.ZodObject): z.ZodType { // The wrapper's own words for what rides beside `entries`: the policy on a knobbed section, the directive alone on a plain list. const beside = - defOf(wrapper).shape?._undeclared === undefined + authored.shape._undeclared === undefined ? 'an optional "_layering" directive' : 'an optional "_undeclared" policy'; return z diff --git a/src/sections/shared/schema-helpers.ts b/src/sections/shared/schema-helpers.ts index 36f2a6b60..ac32c5922 100644 --- a/src/sections/shared/schema-helpers.ts +++ b/src/sections/shared/schema-helpers.ts @@ -99,10 +99,10 @@ function wrapperKeyError(issue: z.core.$ZodRawIssue, kind: WrapperKind): string } /** - * The bare list beside its strict wrapper, whose keys `shape` chooses around `entries`. loosen() (../contract/module.ts) - * and engine/canonical.ts recognize the union by the wrapper's `entries`. The wrapper's definition name derives from - * the list element's own .meta({id}), so the document composition and a section's runtime derivation can never label - * one entry differently. + * The bare list beside its strict wrapper, whose keys `shape` chooses around `entries`. schemaNode() (./schema-node.ts) + * recognizes the union as a knob by the wrapper's `entries`. The wrapper's definition name derives from the list + * element's own .meta({id}), so the document composition and a section's runtime derivation can never label one + * entry differently. * * element without an id -> throws at MODULE LOAD, not typecheck * z.toJSONSchema(SettingsFile) -> fine: it resolves metadata by schema identity diff --git a/src/sections/shared/schema-node.ts b/src/sections/shared/schema-node.ts new file mode 100644 index 000000000..d1a4d4f16 --- /dev/null +++ b/src/sections/shared/schema-node.ts @@ -0,0 +1,125 @@ +/** + * The ONE reading of a zod schema's structure, through zod's public classes and `.def`, for every walk over a + * section slice or the document schema. A schema kind no walk handles is refused here, once, so a new zod + * construct is taught its walk before it is authored in a slice. + * + * object.open -> a catchall other than never admits undeclared keys; a strip object (no catchall) is closed to the + * walks, and loosen() in ../contract/module.ts is what opens it at runtime + * union.knob -> the knobbed()/layeredList() pair (../shared/schema-helpers.ts): the bare entry array beside a + * strict wrapper carrying `entries`, which the canonical walk and loosen() route by container + * leaf.values -> what an enum or literal admits, duplicates included, so a seeded draw over them is stable + */ + +import { z } from "zod"; + +const WRAPPERS = [ + [z.ZodOptional, "optional"], + [z.ZodNullable, "nullable"], + [z.ZodDefault, "default"], + [z.ZodPrefault, "prefault"], + [z.ZodCatch, "catch"], + [z.ZodNonOptional, "nonoptional"], + [z.ZodReadonly, "readonly"], +] as const; + +type Wrapper = InstanceType<(typeof WRAPPERS)[number][0]>; + +type WrapperKind = (typeof WRAPPERS)[number][1]; + +type LeafType = "string" | "number" | "boolean" | "null" | "unknown" | "never" | "enum" | "literal"; + +/** The two forms a knobbed or layered list section takes: the bare entry array, or the strict wrapper with `entries`. */ +interface KnobUnion { + readonly list: z.ZodArray; + readonly wrapper: z.ZodObject; +} + +export type SchemaNode = + | { + readonly kind: "object"; + readonly schema: z.ZodObject; + readonly shape: Readonly>; + readonly catchall: z.ZodType | undefined; + readonly open: boolean; + } + | { readonly kind: "array"; readonly schema: z.ZodArray; readonly element: z.ZodType } + | { readonly kind: "record"; readonly schema: z.ZodRecord; readonly value: z.ZodType } + | { + readonly kind: "wrapper"; + readonly schema: Wrapper; + readonly wrap: WrapperKind; + readonly inner: z.ZodType; + } + | { + readonly kind: "union"; + readonly schema: z.ZodUnion; + readonly options: readonly z.ZodType[]; + readonly knob: KnobUnion | null; + } + | { readonly kind: "leaf"; readonly type: LeafType; readonly values: readonly unknown[] }; + +/** zod types a child by its core supertype; every schema in this tree is built with the classic API, which this restores. */ +function classic(schema: z.core.$ZodType): z.ZodType { + return schema as z.ZodType; +} + +function knobUnion(options: readonly z.ZodType[]): KnobUnion | null { + if (options.length !== 2) { + return null; + } + const list = options.find((option): option is z.ZodArray => option instanceof z.ZodArray); + const wrapper = options.find( + (option): option is z.ZodObject => + option instanceof z.ZodObject && + option.def.catchall instanceof z.ZodNever && + option.shape.entries !== undefined, + ); + return list !== undefined && wrapper !== undefined ? { list, wrapper } : null; +} + +export function schemaNode(schema: z.ZodType): SchemaNode { + if (schema instanceof z.ZodObject) { + const catchall = schema.def.catchall === undefined ? undefined : classic(schema.def.catchall); + return { + kind: "object", + schema, + shape: schema.shape, + catchall, + open: catchall !== undefined && !(catchall instanceof z.ZodNever), + }; + } + if (schema instanceof z.ZodArray) { + return { kind: "array", schema, element: classic(schema.element) }; + } + if (schema instanceof z.ZodRecord) { + return { kind: "record", schema, value: classic(schema.valueType) }; + } + for (const [wrapperClass, wrap] of WRAPPERS) { + if (schema instanceof wrapperClass) { + return { kind: "wrapper", schema, wrap, inner: classic(schema.unwrap()) }; + } + } + if (schema instanceof z.ZodUnion) { + const options = schema.options.map(classic); + return { kind: "union", schema, options, knob: knobUnion(options) }; + } + if (schema instanceof z.ZodEnum) { + return { kind: "leaf", type: "enum", values: Object.values(schema.enum) }; + } + if (schema instanceof z.ZodLiteral) { + return { kind: "leaf", type: "literal", values: schema.def.values }; + } + switch (schema.type) { + case "string": + case "number": + case "boolean": + case "null": + case "unknown": + case "never": + return { kind: "leaf", type: schema.type, values: [] }; + default: + throw new Error( + `BUG: schemaNode(): unhandled schema type "${schema.type}" - teach schema-node.ts its walk before authoring it in a section slice`, + ); + } +} diff --git a/src/sections/shared/snapshot-helpers.ts b/src/sections/shared/snapshot-helpers.ts index df6b19e61..81e7984ba 100644 --- a/src/sections/shared/snapshot-helpers.ts +++ b/src/sections/shared/snapshot-helpers.ts @@ -11,20 +11,9 @@ import { isPlainObject } from "../../plain-data.js"; import type { UndeclaredPolicySection } from "../../schema.js"; import type { UndeclaredPolicyList } from "../../types.js"; import type { SectionFailure } from "../contract/errors.js"; -import { defaultUndeclaredPolicy, defOf, type SectionMeta } from "../contract/module.js"; +import { defaultUndeclaredPolicy, type SectionMeta } from "../contract/module.js"; import type { SnapshotContext } from "../contract/plan.js"; - -/** The schema types the projection treats as leaves: the live value passes through verbatim. */ -const LEAF_TYPES: ReadonlySet = new Set([ - "string", - "number", - "int", - "boolean", - "enum", - "literal", - "unknown", - "null", -]); +import { schemaNode } from "./schema-node.js"; /** * A live value projected onto a schema slice, so server-assigned fields fall away without a hand @@ -48,28 +37,24 @@ function project(schema: z.ZodType, live: unknown): unknown { if (live === null) { return schema.safeParse(null).success ? null : undefined; } - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - return project(def.innerType as z.ZodType, live); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + return project(node.inner, live); case "object": { if (!isPlainObject(live)) { return live; } - const shape = def.shape ?? {}; const out: Record = {}; - for (const [key, child] of Object.entries(shape)) { + for (const [key, child] of Object.entries(node.shape)) { const projected = project(child, live[key]); if (projected !== undefined) { out[key] = projected; } } - // A catchall other than never is a passthrough object: its extra keys are declarable. - if (def.catchall !== undefined && defOf(def.catchall).type !== "never") { + if (node.open) { for (const [key, value] of Object.entries(live)) { - if (!(key in shape) && value !== undefined) { + if (!(key in node.shape) && value !== undefined) { out[key] = value; } } @@ -77,28 +62,18 @@ function project(schema: z.ZodType, live: unknown): unknown { return out; } case "array": - return Array.isArray(live) - ? live.map((item) => project(def.element as z.ZodType, item)) - : live; + return Array.isArray(live) ? live.map((item) => project(node.element, item)) : live; case "record": return isPlainObject(live) ? Object.fromEntries( - Object.entries(live).map(([key, value]) => [ - key, - project(def.valueType as z.ZodType, value), - ]), + Object.entries(live).map(([key, value]) => [key, project(node.value, value)]), ) : live; case "union": { - const option = (def.options ?? []).find((candidate) => candidate.safeParse(live).success); + const option = node.options.find((candidate) => candidate.safeParse(live).success); return option === undefined ? live : project(option, live); } - default: - if (!LEAF_TYPES.has(def.type)) { - throw new Error( - `BUG: projectOntoSchema(): unhandled schema type "${def.type}" - teach the projection its walk before authoring it in a section slice`, - ); - } + case "leaf": return live; } } @@ -122,39 +97,39 @@ function collectSweep( passthrough: string[], nullable: string[], ): void { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "default": - collectSweep(def.innerType as z.ZodType, path, passthrough, nullable); - return; - case "nullable": - nullable.push(path); - collectSweep(def.innerType as z.ZodType, path, passthrough, nullable); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + if (node.wrap === "nullable") { + nullable.push(path); + } + collectSweep(node.inner, path, passthrough, nullable); return; case "array": - collectSweep(def.element as z.ZodType, `${path}[]`, passthrough, nullable); + collectSweep(node.element, `${path}[]`, passthrough, nullable); return; case "union": - for (const option of def.options ?? []) { + for (const option of node.options) { collectSweep(option, path, passthrough, nullable); } return; case "object": { - if (def.catchall !== undefined && defOf(def.catchall).type !== "never") { + if (node.open) { passthrough.push(path); return; } - for (const [key, child] of Object.entries(def.shape ?? {})) { + for (const [key, child] of Object.entries(node.shape)) { collectSweep(child, path === "" ? key : `${path}.${key}`, passthrough, nullable); } return; } case "record": - case "unknown": passthrough.push(path); return; - default: + case "leaf": + if (node.type === "unknown") { + passthrough.push(path); + } return; } } diff --git a/test/e2e/gen-support.ts b/test/e2e/gen-support.ts index 87c73eb5c..249c83d22 100644 --- a/test/e2e/gen-support.ts +++ b/test/e2e/gen-support.ts @@ -10,6 +10,7 @@ import type { ListSectionKey, ListSectionModule, } from "../../src/sections/shared/list-section.js"; +import { schemaNode } from "../../src/sections/shared/schema-node.js"; import type { LiveState } from "./mock/state.js"; import type { Rng } from "./prng.js"; @@ -149,21 +150,6 @@ export function assertSentinelDisjoint(condition: boolean, detail: string): void // --- Generators from slices -------------------------------------------------- -/** Read off zod's internal `_zod.def`, not a public API, so a zod upgrade can rename these. */ -interface SliceDef { - type: string; - shape?: Record; - element?: z.ZodType; - innerType?: z.ZodType; - options?: readonly z.ZodType[]; - entries?: Record; - values?: readonly unknown[]; -} - -function defOf(schema: z.ZodType): SliceDef { - return (schema as unknown as { _zod: { def: SliceDef } })._zod.def; -} - export interface SliceSeed { /** Per field, the pool to draw its value from; a field not named here draws a type-derived value. */ readonly fields?: Readonly unknown>>; @@ -176,13 +162,12 @@ export interface SliceSeed { * slice, so a draw a refinement rejects throws naming the field. */ export function generatorFromSlice(slice: z.ZodType, seed: SliceSeed = {}): (rng: Rng) => Json { - if (defOf(slice).shape === undefined) { - throw new Error( - `generatorFromSlice: the slice is a ${defOf(slice).type}, not an object schema`, - ); + const node = schemaNode(slice); + if (node.kind !== "object") { + throw new Error(`generatorFromSlice: the slice is a ${node.kind}, not an object schema`); } return (rng) => { - const entry = drawObject(slice, seed, rng); + const entry = drawObject(node.shape, seed, rng); // Parsed once at the outer boundary, so a nested issue names its full path. const parsed = slice.safeParse(entry); if (!parsed.success) { @@ -197,10 +182,12 @@ export function generatorFromSlice(slice: z.ZodType, seed: SliceSeed = {}): (rng } /** Validation belongs to the caller holding the root slice, so a nested issue names its full path. */ -function drawObject(schema: z.ZodType, seed: SliceSeed, rng: Rng): Json { +function drawObject(shape: Readonly>, seed: SliceSeed, rng: Rng): Json { const entry: Json = {}; - for (const [field, child] of Object.entries(defOf(schema).shape ?? {})) { - const omittable = ["optional", "default"].includes(defOf(child).type); + for (const [field, child] of Object.entries(shape)) { + const node = schemaNode(child); + const omittable = + node.kind === "wrapper" && (node.wrap === "optional" || node.wrap === "default"); if (omittable && !rng.bool(seed.present?.[field] ?? 0.5)) { continue; } @@ -211,37 +198,35 @@ function drawObject(schema: z.ZodType, seed: SliceSeed, rng: Rng): Json { } function drawFrom(schema: z.ZodType, rng: Rng, path: string): unknown { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - case "prefault": - case "catch": - case "nonoptional": - case "readonly": - return drawFrom(def.innerType as z.ZodType, rng, path); - case "string": - return genName(rng); - case "number": - return rng.int(100); - case "boolean": - return rng.bool(); - case "enum": - return rng.pick(Object.values(def.entries ?? {})); - case "literal": - return rng.pick(def.values ?? []); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + return drawFrom(node.inner, rng, path); case "array": - return Array.from({ length: rng.int(3) }, () => - drawFrom(def.element as z.ZodType, rng, `${path}[]`), - ); + return Array.from({ length: rng.int(3) }, () => drawFrom(node.element, rng, `${path}[]`)); case "union": - return drawFrom(rng.pick(def.options ?? []), rng, path); + return drawFrom(rng.pick(node.options), rng, path); case "object": - return drawObject(schema, {}, rng); - default: + return drawObject(node.shape, {}, rng); + case "leaf": + switch (node.type) { + case "string": + return genName(rng); + case "number": + return rng.int(100); + case "boolean": + return rng.bool(); + case "enum": + case "literal": + return rng.pick(node.values); + default: + throw new Error( + `generatorFromSlice: no draw for the ${node.type} at "${path}" - seed the field with a pool`, + ); + } + case "record": throw new Error( - `generatorFromSlice: no draw for the ${def.type} at "${path}" - seed the field with a pool`, + `generatorFromSlice: no draw for the record at "${path}" - seed the field with a pool`, ); } } diff --git a/test/engine/canonical.test.ts b/test/engine/canonical.test.ts index 5c2038337..85149932a 100644 --- a/test/engine/canonical.test.ts +++ b/test/engine/canonical.test.ts @@ -15,6 +15,7 @@ import { } from "../../src/engine/canonical.js"; import { DOCUMENT_DIRECTIVE_KEYS, SECTION_KEYS, SettingsFile } from "../../src/schema.js"; import { SECTIONS } from "../../src/sections/registry.js"; +import { schemaNode } from "../../src/sections/shared/schema-node.js"; /** A document spelled in the canonical order, so the shuffled twin below has something to converge on. */ const ORDERED: Record = { @@ -228,66 +229,49 @@ function _directivesFirst(): Array<[string, unknown]> { return DOCUMENT_DIRECTIVE_KEYS.map((key) => [key, "deep"]); } -interface Def { - type: string; - shape?: Record; - element?: z.ZodType; - innerType?: z.ZodType; - options?: readonly z.ZodType[]; - valueType?: z.ZodType; -} - -const defOf = (schema: z.ZodType): Def => (schema as unknown as { _zod: { def: Def } })._zod.def; - -/** Every list of mappings the schema declares, by the path LIST_IDENTITY spells (a knob wrapper's `entries` transparent). */ /** Whether a list of this element is a mapping list: a mapping, or a union whose options include one (a ruleset's rules). */ function isMappingSchema(schema: z.ZodType): boolean { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - return isMappingSchema(def.innerType as z.ZodType); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + return isMappingSchema(node.inner); case "object": case "record": return true; case "union": - return (def.options ?? []).some(isMappingSchema); + return node.options.some(isMappingSchema); default: return false; } } +/** Every list of mappings the schema declares, by the path LIST_IDENTITY spells (a knob wrapper's `entries` transparent). */ function mappingListPaths(schema: z.ZodType, path: string, out: Set): void { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - mappingListPaths(def.innerType as z.ZodType, path, out); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + mappingListPaths(node.inner, path, out); return; case "object": - for (const [key, child] of Object.entries(def.shape ?? {})) { + for (const [key, child] of Object.entries(node.shape)) { mappingListPaths(child, path === "" ? key : `${path}.${key}`, out); } return; case "array": { - const element = def.element as z.ZodType; - if (isMappingSchema(element)) { + if (isMappingSchema(node.element)) { out.add(path); } - mappingListPaths(element, `${path}[]`, out); + mappingListPaths(node.element, `${path}[]`, out); return; } case "record": - mappingListPaths(def.valueType as z.ZodType, `${path}.*`, out); + mappingListPaths(node.value, `${path}.*`, out); return; case "union": { - const options = def.options ?? []; - const wrapper = options.find((option) => defOf(option).shape?.entries !== undefined); - for (const option of options) { + const wrapper = node.knob?.wrapper; + for (const option of node.options) { if (option === wrapper) { - for (const [key, child] of Object.entries(defOf(option).shape ?? {})) { + for (const [key, child] of Object.entries(wrapper.shape)) { mappingListPaths(child, key === "entries" ? path : `${path}.${key}`, out); } } else { @@ -296,7 +280,7 @@ function mappingListPaths(schema: z.ZodType, path: string, out: Set): vo } return; } - default: + case "leaf": return; } } diff --git a/test/schema-slices.test.ts b/test/schema-slices.test.ts index c90fe6b80..f99fc3363 100644 --- a/test/schema-slices.test.ts +++ b/test/schema-slices.test.ts @@ -29,23 +29,11 @@ import { PagesConfig } from "../src/sections/pages/schema.js"; import { RepositoryConfig } from "../src/sections/repository/schema.js"; import { RulesetConfig } from "../src/sections/rulesets/schema.js"; import { SecretScanningPatternConfig } from "../src/sections/secret_scanning_custom_patterns/schema.js"; +import { schemaNode } from "../src/sections/shared/schema-node.js"; import { TeamConfig } from "../src/sections/teams/schema.js"; import { WebhookConfig } from "../src/sections/webhooks/schema.js"; import { WorkflowsConfig } from "../src/sections/workflows/schema.js"; -/** The zod internals the unwrap below reads (the loosen() idiom). */ -interface ZodDefView { - type?: string; - innerType?: z.ZodType; - options?: readonly z.ZodType[]; - element?: z.ZodType; - shape?: Record; -} - -function defOf(schema: z.ZodType): ZodDefView { - return (schema as unknown as { _zod: { def: ZodDefView } })._zod.def; -} - /** * Keyed over SectionKey, so a new section fails to compile here until its expectation is declared. * @@ -90,31 +78,34 @@ const EXPECTED: Record< describe("SettingsFile slice composition identity", () => { for (const key of SECTION_KEYS) { test(`${key} is composed from its section's slice export`, () => { - const property = SettingsFile.shape[key] as z.ZodType; - const propertyDef = defOf(property); - expect(propertyDef.type, `${key}: the property must be .optional()`).toBe("optional"); - const inner = propertyDef.innerType as z.ZodType; + const property = schemaNode(SettingsFile.shape[key] as z.ZodType); + expect( + property.kind === "wrapper" && property.wrap === "optional", + `${key}: the property must be .optional()`, + ).toBe(true); + if (property.kind !== "wrapper") { + return; + } const expected = EXPECTED[key]; if (expected.kind === "slice") { expect( - inner === expected.slice, + property.inner === expected.slice, `${key}: the property's inner schema is not the section's slice export instance`, ).toBe(true); return; } // knobbed() and layeredList() build the inner union in root, so identity holds one level down. - const innerDef = defOf(inner); - expect(innerDef.type, `${key}: the wrapped property must wrap a union`).toBe("union"); - const options = innerDef.options ?? []; - const list = options.find((option) => defOf(option).type === "array"); - const wrapper = options.find((option) => defOf(option).type === "object"); - expect(list !== undefined && wrapper !== undefined, `${key}: wrapper branches missing`).toBe( - true, - ); - const entries = defOf(wrapper as z.ZodType).shape?.entries as z.ZodType; + const inner = schemaNode(property.inner); + expect(inner.kind, `${key}: the wrapped property must wrap a union`).toBe("union"); + const knob = inner.kind === "union" ? inner.knob : null; + expect(knob !== null, `${key}: wrapper branches missing`).toBe(true); + if (knob === null) { + return; + } + const entries = knob.wrapper.shape.entries as z.ZodType; if (expected.kind === "layered") { expect( - list === expected.slice, + knob.list === expected.slice, `${key}: the plain-array branch is not the section's list slice instance`, ).toBe(true); expect( @@ -124,11 +115,12 @@ describe("SettingsFile slice composition identity", () => { return; } expect( - defOf(list as z.ZodType).element === expected.entry, + knob.list.element === expected.entry, `${key}: the plain-array branch's element is not the entry slice instance`, ).toBe(true); + const entriesNode = schemaNode(entries); expect( - defOf(entries).element === expected.entry, + entriesNode.kind === "array" && entriesNode.element === expected.entry, `${key}: the wrapper's entries element is not the entry slice instance`, ).toBe(true); }); diff --git a/test/sections/loosen.test.ts b/test/sections/loosen.test.ts index 33e24e873..1ae972e23 100644 --- a/test/sections/loosen.test.ts +++ b/test/sections/loosen.test.ts @@ -1,6 +1,6 @@ /** - * cloneWith patches zod's internal def through a hand-mirrored view, so these are the tripwire a zod-internal rename (element, innerType, valueType, - * catchall) would otherwise turn into a silent no-op. + * loosen() derives the runtime shape by cloning each node with a patched def, so these pin the derivation itself: a + * strip object opens, a strict one stays, children are loosened, and the knobbed union is rerouted. */ import { describe, expect, test } from "bun:test"; @@ -82,7 +82,7 @@ describe("loosen", () => { test("an unrecognized container type fails loudly instead of skipping the derivation", () => { expect(() => loosen(z.tuple([z.string()]))).toThrow( new Error( - 'BUG: loosen(): unhandled schema type "tuple" - teach loosen() its runtime derivation before authoring it in src/schema.ts', + 'BUG: schemaNode(): unhandled schema type "tuple" - teach schema-node.ts its walk before authoring it in a section slice', ), ); }); diff --git a/test/sections/raw-sibling.test.ts b/test/sections/raw-sibling.test.ts index 42e0640bf..9e8727a18 100644 --- a/test/sections/raw-sibling.test.ts +++ b/test/sections/raw-sibling.test.ts @@ -12,22 +12,7 @@ import { z } from "zod"; import { validateSectionShapes } from "../../src/engine/validate.js"; import { SECTION_KEYS, type SectionKey, SettingsFile } from "../../src/schema.js"; import { rule } from "../../src/sections/shared/schema-helpers.js"; - -/** The zod internals the walk reads (the loosen() idiom). */ -interface DefView { - type: string; - shape?: Record; - element?: z.ZodType; - innerType?: z.ZodType; - options?: readonly z.ZodType[]; - valueType?: z.ZodType; - entries?: Record; - values?: readonly unknown[]; -} - -function defOf(schema: z.ZodType): DefView { - return (schema as unknown as { _zod: { def: DefView } })._zod.def; -} +import { schemaNode } from "../../src/sections/shared/schema-node.js"; function first(items: readonly T[] | undefined, what: string): T { const item = items?.[0]; @@ -43,37 +28,39 @@ function first(items: readonly T[] | undefined, what: string): T { * parse. A default wrapper unwraps to its inner type: the default value is what absence parses to, not a raw value. */ function canonical(schema: z.ZodType): unknown { - const def = defOf(schema); - switch (def.type) { + const node = schemaNode(schema); + switch (node.kind) { case "object": return Object.fromEntries( - Object.entries(def.shape ?? {}).map(([key, value]) => [key, canonical(value)]), + Object.entries(node.shape).map(([key, value]) => [key, canonical(value)]), ); case "array": - return [canonical(def.element as z.ZodType)]; + return [canonical(node.element)]; case "record": - return { key: canonical(def.valueType as z.ZodType) }; - case "optional": - case "nullable": - case "default": - return canonical(def.innerType as z.ZodType); + return { key: canonical(node.value) }; + case "wrapper": + return canonical(node.inner); case "union": - return canonical(first(def.options, "union")); - case "string": - case "unknown": - return "a"; - case "number": - return 1; - case "boolean": - return true; - case "null": - return null; - case "enum": - return first(Object.values(def.entries ?? {}), "enum"); - case "literal": - return first(def.values, "literal"); - default: - throw new Error(`no well-typed value for a "${def.type}" node; teach canonical() the node`); + return canonical(first(node.options, "union")); + case "leaf": + switch (node.type) { + case "string": + case "unknown": + return "a"; + case "number": + return 1; + case "boolean": + return true; + case "null": + return null; + case "enum": + case "literal": + return first(node.values, node.type); + default: + throw new Error( + `no well-typed value for a "${node.type}" node; teach canonical() the node`, + ); + } } } @@ -82,19 +69,25 @@ const ABSENT = Symbol("absent"); /** The other well-typed values a node admits: absence, null, false, the other options of an enum or union. */ function alternatives(schema: z.ZodType): unknown[] { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "default": - return [ABSENT, ...alternatives(def.innerType as z.ZodType)]; - case "nullable": - return [null, ...alternatives(def.innerType as z.ZodType)]; + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + switch (node.wrap) { + case "optional": + case "default": + return [ABSENT, ...alternatives(node.inner)]; + case "nullable": + return [null, ...alternatives(node.inner)]; + default: + return []; + } case "union": - return (def.options ?? []).slice(1).map(canonical); - case "boolean": - return [false]; - case "enum": - return Object.values(def.entries ?? {}).slice(1); + return node.options.slice(1).map(canonical); + case "leaf": + if (node.type === "boolean") { + return [false]; + } + return node.type === "enum" ? node.values.slice(1) : []; default: return []; } @@ -109,16 +102,14 @@ interface Gate { /** Every property below the canonical value with each other value it admits, one Gate per pair. */ function gates(schema: z.ZodType, prefix: readonly Step[] = []): Gate[] { - const def = defOf(schema); - switch (def.type) { - case "optional": - case "nullable": - case "default": - return gates(def.innerType as z.ZodType, prefix); + const node = schemaNode(schema); + switch (node.kind) { + case "wrapper": + return gates(node.inner, prefix); case "union": - return gates(first(def.options, "union"), prefix); + return gates(first(node.options, "union"), prefix); case "object": - return Object.entries(def.shape ?? {}).flatMap(([key, property]) => { + return Object.entries(node.shape).flatMap(([key, property]) => { const path = [...prefix, key]; return [ ...alternatives(property).map((value) => ({ path, value })), @@ -126,10 +117,10 @@ function gates(schema: z.ZodType, prefix: readonly Step[] = []): Gate[] { ]; }); case "array": - return gates(def.element as z.ZodType, [...prefix, 0]); + return gates(node.element, [...prefix, 0]); case "record": - return gates(def.valueType as z.ZodType, [...prefix, "key"]); - default: + return gates(node.value, [...prefix, "key"]); + case "leaf": return []; } }