From 94b98352b3d6ad77bb18f3cd7350f91c57dbbe7d Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Sun, 4 Oct 2026 20:24:14 -0400 Subject: [PATCH 1/2] refactor(sections): read every schema through one public-API adapter instead of three private walkers Four walkers each reached into zod's private `_zod.def` through a hand-mirrored def view, carried their own "unhandled schema type" BUG throw and leaf whitelist, and cast through `unknown`: `projectOntoSchema` and `replaceSweep` (snapshot-helpers), `canonicalNode`/`admits` (engine/canonical), and `loosen`/`detectKnobUnion`/`cloneWith` (contract/module). Four test-side copies and the JSON schema generator read the same internals. One adapter now does the reading, through zod's public classes and `.def`: `schemaNode(schema: z.ZodType): SchemaNode` in src/sections/shared/schema-node.ts. Its closed union: - object: shape, catchall, open (a catchall other than never; a strip object stays closed to the walks) - array: element - record: value - wrapper: inner plus the kind (optional, nullable, default, prefault, catch, nonoptional, readonly) - union: options plus knob, the knobbed()/layeredList() pair when the union is one (same detection as the deleted detectKnobUnion) - leaf: string, number, boolean, null, unknown, never, enum, literal, with an enum's or literal's values (duplicates kept, so a seeded draw is stable) Every walker consumes SchemaNode: the two snapshot helpers, the two canonical walkers, loosen (which now writes through public `z.clone(node.schema, { ...node.schema.def, patch })`, typed against the narrowed class), the canonical completeness test, the slice identity test, the raw-sibling walk, the fuzz generator, and the generator override. `defOf`, `ZodDef`, `cloneWith`, `detectKnobUnion`, and the four test-side def views are deleted. The one BUG throw and the one leaf whitelist live in the adapter; `loosen` keeps only its own-refinements-on-a-knob BUG. Behavior on the shipped schemas is unchanged: 2174 tests pass, the e2e suite passes 370/370, and lib/settings.schema.json built from this tree is byte-identical (cmp) to a build at the base branch. The one test edit is the expected text of the moved unhandled-type BUG in test/sections/loosen.test.ts. Two deliberate readings the old walkers did not share. The "int" leaf entry is gone: `z.int().type` is "number" in zod 4, and a walk over every node of SettingsFile met exactly these types: array, boolean, default, enum, literal, never, null, nullable, number, object, optional, record, string, union, unknown. The four extra wrappers (prefault, catch, nonoptional, readonly), absent from that census, are looked through by every walk where before two walkers threw, two fell through, and the generator looked through. `_zod` census over src/, .github/scripts/, and test/: 6 hits before, 0 after. --- .github/scripts/gen-settings-schema.ts | 12 +-- src/engine/canonical.ts | 70 ++++++------- src/sections/contract/module.ts | 99 ++++--------------- src/sections/shared/schema-node.ts | 125 ++++++++++++++++++++++++ src/sections/shared/snapshot-helpers.ts | 81 ++++++--------- test/e2e/gen-support.ts | 85 +++++++--------- test/engine/canonical.test.ts | 54 ++++------ test/schema-slices.test.ts | 52 +++++----- test/sections/loosen.test.ts | 6 +- test/sections/raw-sibling.test.ts | 119 +++++++++++----------- 10 files changed, 345 insertions(+), 358 deletions(-) create mode 100644 src/sections/shared/schema-node.ts 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-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 []; } } From 2b508fe764c940c89170a9b489e86e0cbb4e7dce Mon Sep 17 00:00:00 2001 From: Vivswan Shah <58091053+Vivswan@users.noreply.github.com> Date: Sun, 4 Oct 2026 20:26:46 -0400 Subject: [PATCH 2/2] docs(sections): point the knob-union comment at the schema adapter schemaNode() in src/sections/shared/schema-node.ts is now the one place that recognizes the knobbed()/layeredList() union by the wrapper's entries; loosen() and engine/canonical.ts consume its union.knob instead of detecting the pair themselves. --- src/sections/shared/schema-helpers.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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