Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions .github/scripts/gen-settings-schema.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<string, unknown>;
// 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
Expand All @@ -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
Expand Down
70 changes: 36 additions & 34 deletions src/engine/canonical.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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;
}
}
}

Expand All @@ -223,59 +229,55 @@ 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)) {
return unknownNode(value);
}
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)) {
return unknownNode(value);
}
const out: Record<string, unknown> = {};
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);
}
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);
}
Expand Down
99 changes: 18 additions & 81 deletions src/sections/contract/module.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -796,117 +797,53 @@ 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<string, z.ZodType>;
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<ZodDef>): z.ZodType {
return z.util.clone(
schema as unknown as Parameters<typeof z.util.clone>[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:
*
* 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<string> = 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
Expand Down
8 changes: 4 additions & 4 deletions src/sections/shared/schema-helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading
Loading