@amritk/validation 0.5.0 → 0.6.0

package/AI.md

@@ -107,4 +107,15 @@ any of them without one of those two flags.
    barrel — a leading `_` marks a name for sibling files only). Strict and
    `stripUnknown` parsers are unchanged.
 
+11. **`repairX(input, options?)` takes options, and is one pass when it can be.**
+   `inPlace`, `coerce: false` and `path` work for every schema; `refs`,
+   `skipRefs`, `onRef`, `maxDepth`, `maxWork`, `memo`, `finite` and
+   `plainObjects` only for a schema the single-pass walk covers (the
+   `if`/`then`/`else` + `allOf` + `properties` family; see the README) — on any
+   other schema `repairX` throws if they are set. Do not
+   promise a user instance `$ref` following without `"x-repair": "ref"` on their
+   Reference schema — generation refuses that opt-in on a schema the walk cannot
+   serve rather than ignoring it. `"x-repair": "drop"` and `false` schemas remove
+   a failing position rather than defaulting it.
+
 Only the `.` entry. Install: `bun add @amritk/validation`.

package/README.md

@@ -103,6 +103,51 @@ not enough: a document nothing could repair comes back with none either, and
 `valid: false`. To reject a bad config, use `coerceX`. To hand back a fixed one,
 use `repairX`.
 
+**Repairing large documents.** `repairX(input, options?)` takes an options
+object (a bare string is still read as the base path):
+
+| option | default | what it does |
+| --- | --- | --- |
+| `path` | `''` | JSON Pointer every reported path is rooted at |
+| `inPlace` | `false` | assign and delete on the input instead of copying the containers a repair touches |
+| `coerce` | `true` | move a scalar written in the wrong type (`"5"` under `integer`) before repairing; off, it is repaired to the schema's value and reported |
+| `refs` | `true` | follow instance `$ref`s at positions whose Reference schema opts in (below) |
+| `skipRefs` | `[]` | pointer prefixes (`'#/components/'`) whose targets the root schema already walks; still resolved, not walked again |
+| `onRef` | — | `(value, path, typeId) => boolean \| void`, called for every opted-in `$ref`; `false` leaves it alone |
+| `maxDepth` | `512` | depth past which a position is reported (`maxDepth`) instead of walked |
+| `maxWork` | `10_000_000` | containers visited before the walk stops (`maxWork`) |
+| `memo` | `false` | walk each object once per schema — for in-memory graphs with shared or cyclic subtrees |
+| `finite` | `false` | reject `NaN` and the infinities where a number is declared |
+| `plainObjects` | `false` | accept only plain objects, and remove an own `__proto__` key |
+
+When every definition in the schema is built from `type`, `enum`, `const`,
+`properties`, `required`, `additionalProperties`, `patternProperties`, `items`,
+`$ref`, `if`/`then`/`else` and `allOf` — plus annotations, and scalar
+assertions such as `minLength`, `pattern`, `minimum`, `anyOf`, `oneOf` or `not`,
+which are asked of the validator's own test of the position — `repairX` is a
+single pass: each position is checked and repaired where it stands, an `if` is
+evaluated against the value actually there, a missing required object is built
+with its required children (to a bounded depth on a recursive definition), and
+errors go straight into one array with their paths built only when something is
+reported. A valid document comes back as itself with nothing copied. On a 24 MB
+bundled OpenAPI document that is well under a hundred milliseconds (`bun
+--conditions development scripts/bench-repair-walk.ts`). Any other keyword keeps
+the validate-and-repair loop, which honours `path`, `inPlace` and `coerce` and
+throws on the walk-only options (`skipRefs`, `onRef`, `maxDepth`, `maxWork`,
+`memo`, `finite`, `plainObjects`) rather than quietly dropping a guard.
+
+Two schema annotations steer it. `"x-repair": "drop"` — and a `false` schema —
+removes a failing position instead of writing a default: an unknown key under
+`additionalProperties: false`, an array element under `items: false`, a
+drop-marked property. `"x-repair": "ref"` on a Reference schema turns on
+instance `$ref` following: at a position written
+`{ if: { type: object, required: [$ref] }, then: Reference, else: T }`, the
+`$ref` is resolved as a JSON Pointer against the root document (own properties
+only), and its target is checked and repaired as that position's type, with
+errors at the target's own path. Each target is walked once per type, chains
+and cycles included; one that does not resolve is reported as `unresolvedRef`
+and never created.
+
 **`parseX` agrees with `coerceX`.** Wherever `coerceX` accepts a document, the
 coercing `parseX` returns the very same value — through a union, an `allOf`, an
 `if`, a `$ref`, recursion included — and it only repairs what `coerceX` would
@@ -182,9 +227,11 @@ both leave the caller's document alone (`bun run bench:validators:coerce`, or
 
 <sub>Each cell is how many times faster `coerceX` is than Ajv on the same input,
 each engine timed in its own process (Bun 1.3.11, Node 22.22, Linux x64). A
-valid document is the common case and the widest gap: where `isX` is a
-standalone guard, `coerceX` answers it with that guard and hands the input
-straight back, without walking it. On valid input Ajv rewrites nothing, so it can
+valid document is the common case and the widest gap: `coerceX` answers it with
+`isX` and hands the input straight back, without walking it. `isX` builds
+nothing — no error, no path — and stops at the first failure, answering a
+`$ref` with the target's own `isX`; it calls `validateX` only for a schema that
+folds to a constant. On valid input Ajv rewrites nothing, so it can
 also be timed without the clone; `coerceX` is still ahead there on these
 schemas, by 1.2–3.3×, but not on every one: on a large, union-heavy document
 that the caller lets Ajv coerce in place, Ajv can come out modestly ahead. The

package/dist/validators/generators/build-schema.d.ts

@@ -12,7 +12,7 @@ export type GeneratedFile = {
  * types plus the helpers emitted code calls as free identifiers. Exported so tests
  * can evaluate the very source that ships instead of reimplementing it.
  */
-export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation error: what went wrong, where, and which keyword said so.\n *\n * The shape matches `@amritk/runtime-validators`, so an error from a generated\n * validator and one from the runtime interpreter can be handled by the same\n * code \u2014 grouped, translated, or branched on \u2014 without knowing which produced it.\n */\nexport type ValidationError = {\n  /** Human-readable description of what went wrong. */\n  message: string\n  /** JSON Pointer to the offending value inside the instance. */\n  path: string\n  /** The JSON Schema keyword that rejected the value \u2014 `type`, `required`, `minimum`, \u2026 */\n  keyword: string\n  /**\n   * The keyword's own values, as far as they explain the failure: the bound that\n   * was exceeded, the property that was missing, the allowed values that were not\n   * matched. Empty for a keyword with nothing to add beyond its name.\n   */\n  params: Record<string, unknown>\n}\n\n/**\n * The result of a generated validator function.\n * Returns `true` when the input is valid, or an object with `valid: false`\n * and a list of errors when it is not.\n */\nexport type ValidationResult = true | { valid: false; errors: ValidationError[] }\n\n/**\n * The result of a generated coercing validator.\n *\n * Unlike `ValidationResult` there is no bare `true`: a caller that coerces wants\n * the value back, and the whole point is that it may differ from what went in.\n * The input is never modified \u2014 `value` is the input itself when nothing needed\n * coercing, and otherwise a copy that shares everything the coercion did not\n * touch. So a caller does not have to clone defensively the way an in-place\n * coercer forces them to.\n */\nexport type CoercionResult<T> = { valid: true; value: T } | { valid: false; errors: ValidationError[] }\n\n/**\n * A string this will read as a number: an optional sign, digits with an optional\n * fractional part, an optional exponent. Nothing else.\n *\n * Deliberately narrower than what `Number()` accepts, which is where Ajv gets\n * its surprises \u2014 `Number(\" \")` is `0`, `Number(\"0x10\")` is `16` and\n * `Number(\"Infinity\")` is a value JSON cannot even represent. A config that says\n * `retries: \" \"` has a mistake in it, and answering `0` is the one thing worse\n * than rejecting it. Leading zeros (`\"007\"`) and exponents (`\"1e3\"`) stay: both\n * are ordinary ways to write a number in a YAML file, and neither is ambiguous.\n */\nconst isNumericString = (text: string): boolean => {\n  // `/^[+-]?(?:\\d+|\\d*\\.\\d+)(?:[eE][+-]?\\d+)?$/`, walked by hand. The regex\n  // cost more than the rest of a number coercion put together \u2014 a string past\n  // its end reads `NaN` from `charCodeAt`, which fails every test below, so\n  // the scan needs no bounds checks of its own.\n  let i = 0\n  let c = text.charCodeAt(0)\n  if (c === 43 || c === 45) c = text.charCodeAt(++i)\n  let digits = 0\n  while (c >= 48 && c <= 57) {\n    digits++\n    c = text.charCodeAt(++i)\n  }\n  if (c === 46) {\n    c = text.charCodeAt(++i)\n    let fraction = 0\n    while (c >= 48 && c <= 57) {\n      fraction++\n      c = text.charCodeAt(++i)\n    }\n    if (fraction === 0) return false\n  } else if (digits === 0) return false\n  if (c === 101 || c === 69) {\n    c = text.charCodeAt(++i)\n    if (c === 43 || c === 45) c = text.charCodeAt(++i)\n    let exponent = 0\n    while (c >= 48 && c <= 57) {\n      exponent++\n      c = text.charCodeAt(++i)\n    }\n    if (exponent === 0) return false\n  }\n  return i === text.length\n}\n\n/**\n * One scalar, coerced toward `type`, or returned untouched when that is not\n * possible.\n *\n * Returning the original on failure is what keeps the error honest: nothing is\n * substituted, so the validator that runs next rejects the value the caller\n * actually wrote, with the keyword and params that rejected it. That is the\n * difference between this and a parser's repair, which repairs toward a default\n * and leaves nothing to report.\n *\n * The table is Ajv's `coerceTypes` minus the cells where Ajv guesses. Every\n * value this coerces, Ajv coerces to the same value \u2014 `coerced-vs-ajv` pins that\n * as a property, so moving off Ajv never changes a value, it only turns some of\n * Ajv's silent repairs into errors. What is deliberately *not* coerced:\n *\n *  - **Anything to or from `null`.** Ajv reads `null` as `\"\"`, `0` and\n *    `false`, and reads `\"\"`, `0` and `false` back as `null`. `null` is a\n *    JSON value in its own right and usually means \"not set\"; turning it into an\n *    empty string, or an empty string into it, loses the distinction the document\n *    drew.\n *  - **Strings that are not cleanly numeric** ({@link isNumericString}) \u2014 no\n *    whitespace padding, no `0x`/`0o`/`0b`, no `Infinity`, no trailing `.`.\n */\nexport const coerceScalar = (value: unknown, type: string): unknown => {\n  switch (type) {\n    case 'string':\n      return typeof value === 'number' || typeof value === 'boolean' ? String(value) : value\n    case 'number':\n    case 'integer': {\n      if (typeof value === 'boolean') return value ? 1 : 0\n      if (typeof value !== 'string' || !isNumericString(value)) return value\n      const asNumber = Number(value)\n      if (!Number.isFinite(asNumber)) return value\n      return type === 'integer' && asNumber % 1 !== 0 ? value : asNumber\n    }\n    case 'boolean':\n      if (value === 'true' || value === 1) return true\n      if (value === 'false' || value === 0) return false\n      return value\n    default:\n      return value\n  }\n}\n\n/**\n * One scalar at a position that offers several types \u2014 a `type` array, or a\n * union of scalar branches \u2014 coerced only when every type that can take it\n * agrees on the result.\n *\n * A value whose type is already one of the offered types is left alone: it is\n * what the schema asked for, and the question of coercion does not arise. That\n * one rule is where this parts company with Ajv, which walks its own coercion\n * list in order and so turns `\"1\"` into `1` under `[\"number\", \"string\"]` while\n * leaving it a string under `[\"string\", \"number\"]`. The answer should not depend\n * on the order someone wrote the union in.\n *\n * Otherwise every offered type is tried, and the coercion is taken only if the\n * types that succeed all agree on it. `true` against `number | string` could be\n * `1` or `\"true\"` with equal justification, so it stays `true` and the\n * validator says what is wrong with it. `\"1\"` against `number | integer` is `1`\n * either way, so it is `1`.\n */\nexport const coerceUnion = (value: unknown, types: readonly string[]): unknown => {\n  const actual = value === null ? 'null' : typeof value\n  for (const type of types) {\n    // `integer` is satisfied by a number, so a non-integral number is not a\n    // *type* mismatch here \u2014 the validator is what holds it to being whole.\n    if (actual === type || (actual === 'number' && type === 'integer')) return value\n  }\n\n  let coerced: unknown = value\n  for (const type of types) {\n    const candidate = coerceScalar(value, type)\n    if (candidate === value) continue\n    if (coerced === value) coerced = candidate\n    else if (candidate !== coerced) return value\n  }\n  return coerced\n}\n\n/**\n * How deep a structural comparison walks before it gives up and answers \"not\n * equal\".\n *\n * JSON data is acyclic, but a generated validator is a plain function applied to\n * whatever in-memory value a caller hands it \u2014 and a self-referential object\n * reaching a `const` / `enum` / `uniqueItems` check used to recurse until the\n * stack overflowed, so `validateFoo` threw a `RangeError` instead of returning\n * the `ValidationResult` its signature promises. The cap turns that into an\n * ordinary \"these are different\" without ever coming near real data;\n * `@amritk/runtime-validators` guards its own `deepEqual` at the same depth.\n */\nconst MAX_EQUAL_DEPTH = 512\n\n/**\n * Structural deep equality used by generated `const` checks. Objects compare by\n * their key sets rather than serialization, so `{ a: 1, b: 2 }` and\n * `{ b: 2, a: 1 }` are equal \u2014 unlike `JSON.stringify`, which is key-order\n * sensitive and would reject a reordered-but-equal value.\n */\nexport const valuesEqual = (a: unknown, b: unknown, depth = 0): boolean => {\n  // SameValueZero: `===` settles every primitive except `NaN`, which counts as\n  // equal to itself here. That is what the native `Set` in {@link allUnique} does,\n  // what Ajv does, and what the interpreter's `deepEqual` does \u2014 leaving it out\n  // made a `NaN` nested inside an object compare unequal to itself, so the same\n  // array was \"unique\" here and \"duplicated\" everywhere else.\n  if (a === b || (Number.isNaN(a) && Number.isNaN(b))) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) return false\n  if (depth >= MAX_EQUAL_DEPTH) return false\n  const aArray = Array.isArray(a)\n  const bArray = Array.isArray(b)\n  if (aArray !== bArray) return false\n  if (aArray) {\n    const aa = a as unknown[]\n    const bb = b as unknown[]\n    if (aa.length !== bb.length) return false\n    for (let i = 0; i < aa.length; i++) if (!valuesEqual(aa[i], bb[i], depth + 1)) return false\n    return true\n  }\n  const ao = a as Record<string, unknown>\n  const bo = b as Record<string, unknown>\n  const keys = Object.keys(ao)\n  if (keys.length !== Object.keys(bo).length) return false\n  for (const key of keys) {\n    if (!Object.hasOwn(bo, key) || !valuesEqual(ao[key], bo[key], depth + 1)) return false\n  }\n  return true\n}\n\n/**\n * A cheap, order-independent structural hash consistent with {@link valuesEqual}:\n * equal values always hash the same. It buckets candidate-equal elements in\n * {@link allUnique} so the exact comparison only ever runs inside a bucket.\n *\n * Object keys are folded commutatively (XOR) so key order does not change the\n * hash, and `NaN` / `-0` collapse the way SameValueZero does. Depth-capped like\n * {@link valuesEqual}: an over-deep value simply shares a bucket and is settled by\n * the (also capped) comparison, so the cap can cost a little time and never a\n * wrong answer. This is the same hash `@amritk/runtime-validators` uses.\n */\nconst structuralHash = (value: unknown, depth = 0): number => {\n  if (value === null) return 0x1a2b3c\n  const t = typeof value\n  if (t === 'number') {\n    const n = value as number\n    return Number.isNaN(n) ? 0x7ff8 : n === 0 ? 0 : Math.trunc(n * 2654435761) | 0\n  }\n  if (t === 'string') {\n    const s = value as string\n    let h = 0x811c9dc5\n    for (let i = 0; i < s.length; i++) h = Math.imul(h ^ s.charCodeAt(i), 0x01000193)\n    return h | 0\n  }\n  if (t === 'boolean') return value ? 1 : 2\n  if (t !== 'object') return 0x5eed\n  if (depth >= MAX_EQUAL_DEPTH) return 0xdee9\n  if (Array.isArray(value)) {\n    let h = 0x12345 ^ value.length\n    for (let i = 0; i < value.length; i++) h = (Math.imul(h, 31) + structuralHash(value[i], depth + 1)) | 0\n    return h | 0\n  }\n  const obj = value as Record<string, unknown>\n  const keys = Object.keys(obj)\n  let h = 0xabcde ^ keys.length\n  for (const k of keys) {\n    let kh = 0x811c9dc5\n    for (let i = 0; i < k.length; i++) kh = Math.imul(kh ^ k.charCodeAt(i), 0x01000193)\n    h = (h ^ (Math.imul(kh, 0x9e3779b1) + structuralHash(obj[k], depth + 1))) | 0\n  }\n  return h | 0\n}\n\n/**\n * True when every element of `arr` is distinct under structural equality\n * ({@link valuesEqual}). Backs generated `uniqueItems` checks whose items may be\n * objects or arrays, where a `JSON.stringify` dedupe key would be key-order\n * sensitive and let a reordered-but-equal duplicate (`{ a: 1, b: 2 }` vs\n * `{ b: 2, a: 1 }`) slip through.\n *\n * A native `Set` dedupes the all-primitive case in one linear pass. Object and\n * array elements are bucketed by {@link structuralHash} first, so the exact\n * comparison runs only against elements that could actually be equal: an array of\n * distinct objects costs ~O(n) instead of the O(n\u00B2) an exhaustive pairwise sweep\n * charged \u2014 4 000 rows took over half a second of pure comparison before, which\n * is a lot to hand an unauthenticated caller.\n */\nexport const allUnique = (arr: readonly unknown[]): boolean => {\n  const len = arr.length\n  if (len < 2) return true\n  let allPrimitive = true\n  for (let i = 0; i < len; i++) {\n    const v = arr[i]\n    if (v !== null && typeof v === 'object') {\n      allPrimitive = false\n      break\n    }\n  }\n  if (allPrimitive) return new Set(arr).size === len\n  const buckets = new Map<number, unknown[]>()\n  for (let i = 0; i < len; i++) {\n    const item = arr[i]\n    const hash = structuralHash(item)\n    const bucket = buckets.get(hash)\n    if (bucket === undefined) {\n      buckets.set(hash, [item])\n      continue\n    }\n    for (const seen of bucket) if (valuesEqual(seen, item)) return false\n    bucket.push(item)\n  }\n  return true\n}\n\n/**\n * True when `test` holds for every element of `arr`, holes included. Backs the\n * item check inside a generated boolean guard.\n *\n * Not `Array.prototype.every`, because that *skips holes* in a sparse array\n * (`[, 'x']`), whereas the validator's index-based loop reads a hole as\n * `undefined` and rejects it \u2014 and the guard must never accept what the validator\n * rejects. The guard used to get that by materialising `Array.from(arr)` first,\n * which copied every array it looked at; an index loop reads a hole the same way\n * and copies nothing.\n */\nexport const everyItem = (arr: readonly unknown[], test: (item: unknown) => boolean): boolean => {\n  for (let i = 0; i < arr.length; i++) if (!test(arr[i])) return false\n  return true\n}\n\n/**\n * Escapes one JSON Pointer segment (RFC 6901): `~` \u2192 `~0`, `/` \u2192 `~1`, in that\n * order. Generated error paths are built from *runtime* keys wherever the schema\n * did not name them \u2014 a `patternProperties` match, an `additionalProperties`\n * sweep, a `propertyNames` loop \u2014 and a key containing a `/` would otherwise read\n * back as two segments, so an error on `{\"a/b\": \u2026}` pointed at `/a/b`, which is\n * the child `b` of a property `a`. Keys the schema *does* name are escaped at\n * generation time instead, and `@amritk/runtime-validators` escapes the same way,\n * so all three agree.\n *\n * The `indexOf` pre-test keeps the common key \u2014 no `/`, no `~` \u2014 off the replace\n * path entirely, which is what the interpreter does for the same reason.\n */\nexport const escapePointer = (key: string): string =>\n  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key\n\n/**\n * The errors of the branch that was plainly the one meant, out of every branch a\n * failing `anyOf` / `oneOf` rejected. Empty when no branch stands out.\n *\n * A failing combinator on its own says almost nothing: \"must match a schema in\n * anyOf\" names no field and no reason, and on the shape this is most often used\n * for \u2014 a union where the value plainly *is* one of the variants and one field of\n * it is wrong \u2014 that is the least useful thing a validator can say. The branch\n * errors are computed anyway to answer the yes/no question, so the only question\n * is which of them are worth reporting.\n *\n * Branches that rejected the value's *kind* go first: a branch wanting a string\n * has nothing to say about an object, so a `string | { \u2026 }` union is left with\n * the one branch that was even talking about this value. When more than one\n * survives they all describe the same kind of value, and the tie is broken the\n * way a discriminated union reads from the outside \u2014 if every survivor but one\n * was rejected on the value's *identity* (a `const` or `enum` on the value or\n * one of its own properties), the remaining one is the variant the author meant.\n *\n * When every branch rejected the value's kind, no branch was meant, but the\n * kinds they wanted together are what the union accepts, so that is reported as\n * one `type` error: \"must be object or boolean\" for a `true` written as the\n * string `'true'`. `total` is how many branches the combinator has, and the kinds\n * are only named when all of them were heard from. A branch that could not\n * explain itself might have accepted this kind, and then the list would be wrong.\n *\n * Otherwise nothing is reported when no branch stands out, which is as much as\n * can be said honestly: \"the branch with the fewest errors\" would answer here\n * too, and answers wrongly on `oneOf: [aReference, theActualThing]`, where \"you\n * did not write a $ref\" is one complaint and the real mistake is two.\n *\n * `path` is where the combinator was applied, so a segment below it is a direct\n * property of the value being judged. `@amritk/runtime-validators` selects the\n * same branch by the same rule, so a generated validator and the interpreter\n * explain a failing union the same way.\n */\nexport const selectBranchErrors = (\n  branches: readonly (readonly ValidationError[])[],\n  path: string,\n  total?: number,\n): readonly ValidationError[] => {\n  const candidates: (readonly ValidationError[])[] = []\n  for (const errors of branches) {\n    // The value itself is `path`, so a `type` error there is a rejected kind.\n    if (!errors.some((error) => error.keyword === 'type' && error.path === path)) candidates.push(errors)\n  }\n  if (candidates.length === 1) return candidates[0] as readonly ValidationError[]\n  if (candidates.length === 0) return branches.length === total ? acceptedKinds(branches, path) : []\n\n  let selected: readonly ValidationError[] | null = null\n  let rejectedOnIdentity = 0\n  for (const errors of candidates) {\n    // One segment below `path` and no deeper: a discriminator is conventionally a\n    // direct field, and a `const` buried further down is far more likely to be an\n    // ordinary payload constraint.\n    const identity = errors.some(\n      (error) =>\n        (error.keyword === 'const' || error.keyword === 'enum') && error.path.indexOf('/', path.length + 1) === -1,\n    )\n    if (identity) {\n      rejectedOnIdentity++\n      continue\n    }\n    // Two branches survive the discriminator, so it did not discriminate.\n    if (selected !== null) return []\n    selected = errors\n  }\n\n  return selected !== null && rejectedOnIdentity === candidates.length - 1 ? selected : []\n}\n\n/**\n * One `type` error naming every kind the branches asked for, in branch order and\n * once each. A branch's own `type` may be a list, and a nested union reports its\n * kinds as a list too, so both are read flat.\n */\nconst acceptedKinds = (\n  branches: readonly (readonly ValidationError[])[],\n  path: string,\n): readonly ValidationError[] => {\n  const kinds: string[] = []\n  for (const errors of branches) {\n    for (const error of errors) {\n      if (error.keyword !== 'type' || error.path !== path) continue\n      const type = error.params['type']\n      for (const kind of Array.isArray(type) ? type : [type]) {\n        if (typeof kind === 'string' && !kinds.includes(kind)) kinds.push(kind)\n      }\n    }\n  }\n  if (kinds.length === 0) return []\n  return [\n    {\n      message: 'must be ' + kinds.join(' or '),\n      path,\n      keyword: 'type',\n      params: { type: kinds.length === 1 ? kinds[0] : kinds },\n    },\n  ]\n}\n\n/**\n * The result of a generated repairing validator.\n *\n * `repairs` is not a second, parallel account of what went wrong \u2014 it *is* the\n * errors `validateX` produced, the ones a repair was found for. So a caller that\n * logs a repair logs the same path, keyword and params it would have been\n * rejected with, and the two can never drift apart, because there is only one of\n * them.\n *\n * A document that needed no repair comes back `valid: true` with an empty\n * `repairs`, which is exactly what `coerceX` would have returned. One that was\n * fully repaired is `valid: true` with a non-empty `repairs` \u2014 the caller\n * decides whether that is acceptable by looking, rather than by being told. One\n * that could not be fully repaired is `valid: false` and carries both: the\n * repairs that were applied, and the `errors` still outstanding against the\n * value handed back.\n */\nexport type RepairResult<T> =\n  | { valid: true; value: T; repairs: ValidationError[] }\n  | { valid: false; value: unknown; errors: ValidationError[]; repairs: ValidationError[] }\n\n/**\n * Looks up the repaired value for one position, given that position's JSON\n * Pointer split into segments. Returns a thunk rather than a value so each\n * repair gets its own object \u2014 a shared literal would alias every site that\n * repaired to it \u2014 and `null` where the schema offers nothing to repair toward.\n */\nexport type RepairLookup = (segments: readonly string[]) => (() => unknown) | null\n\n/**\n * How many validate-and-repair rounds `repairX` will run. Repairing a child can\n * expose a parent that only became checkable once the child was there, so one\n * round is not always enough; but each round is bounded further by the rule that\n * a position is repaired at most once, so this is a backstop rather than the\n * thing doing the terminating.\n */\nexport const MAX_REPAIR_PASSES = 8\n\n/**\n * Splits a JSON Pointer into its segments, undoing the escaping\n * {@link escapePointer} applied. The root pointer (`''`) is zero segments.\n */\nexport const pointerSegments = (path: string): string[] =>\n  path === ''\n    ? []\n    : path\n        .slice(1)\n        .split('/')\n        .map((segment) =>\n          segment.indexOf('~') === -1 ? segment : segment.replace(/~1/g, '/').replace(/~0/g, '~'),\n        )\n\n/**\n * Returns `root` with the position at `segments` replaced by `value`, copying\n * only the containers along the way.\n *\n * Copying rather than writing is not politeness, it is the same promise\n * `coerceX` makes: the caller's input is never modified, so a repaired document\n * can be compared against what was actually sent. Everything the path did not\n * touch is shared, so repairing one field of a large document does not clone it.\n *\n * Returns `root` unchanged when the path does not lead anywhere \u2014 a segment into\n * a missing or non-container parent. That is not a failure to handle here: the\n * parent has an error of its own, and repairing *it* is what makes this position\n * reachable on a later pass.\n */\nexport const repairAt = (root: unknown, segments: readonly string[], value: unknown): unknown => {\n  if (segments.length === 0) return value\n  const [head, ...rest] = segments as [string, ...string[]]\n\n  if (Array.isArray(root)) {\n    const index = Number(head)\n    // `index === root.length` is an append, which is what padding a short array\n    // to its `minItems` is made of. Anything past that would leave a hole, and a\n    // hole is not a repair.\n    if (!Number.isInteger(index) || index < 0 || index > root.length) return root\n    const next = repairAt(root[index], rest, value)\n    if (next === root[index]) return root\n    const copy = [...root]\n    copy[index] = next\n    return copy\n  }\n\n  if (typeof root !== 'object' || root === null) return root\n  const obj = root as Record<string, unknown>\n  // A missing key is reachable only when this is the last segment: that is the\n  // `required` repair, which is putting the key there. Deeper than that and the\n  // parent is the thing that needs repairing first.\n  if (!Object.hasOwn(obj, head) && rest.length > 0) return root\n  const next = repairAt(obj[head], rest, value)\n  if (next === obj[head] && Object.hasOwn(obj, head)) return root\n  return { ...obj, [head]: next }\n}\n\n/**\n * The position one error is asking to have repaired, or `null` when the error is\n * not about a position a value can be put at.\n *\n * One keyword does not point at the value that is wrong: a `required` error is\n * reported against the *object* that is missing the key, and names the key in\n * `params.missingProperty`, so the position to fill is one segment deeper.\n * `minItems` is the other exception and is handled separately, because it is\n * satisfied by adding several values rather than by replacing one.\n */\nconst repairTarget = (error: ValidationError): readonly string[] | null => {\n  const segments = pointerSegments(error.path)\n  if (error.keyword === 'required') {\n    const missing = error.params['missingProperty']\n    return typeof missing === 'string' ? [...segments, missing] : null\n  }\n  return segments\n}\n\n/** The value at a pointer, or `undefined` when the path does not lead anywhere. */\nconst valueAt = (root: unknown, segments: readonly string[]): unknown =>\n  segments.reduce<unknown>(\n    (node, segment) =>\n      Array.isArray(node)\n        ? node[Number(segment)]\n        : typeof node === 'object' && node !== null\n          ? (node as Record<string, unknown>)[segment]\n          : undefined,\n    root,\n  )\n\n/**\n * Grows a short array to the length `minItems` asks for, or `null` when it\n * cannot.\n *\n * Padding is its own operation rather than a position repair because one\n * `minItems` error is satisfied by *several* values, not one. Doing it a single\n * element per round would work, but it would spend a round per element and a\n * `minItems: 50` would run out of them; filling the shortfall at once keeps the\n * number of rounds a question about the shape of the document rather than about\n * the size of its arrays.\n *\n * Every added element is a separate call to the thunk, so no two share an object.\n */\nconst padToMinItems = (\n  root: unknown,\n  error: ValidationError,\n  lookup: RepairLookup,\n  done: Set<string>,\n): unknown => {\n  const segments = pointerSegments(error.path)\n  const array = valueAt(root, segments)\n  const limit = error.params['limit']\n  if (!Array.isArray(array) || typeof limit !== 'number' || array.length >= limit) return null\n\n  // Keyed apart from a position repair at the same path: replacing the whole\n  // array and padding it are different repairs, and having done one is no reason\n  // to refuse the other.\n  const key = `${segments.join('/')}#minItems`\n  if (done.has(key)) return null\n\n  const element = lookup([...segments, String(array.length)])\n  if (element === null) return null\n\n  const padded = [...array]\n  while (padded.length < limit) padded.push(element())\n  const updated = repairAt(root, segments, padded)\n  if (updated === root) return null\n  done.add(key)\n  return updated\n}\n\n/**\n * Applies one round of repairs: every error the schema offers a value for is\n * repaired, and the rest are handed back untouched.\n *\n * `done` carries the positions already repaired on an earlier round. A position\n * that failed again after being repaired is not repaired a second time \u2014 the\n * value the schema offered did not satisfy the schema, which is a fact about the\n * schema, and trying again would only produce the same value. Refusing keeps the\n * loop finite without relying on the pass cap, and turns the position into an\n * honest error instead of a silent spin.\n */\nexport const applyRepairs = (\n  value: unknown,\n  errors: readonly ValidationError[],\n  lookup: RepairLookup,\n  done: Set<string>,\n): { value: unknown; repaired: ValidationError[] } => {\n  const repaired: ValidationError[] = []\n  let next = value\n\n  for (const error of errors) {\n    if (error.keyword === 'minItems') {\n      const padded = padToMinItems(next, error, lookup, done)\n      if (padded === null) continue\n      next = padded\n      repaired.push(error)\n      continue\n    }\n\n    const target = repairTarget(error)\n    if (target === null) continue\n    const key = target.join('/')\n    if (done.has(key)) continue\n    const to = lookup(target)\n    if (to === null) continue\n\n    const updated = repairAt(next, target, to())\n    // An unreachable position leaves the document exactly as it was. Not counting\n    // it as repaired is what lets the parent's own error be the thing that\n    // reports, rather than this silently claiming a fix that did not land.\n    if (updated === next) continue\n    done.add(key)\n    next = updated\n    repaired.push(error)\n  }\n\n  return { value: next, repaired }\n}\n";
+export declare const VALIDATION_RESULT_CONTENT: string;
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all
  * `$ref` / `$dynamicRef` references recursively (via the shared

package/dist/validators/generators/build-schema.js

@@ -3,6 +3,8 @@ import { DEFAULT_UNKNOWN_KEYS } from "@amritk/helpers/unknown-keys-strategy";
 import { walkRefGraph } from "@amritk/helpers/walk-ref-graph";
 import { emitFormatModule, FORMAT_FRAGMENTS, formatCheckName } from "./emit-format-checks.js";
 import { generateValidatorFile } from "./generate-files.js";
+import { REPAIR_RUNTIME_CONTENT } from "./repair-runtime.js";
+import { asksForRefs, repairWalkBlocker } from "./repair-walkable.js";
 const VALIDATION_RESULT_CONTENT = `/**
  * A single validation error: what went wrong, where, and which keyword said so.
  *
@@ -436,222 +438,10 @@ const acceptedKinds = (
   ]
 }
 
-/**
- * The result of a generated repairing validator.
- *
- * \`repairs\` is not a second, parallel account of what went wrong \u2014 it *is* the
- * errors \`validateX\` produced, the ones a repair was found for. So a caller that
- * logs a repair logs the same path, keyword and params it would have been
- * rejected with, and the two can never drift apart, because there is only one of
- * them.
- *
- * A document that needed no repair comes back \`valid: true\` with an empty
- * \`repairs\`, which is exactly what \`coerceX\` would have returned. One that was
- * fully repaired is \`valid: true\` with a non-empty \`repairs\` \u2014 the caller
- * decides whether that is acceptable by looking, rather than by being told. One
- * that could not be fully repaired is \`valid: false\` and carries both: the
- * repairs that were applied, and the \`errors\` still outstanding against the
- * value handed back.
- */
-export type RepairResult<T> =
-  | { valid: true; value: T; repairs: ValidationError[] }
-  | { valid: false; value: unknown; errors: ValidationError[]; repairs: ValidationError[] }
-
-/**
- * Looks up the repaired value for one position, given that position's JSON
- * Pointer split into segments. Returns a thunk rather than a value so each
- * repair gets its own object \u2014 a shared literal would alias every site that
- * repaired to it \u2014 and \`null\` where the schema offers nothing to repair toward.
- */
-export type RepairLookup = (segments: readonly string[]) => (() => unknown) | null
-
-/**
- * How many validate-and-repair rounds \`repairX\` will run. Repairing a child can
- * expose a parent that only became checkable once the child was there, so one
- * round is not always enough; but each round is bounded further by the rule that
- * a position is repaired at most once, so this is a backstop rather than the
- * thing doing the terminating.
- */
-export const MAX_REPAIR_PASSES = 8
-
-/**
- * Splits a JSON Pointer into its segments, undoing the escaping
- * {@link escapePointer} applied. The root pointer (\`''\`) is zero segments.
- */
-export const pointerSegments = (path: string): string[] =>
-  path === ''
-    ? []
-    : path
-        .slice(1)
-        .split('/')
-        .map((segment) =>
-          segment.indexOf('~') === -1 ? segment : segment.replace(/~1/g, '/').replace(/~0/g, '~'),
-        )
-
-/**
- * Returns \`root\` with the position at \`segments\` replaced by \`value\`, copying
- * only the containers along the way.
- *
- * Copying rather than writing is not politeness, it is the same promise
- * \`coerceX\` makes: the caller's input is never modified, so a repaired document
- * can be compared against what was actually sent. Everything the path did not
- * touch is shared, so repairing one field of a large document does not clone it.
- *
- * Returns \`root\` unchanged when the path does not lead anywhere \u2014 a segment into
- * a missing or non-container parent. That is not a failure to handle here: the
- * parent has an error of its own, and repairing *it* is what makes this position
- * reachable on a later pass.
- */
-export const repairAt = (root: unknown, segments: readonly string[], value: unknown): unknown => {
-  if (segments.length === 0) return value
-  const [head, ...rest] = segments as [string, ...string[]]
-
-  if (Array.isArray(root)) {
-    const index = Number(head)
-    // \`index === root.length\` is an append, which is what padding a short array
-    // to its \`minItems\` is made of. Anything past that would leave a hole, and a
-    // hole is not a repair.
-    if (!Number.isInteger(index) || index < 0 || index > root.length) return root
-    const next = repairAt(root[index], rest, value)
-    if (next === root[index]) return root
-    const copy = [...root]
-    copy[index] = next
-    return copy
-  }
-
-  if (typeof root !== 'object' || root === null) return root
-  const obj = root as Record<string, unknown>
-  // A missing key is reachable only when this is the last segment: that is the
-  // \`required\` repair, which is putting the key there. Deeper than that and the
-  // parent is the thing that needs repairing first.
-  if (!Object.hasOwn(obj, head) && rest.length > 0) return root
-  const next = repairAt(obj[head], rest, value)
-  if (next === obj[head] && Object.hasOwn(obj, head)) return root
-  return { ...obj, [head]: next }
-}
-
-/**
- * The position one error is asking to have repaired, or \`null\` when the error is
- * not about a position a value can be put at.
- *
- * One keyword does not point at the value that is wrong: a \`required\` error is
- * reported against the *object* that is missing the key, and names the key in
- * \`params.missingProperty\`, so the position to fill is one segment deeper.
- * \`minItems\` is the other exception and is handled separately, because it is
- * satisfied by adding several values rather than by replacing one.
- */
-const repairTarget = (error: ValidationError): readonly string[] | null => {
-  const segments = pointerSegments(error.path)
-  if (error.keyword === 'required') {
-    const missing = error.params['missingProperty']
-    return typeof missing === 'string' ? [...segments, missing] : null
-  }
-  return segments
-}
-
-/** The value at a pointer, or \`undefined\` when the path does not lead anywhere. */
-const valueAt = (root: unknown, segments: readonly string[]): unknown =>
-  segments.reduce<unknown>(
-    (node, segment) =>
-      Array.isArray(node)
-        ? node[Number(segment)]
-        : typeof node === 'object' && node !== null
-          ? (node as Record<string, unknown>)[segment]
-          : undefined,
-    root,
-  )
-
-/**
- * Grows a short array to the length \`minItems\` asks for, or \`null\` when it
- * cannot.
- *
- * Padding is its own operation rather than a position repair because one
- * \`minItems\` error is satisfied by *several* values, not one. Doing it a single
- * element per round would work, but it would spend a round per element and a
- * \`minItems: 50\` would run out of them; filling the shortfall at once keeps the
- * number of rounds a question about the shape of the document rather than about
- * the size of its arrays.
- *
- * Every added element is a separate call to the thunk, so no two share an object.
- */
-const padToMinItems = (
-  root: unknown,
-  error: ValidationError,
-  lookup: RepairLookup,
-  done: Set<string>,
-): unknown => {
-  const segments = pointerSegments(error.path)
-  const array = valueAt(root, segments)
-  const limit = error.params['limit']
-  if (!Array.isArray(array) || typeof limit !== 'number' || array.length >= limit) return null
-
-  // Keyed apart from a position repair at the same path: replacing the whole
-  // array and padding it are different repairs, and having done one is no reason
-  // to refuse the other.
-  const key = \`\${segments.join('/')}#minItems\`
-  if (done.has(key)) return null
-
-  const element = lookup([...segments, String(array.length)])
-  if (element === null) return null
-
-  const padded = [...array]
-  while (padded.length < limit) padded.push(element())
-  const updated = repairAt(root, segments, padded)
-  if (updated === root) return null
-  done.add(key)
-  return updated
-}
-
-/**
- * Applies one round of repairs: every error the schema offers a value for is
- * repaired, and the rest are handed back untouched.
- *
- * \`done\` carries the positions already repaired on an earlier round. A position
- * that failed again after being repaired is not repaired a second time \u2014 the
- * value the schema offered did not satisfy the schema, which is a fact about the
- * schema, and trying again would only produce the same value. Refusing keeps the
- * loop finite without relying on the pass cap, and turns the position into an
- * honest error instead of a silent spin.
- */
-export const applyRepairs = (
-  value: unknown,
-  errors: readonly ValidationError[],
-  lookup: RepairLookup,
-  done: Set<string>,
-): { value: unknown; repaired: ValidationError[] } => {
-  const repaired: ValidationError[] = []
-  let next = value
-
-  for (const error of errors) {
-    if (error.keyword === 'minItems') {
-      const padded = padToMinItems(next, error, lookup, done)
-      if (padded === null) continue
-      next = padded
-      repaired.push(error)
-      continue
-    }
-
-    const target = repairTarget(error)
-    if (target === null) continue
-    const key = target.join('/')
-    if (done.has(key)) continue
-    const to = lookup(target)
-    if (to === null) continue
-
-    const updated = repairAt(next, target, to())
-    // An unreachable position leaves the document exactly as it was. Not counting
-    // it as repaired is what lets the parent's own error be the thing that
-    // reports, rather than this silently claiming a fix that did not land.
-    if (updated === next) continue
-    done.add(key)
-    next = updated
-    repaired.push(error)
-  }
-
-  return { value: next, repaired }
-}
-`;
+` + REPAIR_RUNTIME_CONTENT;
 const RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set(["ValidationResult", "ValidationError"]);
+const COERCE_TYPE_NAMES = ["CoercionResult"];
+const REPAIR_TYPE_NAMES = ["RepairResult", "RepairLookup", "RepairOptions", "RepairThunk", "RepairWalk", "RepairRun"];
 const TYPE_NAME = /^[\p{ID_Start}_$][\p{ID_Continue}$]*$/u;
 const RESERVED_WORDS = /* @__PURE__ */ new Set([
   "await",
@@ -693,10 +483,34 @@ const RESERVED_WORDS = /* @__PURE__ */ new Set([
   "with",
   "yield"
 ]);
+const decideRepairWalk = (nodes) => {
+  for (const node of nodes) {
+    const blocker = repairWalkBlocker(node.schema, node.isRoot);
+    if (blocker === null)
+      continue;
+    const refs = nodes.find((candidate) => asksForRefs(candidate.schema));
+    if (refs !== void 0) {
+      const owner = node.isRoot ? "the root schema" : `"${node.ref}"`;
+      throw new Error(`"x-repair": "ref" needs the single-pass repair walk, which ${owner} cannot use: ${blocker} is a keyword the walk does not repair. Remove it, or drop the "x-repair": "ref" opt-in.`);
+    }
+    return false;
+  }
+  return true;
+};
 const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS, formats, coerce = false, branchErrors = false, repair = false, importExt = "js", check = false) => {
   const enforced = formats === "all" ? new Set(Object.keys(FORMAT_FRAGMENTS)) : new Set((formats ?? []).filter((name) => Object.hasOwn(FORMAT_FRAGMENTS, name)));
   const files = [];
+  const reserved = /* @__PURE__ */ new Set([
+    ...RESERVED_TYPE_NAMES,
+    ...coerce || repair ? COERCE_TYPE_NAMES : [],
+    ...repair ? REPAIR_TYPE_NAMES : []
+  ]);
+  const nodes = [];
   walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
+    nodes.push(node);
+  });
+  const repairWalk = repair && decideRepairWalk(nodes);
+  for (const node of nodes) {
     if (node.filename === "validation-result" || node.filename === "index") {
       const owner = node.isRoot ? `the root type "${node.typeName}"` : `"${node.ref}"`;
       const purpose = node.filename === "index" ? "the generated barrel" : "the generated validators' runtime contract";
@@ -707,7 +521,7 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
       const suffixNote = typeSuffix === "" ? "" : ` (with the type suffix "${typeSuffix}")`;
       throw new Error(`${owner}${suffixNote}, "${node.typeName}", is not a TypeScript type name, so the generated file would not parse. Pass a name that is a plain identifier \u2014 letters, digits, "_" and "$", not starting with a digit, and not a reserved word.`);
     }
-    if (RESERVED_TYPE_NAMES.has(node.typeName)) {
+    if (reserved.has(node.typeName)) {
       const owner = node.isRoot ? `the root type name "${node.typeName}"` : `"${node.ref}"`;
       throw new Error(`${owner} generates the type "${node.typeName}", which every generated file already imports from "validation-result.ts". Rename the definition (or pass a different root type name or type suffix) so the two names do not collide.`);
     }
@@ -720,11 +534,12 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
       coerce,
       branchErrors,
       repair,
+      repairWalk,
       importExt,
       ...node.ref !== void 0 ? { selfRef: node.ref } : {}
     });
     files.push({ filename: `${node.filename}.ts`, content });
-  });
+  }
   files.push({ filename: "validation-result.ts", content: VALIDATION_RESULT_CONTENT });
   const called = [...enforced].filter((format) => files.some((file) => file.content.includes(`${formatCheckName(format)}(`)));
   const formatModule = emitFormatModule(called);

package/dist/validators/generators/collect-validator-imports.d.ts

@@ -46,6 +46,7 @@ type CollectValidatorImportsOptions = {
         readonly checkerName: string;
         readonly coercerName: string;
         readonly repairerName: string;
+        readonly walkerName: string;
     }) => {
         readonly type: boolean;
         readonly validator: boolean;
@@ -76,6 +77,12 @@ type CollectValidatorImportsOptions = {
          * without {@link coercer}, though the reverse is ordinary.
          */
         readonly repairer?: boolean;
+        /**
+         * The `$ref` target's single-pass repair walk. Only emitted when the whole
+         * schema graph is one the walk covers, and then called wherever a walk
+         * reaches the ref.
+         */
+        readonly walker?: boolean;
     };
 };
 /**

package/dist/validators/generators/collect-validator-imports.js

@@ -10,20 +10,23 @@ const buildImport = (ref, suffix, reads, importExt) => {
   const checkerName = `check${typeName}`;
   const coercerName = `coerce${typeName}Value`;
   const repairerName = `repair${typeName}At`;
-  const { type, validator, guard = false, checker = false, coercer = false, repairer = false } = reads({
+  const walkerName = `walk${typeName}Repair`;
+  const { type, validator, guard = false, checker = false, coercer = false, repairer = false, walker = false } = reads({
     typeName,
     validatorName,
     guardName,
     checkerName,
     coercerName,
-    repairerName
+    repairerName,
+    walkerName
   });
   const values = [
     ...validator ? [validatorName] : [],
     ...guard ? [guardName] : [],
     ...checker ? [checkerName] : [],
     ...coercer ? [coercerName] : [],
-    ...repairer ? [repairerName] : []
+    ...repairer ? [repairerName] : [],
+    ...walker ? [walkerName] : []
   ];
   if (type && values.length > 0)
     return `import { type ${typeName}, ${values.join(", ")} } from './${filename}.${importExt}'`;

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

@@ -53,6 +53,12 @@ type GenerateValidatorFileOptions = {
      * validator ever sees it, and never shows up as a repair.
      */
     readonly repair?: boolean;
+    /**
+     * Whether the repairing half also gets the single-pass walk, which `repairX`
+     * then runs instead of the validate-and-repair loop. Decided over the whole
+     * schema graph by the caller, since one walk calls another across files.
+     */
+    readonly repairWalk?: boolean;
     /** Extension on every emitted relative specifier: `'js'` (default) or `'ts'`. */
     readonly importExt?: 'js' | 'ts';
     /**

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

@@ -17,7 +17,7 @@ const generateValidatorFile = (schema, typeName, options) => {
   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 { code: booleanGuard, standalone: standaloneGuard } = generateBooleanGuardSource(schema, typeName, unknownKeys, formats);
+  const { code: booleanGuard, standalone: standaloneGuard } = generateBooleanGuardSource(schema, typeName, unknownKeys, formats, { suffix: typeSuffix, ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {} });
   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, {
@@ -27,7 +27,8 @@ const generateValidatorFile = (schema, typeName, options) => {
   }).code : "";
   const repairer = options?.repair === true ? generateRepairFunction(schema, typeName, typeSuffix, {
     ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {},
-    formats
+    formats,
+    walk: options.repairWalk === true
   }).code : "";
   const appended = [checker, coercer, repairer].filter((part) => part !== "");
   const body = validatorFunction + booleanGuard + (appended.length === 0 ? "" : "\n\n" + appended.join("\n\n"));
@@ -37,13 +38,14 @@ const generateValidatorFile = (schema, typeName, options) => {
     rootSchema: options?.rootSchema,
     typeSuffix,
     importExt,
-    reads: ({ typeName: name, validatorName, guardName, checkerName, coercerName, repairerName }) => ({
+    reads: ({ typeName: name, validatorName, guardName, checkerName, coercerName, repairerName, walkerName }) => ({
       type: mentions(name),
       validator: mentions(validatorName),
       guard: mentions(guardName),
       checker: mentions(checkerName),
       coercer: mentions(coercerName),
-      repairer: mentions(repairerName)
+      repairer: mentions(repairerName),
+      walker: mentions(walkerName)
     })
   });
   const resultTypes = [
@@ -51,7 +53,7 @@ const generateValidatorFile = (schema, typeName, options) => {
     .../\bValidationError\b/.test(body) ? ["ValidationError"] : [],
     .../\bCoercionResult\b/.test(body) ? ["CoercionResult"] : [],
     .../\bRepairResult\b/.test(body) ? ["RepairResult"] : [],
-    .../\bRepairLookup\b/.test(body) ? ["RepairLookup"] : []
+    ...["RepairLookup", "RepairOptions", "RepairThunk", "RepairWalk", "RepairRun"].filter((name) => new RegExp(`\\b${name}\\b`).test(body))
   ];
   let result = `import type { ${resultTypes.join(", ")} } from './validation-result.${importExt}'
 `;
@@ -63,10 +65,33 @@ const generateValidatorFile = (schema, typeName, options) => {
     "selectBranchErrors",
     "coerceScalar",
     "coerceUnion",
-    "applyRepairs"
-  ].filter((name) => body.includes(`${name}(`));
-  if (body.includes("MAX_REPAIR_PASSES"))
-    runtimeHelpers.push("MAX_REPAIR_PASSES");
+    "runRepairLoop",
+    "runRepairWalk",
+    "childAt",
+    "fillKey",
+    "fillInto",
+    "walkError",
+    "walkPath",
+    "walkRepair",
+    "walkVerified",
+    "walkSet",
+    "walkSetItem",
+    "walkCompact",
+    "walkMissing",
+    "walkScope",
+    "walkUnscope",
+    "fillBegin",
+    "walkExtra",
+    "walkProto",
+    "walkHalt",
+    "walkMemo",
+    "walkRef",
+    "isPlainObject"
+  ].filter((name) => body.includes(`${name}(`) || body.includes(`${name}<`));
+  for (const name of ["REPAIR_DROP", "NO_SEGMENTS", "MAX_FILL_DEPTH"]) {
+    if (new RegExp(`\\b${name}\\b`).test(body))
+      runtimeHelpers.push(name);
+  }
   if (runtimeHelpers.length > 0) {
     result += `import { ${runtimeHelpers.join(", ")} } from './validation-result.${importExt}'
 `;

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

@@ -5,28 +5,24 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  */
 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.
+ * Generates the repairing half of a validator file: the position lookup, the
+ * single-pass walk when the schema is one it covers, and the `repairX` that runs
+ * one or the other.
  *
- * 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.
+ * The lookup answers what a position repairs to, and both engines ask it, so
+ * they cannot land on different values. The walk checks and repairs every
+ * position in one pass; the loop — validate, repair the reported positions,
+ * validate again — is what every other schema gets. Either way, what is
+ * reported is the error the validator would have produced, and nothing
+ * second-guesses it.
  */
 export declare const generateRepairFunction: (schema: JSONSchema, typeName: string, typeSuffix?: string, options?: {
-    /** The whole document, for a `propertyNames` test that reads a `$ref`'s target. */
+    /** The whole document, for a test that reads a `$ref`'s target. */
     readonly rootSchema?: Record<string, unknown>;
-    /** The `format` names the validator enforces, so a key test agrees with it. */
+    /** The `format` names the validator enforces, so a test agrees with it. */
     readonly formats?: ReadonlySet<string>;
+    /** Whether to emit the single-pass walk, decided over the whole schema graph. */
+    readonly walk?: boolean;
 }) => {
     code: string;
 };