@amritk/validation 0.2.0

package/dist/validators/generators/enforced-keywords.js

@@ -0,0 +1,70 @@
+import { MJST_EXTENSION_KEY } from "@amritk/helpers/mjst-extension";
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+const ENFORCED_KEYWORDS = /* @__PURE__ */ new Set([
+  "$ref",
+  "type",
+  "enum",
+  "const",
+  MJST_EXTENSION_KEY,
+  "pattern",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "items",
+  "prefixItems",
+  "additionalItems",
+  "contains",
+  "minContains",
+  "maxContains",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "properties",
+  "patternProperties",
+  "additionalProperties",
+  "required",
+  "propertyNames",
+  "dependentRequired",
+  "dependentSchemas",
+  "dependencies",
+  "minProperties",
+  "maxProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "not",
+  "if",
+  "then",
+  "else",
+  "unevaluatedProperties",
+  "unevaluatedItems"
+]);
+const declaresKeywordOutside = (schema, owned, formats = NO_FORMATS) => {
+  if (!isSchemaObject(schema))
+    return false;
+  const record = schema;
+  for (const keyword of Object.keys(record)) {
+    if (owned.includes(keyword))
+      continue;
+    if (ENFORCED_KEYWORDS.has(keyword))
+      return true;
+    if (keyword === "format" && enforcesFormat(record, formats))
+      return true;
+  }
+  return false;
+};
+const NO_FORMATS = /* @__PURE__ */ new Set();
+const enforcesFormat = (schema, formats) => {
+  const format = schema["format"];
+  return typeof format === "string" && formats.has(format);
+};
+export {
+  ENFORCED_KEYWORDS,
+  NO_FORMATS,
+  declaresKeywordOutside,
+  enforcesFormat
+};

package/dist/validators/generators/folds-to-constant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a subschema's verdict is decidable without looking at the instance —
+ * `true` when it accepts everything, `false` when it accepts nothing, and
+ * `undefined` when it depends on the value.
+ *
+ * The emitter asks the same question by building the subschema's checks and
+ * seeing whether any came out (`generateMatchesExpr` returns the literal
+ * `'true'`), and folds the branch away when they did not. Anything reading the
+ * emitter's *output* — which arms it emitted, which `validateX` calls it made —
+ * has to agree with it, and a predicate that under-answers costs only a branch
+ * kept alive, while one that over-answers drops a call that really is emitted.
+ * Hence the conservative `undefined`: this recognises the spellings that are
+ * decidable from the node alone and declines everything else.
+ */
+export declare const foldsToConstant: (schema: unknown, formats?: ReadonlySet<string>) => boolean | undefined;

package/dist/validators/generators/folds-to-constant.js

@@ -0,0 +1,43 @@
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { enforcesFormat, NO_FORMATS } from "./enforced-keywords.js";
+const ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+  "$anchor",
+  "$comment",
+  "$defs",
+  "$dynamicAnchor",
+  "$id",
+  "$schema",
+  "$vocabulary",
+  "contentEncoding",
+  "contentMediaType",
+  "contentSchema",
+  "default",
+  "definitions",
+  "deprecated",
+  "description",
+  "discriminator",
+  "example",
+  "examples",
+  "externalDocs",
+  "format",
+  "nullable",
+  "readOnly",
+  "title",
+  "writeOnly",
+  "xml"
+]);
+const foldsToConstant = (schema, formats = NO_FORMATS) => {
+  if (schema === true)
+    return true;
+  if (schema === false)
+    return false;
+  if (!isSchemaObject(schema))
+    return void 0;
+  const record = schema;
+  if (enforcesFormat(record, formats))
+    return void 0;
+  return Object.keys(record).every((key) => ANNOTATION_KEYWORDS.has(key)) ? true : void 0;
+};
+export {
+  foldsToConstant
+};

package/dist/validators/generators/generate-coerce-function.d.ts

@@ -0,0 +1,22 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/** The name of the value-coercing half generated for a `$ref`'s target. */
+export declare const coercerNameFor: (ref: string, typeSuffix: string) => string;
+/**
+ * Generates the coercing half of a validator file: a value-coercing walk, and
+ * the `coerceX` that runs it and then hands the result to `validateX`.
+ *
+ * Coercion is a separate pass rather than something threaded through the
+ * validator, which is what keeps every error identical to the one `validateX`
+ * already produced — same path, same keyword, same params, same `anyOf` branch
+ * selection. The validator is the only thing that decides anything; this pass
+ * only moves scalars toward what the schema asked for, and where it cannot, it
+ * hands the original value straight back so the validator rejects what the
+ * caller actually wrote rather than something substituted for it.
+ *
+ * The walk is exported because a `$ref` in another generated file needs it: a
+ * coercion has to cross a file boundary the same way validation does.
+ */
+export declare const generateCoerceFunction: (schema: JSONSchema, typeName: string, typeSuffix?: string) => {
+    code: string;
+    usesCoerceScalar: boolean;
+};

package/dist/validators/generators/generate-coerce-function.js

@@ -0,0 +1,208 @@
+import { regexFlagsFor } from "@amritk/helpers/escape-regex-pattern";
+import { declaresKey, readKey } from "@amritk/helpers/read-key";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+const COERCIBLE_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "null"]);
+const coercerNameFor = (ref, typeSuffix) => `coerce${refToName(ref, typeSuffix)}Value`;
+const declaresObjectKeys = (schema) => declaresKey(schema, "properties") || declaresKey(schema, "patternProperties") || declaresKey(schema, "additionalProperties");
+const declaresArrayItems = (schema) => declaresKey(schema, "items") || declaresKey(schema, "prefixItems");
+const schemaMap = (schema, key) => {
+  const value = readKey(schema, key);
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+};
+const soleScalarType = (schema) => {
+  const type = readKey(schema, "type");
+  return typeof type === "string" && COERCIBLE_TYPES.has(type) ? type : null;
+};
+const unionScalarTypes = (schema) => {
+  const declared = readKey(schema, "type");
+  if (Array.isArray(declared)) {
+    const types2 = declared.filter((entry) => typeof entry === "string");
+    return types2.length > 0 && types2.every((type) => COERCIBLE_TYPES.has(type)) ? types2 : null;
+  }
+  if (declared !== void 0)
+    return null;
+  const branches = readKey(schema, "anyOf") ?? readKey(schema, "oneOf");
+  if (!Array.isArray(branches) || branches.length === 0)
+    return null;
+  const types = [];
+  for (const branch of branches) {
+    if (!isSchemaObject(branch))
+      return null;
+    const type = soleScalarType(branch);
+    if (type !== null)
+      types.push(type);
+    else if (declaresObjectKeys(branch) || declaresArrayItems(branch))
+      continue;
+    else if (readKey(branch, "type") === "object")
+      continue;
+    else if (readKey(branch, "type") === "array")
+      continue;
+    else
+      return null;
+  }
+  return types.length > 0 ? types : null;
+};
+const emitObjectCoercer = (schema, ctx) => {
+  const properties = schemaMap(schema, "properties") ?? {};
+  const patternProperties = schemaMap(schema, "patternProperties") ?? {};
+  const additional = readKey(schema, "additionalProperties");
+  const declared = [];
+  for (const key of Object.keys(properties)) {
+    const coerce = coercerFor(readKey(properties, key), ctx);
+    if (coerce !== null)
+      declared.push({ key, coerce });
+  }
+  const patterns = [];
+  for (const source of Object.keys(patternProperties)) {
+    const coerce = coercerFor(readKey(patternProperties, source), ctx);
+    if (coerce !== null)
+      patterns.push({ source, coerce });
+  }
+  const additionalCoercer = typeof additional === "object" && additional !== null ? coercerFor(additional, ctx) : null;
+  if (declared.length === 0 && patterns.length === 0 && additionalCoercer === null)
+    return null;
+  const id = ctx.next();
+  const name = `_coerceObject${id}`;
+  const lines = [
+    `const ${name} = (input: unknown): unknown => {`,
+    `  if (typeof input !== 'object' || input === null || Array.isArray(input)) return input`,
+    `  const obj = input as Record<string, unknown>`,
+    `  let out: Record<string, unknown> | null = null`
+  ];
+  declared.forEach(({ key, coerce }, index) => {
+    const quoted = JSON.stringify(key);
+    const local = `_value${id}_${index}`;
+    lines.push(
+      // Own properties only. A plain `obj[key]` walks the prototype chain, and
+      // this pass *writes*: with `Object.prototype.flag` set by any dependency, an
+      // empty object was read as carrying `flag`, coerced, and handed back with
+      // `flag` as its own — inventing data the caller never sent, and satisfying
+      // a `required` the input actually violates. An absent key is not a value to
+      // coerce, and `{ a: undefined }` counts as absent everywhere else in this
+      // package, so it counts as absent here too.
+      `  const ${local} = Object.hasOwn(obj, ${quoted}) ? obj[${quoted}] : undefined`,
+      `  if (${local} !== undefined) {`,
+      `    const next = ${coerce(local)}`,
+      `    if (next !== ${local}) (out ??= { ...obj })[${quoted}] = next`,
+      `  }`
+    );
+  });
+  if (patterns.length > 0 || additionalCoercer !== null) {
+    const declaredKeys = Object.keys(properties);
+    const known = `_declared${id}`;
+    if (declaredKeys.length > 0) {
+      ctx.hoisted.push(`const ${known} = new Set(${JSON.stringify(declaredKeys)})`);
+    }
+    const patternNames = patterns.map((pattern, index) => {
+      const regexName = `_pattern${id}_${index}`;
+      ctx.hoisted.push(`const ${regexName} = new RegExp(${JSON.stringify(pattern.source)}, ${JSON.stringify(regexFlagsFor(pattern.source))})`);
+      return regexName;
+    });
+    lines.push(`  for (const key of Object.keys(obj)) {`);
+    if (declaredKeys.length > 0)
+      lines.push(`    if (${known}.has(key)) continue`);
+    lines.push(
+      `    const value = obj[key]`,
+      `    if (value === undefined) continue`,
+      // Annotated, not inferred: narrowing `unknown` by `!== undefined` leaves
+      // `{} | null`, and a coercion returns `unknown`, so the inferred binding
+      // rejected the very thing it exists to hold.
+      `    let next: unknown = value`
+    );
+    patterns.forEach((pattern, index) => {
+      lines.push(`    if (${patternNames[index]}.test(key)) next = ${pattern.coerce("next")}`);
+    });
+    if (additionalCoercer !== null) {
+      const guard = patternNames.length === 0 ? "" : `if (!(${patternNames.map((p) => `${p}.test(key)`).join(" || ")})) `;
+      lines.push(`    ${guard}next = ${additionalCoercer("next")}`);
+    }
+    lines.push(`    if (next !== value) (out ??= { ...obj })[key] = next`, `  }`);
+  }
+  lines.push(`  return out ?? input`, `}`);
+  ctx.helpers.push(lines.join("\n"));
+  return (valueExpr) => `${name}(${valueExpr})`;
+};
+const emitArrayCoercer = (schema, ctx) => {
+  const prefixItems = readKey(schema, "prefixItems");
+  const tuple = Array.isArray(prefixItems) ? prefixItems : [];
+  const tupleCoercers = tuple.map((item) => coercerFor(item, ctx));
+  const items = readKey(schema, "items");
+  const restCoercer = typeof items === "object" && items !== null && !Array.isArray(items) ? coercerFor(items, ctx) : null;
+  if (tupleCoercers.every((coerce) => coerce === null) && restCoercer === null)
+    return null;
+  const id = ctx.next();
+  const name = `_coerceArray${id}`;
+  const lines = [
+    `const ${name} = (input: unknown): unknown => {`,
+    `  if (!Array.isArray(input)) return input`,
+    `  let out: unknown[] | null = null`
+  ];
+  tupleCoercers.forEach((coerce, index) => {
+    if (coerce === null)
+      return;
+    const read = `input[${index}]`;
+    lines.push(
+      // `Object.hasOwn` rather than a length test, for the same reason the
+      // properties above use it: a hole reads through `Array.prototype`, and
+      // coercing what it finds there would turn a hole into an own element.
+      `  if (Object.hasOwn(input, ${index})) {`,
+      `    const next = ${coerce(read)}`,
+      `    if (next !== ${read}) (out ??= [...input])[${index}] = next`,
+      `  }`
+    );
+  });
+  if (restCoercer !== null) {
+    lines.push(`  for (let i = ${tuple.length}; i < input.length; i++) {`, `    if (!Object.hasOwn(input, i)) continue`, `    const value = input[i]`, `    const next = ${restCoercer("value")}`, `    if (next !== value) (out ??= [...input])[i] = next`, `  }`);
+  }
+  lines.push(`  return out ?? input`, `}`);
+  ctx.helpers.push(lines.join("\n"));
+  return (valueExpr) => `${name}(${valueExpr})`;
+};
+const coercerFor = (schema, ctx) => {
+  if (!isSchemaObject(schema))
+    return null;
+  const node = schema;
+  const ref = readKey(node, "$ref");
+  if (typeof ref === "string") {
+    const name = coercerNameFor(ref, ctx.typeSuffix);
+    return (valueExpr) => `${name}(${valueExpr})`;
+  }
+  const scalar = soleScalarType(node);
+  if (scalar !== null)
+    return (valueExpr) => `coerceScalar(${valueExpr}, ${JSON.stringify(scalar)})`;
+  const union = unionScalarTypes(node);
+  if (union !== null)
+    return (valueExpr) => `coerceUnion(${valueExpr}, ${JSON.stringify(union)})`;
+  const type = readKey(node, "type");
+  if (type === "object" || type === void 0 && declaresObjectKeys(node))
+    return emitObjectCoercer(node, ctx);
+  if (type === "array" || type === void 0 && declaresArrayItems(node))
+    return emitArrayCoercer(node, ctx);
+  return null;
+};
+const generateCoerceFunction = (schema, typeName, typeSuffix = "") => {
+  const helpers = [];
+  const hoisted = [];
+  let counter = 0;
+  const ctx = { typeSuffix, helpers, hoisted, next: () => counter++ };
+  const coerce = coercerFor(schema, ctx);
+  const valueName = `coerce${typeName}Value`;
+  const body = coerce === null ? "input" : coerce("input");
+  const parts = [...hoisted, ...helpers];
+  const walk = [
+    ...parts.length > 0 ? [parts.join("\n\n"), ""] : [],
+    `export const ${valueName} = (input: unknown): unknown => ${body}`,
+    "",
+    `export const coerce${typeName} = (input: unknown, _path = ''): CoercionResult<${typeName}> => {`,
+    `  const value = ${valueName}(input)`,
+    `  const result = validate${typeName}(value, _path)`,
+    `  return result === true ? { valid: true, value: value as ${typeName} } : { valid: false, errors: result.errors }`,
+    `}`
+  ].join("\n");
+  return { code: walk, usesCoerceScalar: walk.includes("coerceScalar(") || walk.includes("coerceUnion(") };
+};
+export {
+  coercerNameFor,
+  generateCoerceFunction
+};

package/dist/validators/generators/generate-files.d.ts

@@ -0,0 +1,92 @@
+import { type UnknownKeysStrategy } from '@amritk/helpers/unknown-keys-strategy';
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling what gets generated in a validator file.
+ */
+type GenerateValidatorFileOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/info`).
+     * Prevents the file from importing itself.
+     */
+    readonly selfRef?: string;
+    /**
+     * The root schema document. Used to filter out unresolvable refs.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+    /**
+     * Suffix appended to every type/validator name derived from a `$ref`.
+     * Defaults to `''` (no suffix).
+     */
+    readonly typeSuffix?: string;
+    /**
+     * How the fast paths prove a closed object carries no undeclared key —
+     * `Object.keys(obj).length` (the default) or a `for…in` count. See
+     * {@link UnknownKeysStrategy} for the trade-off between the two.
+     */
+    readonly unknownKeys?: UnknownKeysStrategy;
+    /**
+     * The `format` names this build enforces. Empty (the default) leaves `format`
+     * an annotation, as 2020-12 reads it; a name here makes the generated
+     * `validateX` and `isX` both check it, against a `formats.ts` emitted
+     * alongside.
+     */
+    readonly formats?: ReadonlySet<string>;
+    /**
+     * Whether to emit the fail-fast half — `checkX`, which answers with the same
+     * `ValidationResult` as `validateX` but stops at the first violation, so its
+     * `errors` array holds exactly one error. Off by default: a caller who wants
+     * every error should not carry a second body, and `validateX` / `isX` are
+     * byte-for-byte the same either way.
+     */
+    readonly check?: boolean;
+    /**
+     * Whether to emit the coercing half — `coerceX`, and the value walk a `$ref`
+     * in another file calls. Off by default: a caller who does not coerce should
+     * not carry the code, and `validateX` / `isX` are byte-for-byte the same
+     * either way.
+     */
+    readonly coerce?: boolean;
+    /**
+     * Whether to emit the repairing half — `repairX`, and the position lookup a
+     * `$ref` in another file calls. Implies {@link coerce}: `repairX` coerces
+     * first, so anything merely written in the wrong type is right before the
+     * validator ever sees it, and never shows up as a repair.
+     */
+    readonly repair?: boolean;
+    /** Extension on every emitted relative specifier: `'js'` (default) or `'ts'`. */
+    readonly importExt?: 'js' | 'ts';
+    /**
+     * Whether a failing `anyOf` / `oneOf` also reports the errors of the branch it
+     * meant. Off by default, and off is free — the emitted text is exactly what it
+     * was before the option existed.
+     */
+    readonly branchErrors?: boolean;
+};
+/**
+ * Generates a complete TypeScript validator file from a JSON Schema.
+ *
+ * The file contains:
+ * - Imports for the ValidationResult/ValidationError types
+ * - Imports for any $ref types and their validator functions
+ * - The exported TypeScript type definition
+ * - The exported validator function (`validateX`, rich `ValidationResult`)
+ * - The exported boolean type-guard (`isX`, a flat `input is X` predicate)
+ * - Optionally the fail-fast validator (`checkX`, the same `ValidationResult`
+ *   carrying only the first error)
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   type: 'object',
+ *   properties: { title: { type: 'string' } },
+ *   required: ['title'],
+ * }
+ * generateValidatorFile(schema, 'Info')
+ * // import type { ValidationResult, ValidationError } from './validation-result'
+ * // export type Info = { title: string }
+ * // export const validateInfo = (input: unknown, _path = ''): ValidationResult => { ... }
+ * // export const isInfo = (input: unknown): input is Info => { ... }
+ * ```
+ */
+export declare const generateValidatorFile: (schema: JSONSchema, typeName: string, options?: GenerateValidatorFileOptions) => string;
+export {};

package/dist/validators/generators/generate-files.js

@@ -0,0 +1,86 @@
+import { generateTypeDefinition } from "@amritk/helpers/generate-type-definition";
+import { identifierMentions } from "@amritk/helpers/identifier-mentions";
+import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
+import { collectValidatorImports } from "./collect-validator-imports.js";
+import { formatCheckName } from "./emit-format-checks.js";
+import { NO_FORMATS } from "./enforced-keywords.js";
+import { generateCoerceFunction } from "./generate-coerce-function.js";
+import { generateRepairFunction } from "./generate-repair-function.js";
+import { generateBooleanGuard, generateCheckFunction, generateValidatorFunction } from "./generate-validator-function.js";
+const generateValidatorFile = (schema, typeName, options) => {
+  const typeSuffix = options?.typeSuffix ?? "";
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    typeSuffix,
+    ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {}
+  });
+  const unknownKeys = options?.unknownKeys ?? DEFAULT_UNKNOWN_KEYS;
+  const importExt = options?.importExt ?? "js";
+  const formats = options?.formats ?? NO_FORMATS;
+  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema, unknownKeys, formats, options?.branchErrors === true);
+  const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix, unknownKeys, formats);
+  const checker = options?.check === true ? generateCheckFunction(schema, typeName, typeSuffix, options?.rootSchema, unknownKeys, formats) : "";
+  const wantsCoerce = options?.coerce === true || options?.repair === true;
+  const coercer = wantsCoerce ? generateCoerceFunction(schema, typeName, typeSuffix).code : "";
+  const repairer = options?.repair === true ? generateRepairFunction(schema, typeName, typeSuffix).code : "";
+  const appended = [checker, coercer, repairer].filter((part) => part !== "");
+  const body = validatorFunction + booleanGuard + (appended.length === 0 ? "" : "\n\n" + appended.join("\n\n"));
+  const mentions = identifierMentions(typeDefinition + body);
+  const refImports = collectValidatorImports(schema, {
+    selfRef: options?.selfRef,
+    rootSchema: options?.rootSchema,
+    typeSuffix,
+    importExt,
+    reads: ({ typeName: name, validatorName, checkerName, coercerName, repairerName }) => ({
+      type: mentions(name),
+      validator: mentions(validatorName),
+      checker: mentions(checkerName),
+      coercer: mentions(coercerName),
+      repairer: mentions(repairerName)
+    })
+  });
+  const resultTypes = [
+    "ValidationResult",
+    .../\bValidationError\b/.test(body) ? ["ValidationError"] : [],
+    .../\bCoercionResult\b/.test(body) ? ["CoercionResult"] : [],
+    .../\bRepairResult\b/.test(body) ? ["RepairResult"] : [],
+    .../\bRepairLookup\b/.test(body) ? ["RepairLookup"] : []
+  ];
+  let result = `import type { ${resultTypes.join(", ")} } from './validation-result.${importExt}'
+`;
+  const runtimeHelpers = [
+    "valuesEqual",
+    "allUnique",
+    "escapePointer",
+    "everyItem",
+    "selectBranchErrors",
+    "coerceScalar",
+    "coerceUnion",
+    "applyRepairs"
+  ].filter((name) => body.includes(`${name}(`));
+  if (body.includes("MAX_REPAIR_PASSES"))
+    runtimeHelpers.push("MAX_REPAIR_PASSES");
+  if (runtimeHelpers.length > 0) {
+    result += `import { ${runtimeHelpers.join(", ")} } from './validation-result.${importExt}'
+`;
+  }
+  const formatChecks = [...formats].map(formatCheckName).filter((name) => body.includes(`${name}(`)).sort();
+  if (formatChecks.length > 0) {
+    result += `import { ${formatChecks.join(", ")} } from './formats.${importExt}'
+`;
+  }
+  for (const imp of refImports) {
+    result += imp + "\n";
+  }
+  if (refImports.length > 0) {
+    result += "\n";
+  } else {
+    result += "\n";
+  }
+  result += typeDefinition + "\n\n" + validatorFunction + "\n\n" + booleanGuard;
+  for (const part of appended)
+    result += "\n\n" + part;
+  return result;
+};
+export {
+  generateValidatorFile
+};

package/dist/validators/generators/generate-repair-function.d.ts

@@ -0,0 +1,27 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * The name of the position-lookup half generated for a `$ref`'s target. A repair
+ * has to cross a file boundary the same way validation and coercion do.
+ */
+export declare const repairLookupNameFor: (ref: string, typeSuffix: string) => string;
+/**
+ * Generates the repairing half of a validator file: the position lookup, and the
+ * `repairX` that drives validate-repair-revalidate over it.
+ *
+ * The loop is the whole design. Coercion runs first, so anything that was only
+ * written in the wrong type is already right and never counts as a repair. What
+ * is left is judged by the very same `validateX` the package already emits, and
+ * *its errors* are what drive the repair: each one names a position and a
+ * reason, the lookup answers with a value for that position, and the error the
+ * repair came from is what gets reported. Nothing second-guesses the validator,
+ * and there is no parallel set of rules about what is wrong that could disagree
+ * with it.
+ *
+ * Re-validating after a round is what catches the cases one pass cannot see: a
+ * required object that was missing entirely is repaired into existence, and only
+ * then can its own children be judged. A position is repaired at most once, so
+ * the loop terminates on progress rather than on the pass cap.
+ */
+export declare const generateRepairFunction: (schema: JSONSchema, typeName: string, typeSuffix?: string) => {
+    code: string;
+};

package/dist/validators/generators/generate-repair-function.js

@@ -0,0 +1,102 @@
+import { getDefaultValue } from "@amritk/helpers/get-default-value";
+import { readKey } from "@amritk/helpers/read-key";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+const repairLookupNameFor = (ref, typeSuffix) => `repair${refToName(ref, typeSuffix)}At`;
+const fallbackLiteral = (schema) => {
+  const literal = getDefaultValue(schema);
+  return literal === "undefined" ? null : literal;
+};
+const schemaMap = (schema, key) => {
+  const value = readKey(schema, key);
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+};
+const emitWalker = (schema, ctx) => {
+  if (!isSchemaObject(schema))
+    return null;
+  const node = schema;
+  const ref = readKey(node, "$ref");
+  if (typeof ref === "string")
+    return repairLookupNameFor(ref, ctx.typeSuffix);
+  const own = fallbackLiteral(schema);
+  const properties = schemaMap(node, "properties") ?? {};
+  const children = Object.entries(properties).map(([key, child]) => [key, emitWalker(child, ctx)]).filter((entry) => entry[1] !== null);
+  const prefixItems = readKey(node, "prefixItems");
+  const tuple = Array.isArray(prefixItems) ? prefixItems : [];
+  const tupleWalkers = tuple.map((item) => emitWalker(item, ctx));
+  const items = readKey(node, "items");
+  const itemsWalker = typeof items === "object" && items !== null && !Array.isArray(items) ? emitWalker(items, ctx) : null;
+  const hasChildren = children.length > 0 || itemsWalker !== null || tupleWalkers.some((walker) => walker !== null);
+  if (own === null && !hasChildren)
+    return null;
+  const id = ctx.next();
+  const name = `_repairAt${id}`;
+  const lines = [
+    `const ${name}: RepairLookup = (segments) => {`,
+    `  if (segments.length === 0) return ${own === null ? "null" : `() => (${own})`}`
+  ];
+  if (hasChildren) {
+    lines.push(`  const [head, ...rest] = segments as [string, ...string[]]`);
+    if (children.length > 0) {
+      lines.push(`  switch (head) {`);
+      for (const [key, walker] of children)
+        lines.push(`    case ${JSON.stringify(key)}: return ${walker}(rest)`);
+      lines.push(`  }`);
+    }
+    const indexed = tupleWalkers.some((walker) => walker !== null) || itemsWalker !== null;
+    if (indexed) {
+      lines.push(`  const index = Number(head)`);
+      lines.push(`  if (Number.isInteger(index) && index >= 0) {`);
+      tupleWalkers.forEach((walker, position) => {
+        if (walker === null)
+          return;
+        lines.push(`    if (index === ${position}) return ${walker}(rest)`);
+      });
+      if (itemsWalker !== null) {
+        lines.push(`    if (index >= ${tuple.length}) return ${itemsWalker}(rest)`);
+      }
+      lines.push(`  }`);
+    }
+  }
+  lines.push(`  return null`, `}`);
+  ctx.helpers.push(lines.join("\n"));
+  return name;
+};
+const generateRepairFunction = (schema, typeName, typeSuffix = "") => {
+  const helpers = [];
+  let counter = 0;
+  const ctx = { typeSuffix, helpers, next: () => counter++ };
+  const walker = emitWalker(schema, ctx);
+  const lookupName = `repair${typeName}At`;
+  const parts = [
+    ...helpers.length > 0 ? [helpers.join("\n\n"), ""] : [],
+    `export const ${lookupName}: RepairLookup = ${walker === null ? "() => null" : walker}`,
+    "",
+    `export const repair${typeName} = (input: unknown, _path = ''): RepairResult<${typeName}> => {`,
+    `  let value = coerce${typeName}Value(input)`,
+    `  const repairs: ValidationError[] = []`,
+    `  const done = new Set<string>()`,
+    ``,
+    `  for (let pass = 0; pass < MAX_REPAIR_PASSES; pass++) {`,
+    `    const result = validate${typeName}(value, _path)`,
+    `    if (result === true) return { valid: true, value: value as ${typeName}, repairs }`,
+    ``,
+    `    const applied = applyRepairs(value, result.errors, ${lookupName}, done)`,
+    `    // Nothing moved, so nothing on a further pass would either.`,
+    `    if (applied.repaired.length === 0) return { valid: false, value, errors: result.errors, repairs }`,
+    `    value = applied.value`,
+    `    repairs.push(...applied.repaired)`,
+    `  }`,
+    ``,
+    `  const final = validate${typeName}(value, _path)`,
+    `  return final === true`,
+    `    ? { valid: true, value: value as ${typeName}, repairs }`,
+    `    : { valid: false, value, errors: final.errors, repairs }`,
+    `}`
+  ];
+  return { code: parts.join("\n") };
+};
+export {
+  generateRepairFunction,
+  repairLookupNameFor
+};