@amritk/validation 0.5.0 → 0.6.0

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

@@ -0,0 +1,335 @@
+import { regexFlagsFor } from "@amritk/helpers/escape-regex-pattern";
+import { readKey } from "@amritk/helpers/read-key";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { namedTest, schemaMap, subschema } from "./repair-context.js";
+import { isReferenceSchema, leafKeywords } from "./repair-walkable.js";
+const repairWalkNameFor = (typeName) => `walk${typeName}Repair`;
+const SCALAR_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "null"]);
+const typeCondition = (type) => {
+  switch (type) {
+    case "string":
+      return `typeof v === 'string'`;
+    case "number":
+      return `(typeof v === 'number' && (!run.finite || Number.isFinite(v)))`;
+    case "integer":
+      return `Number.isInteger(v)`;
+    case "boolean":
+      return `typeof v === 'boolean'`;
+    case "null":
+      return `v === null`;
+    case "array":
+      return `Array.isArray(v)`;
+    default:
+      return `(typeof v === 'object' && v !== null && !Array.isArray(v) && (!run.plain || isPlainObject(v)))`;
+  }
+};
+const equalsCondition = (value) => {
+  if (typeof value === "number" && Number.isNaN(value))
+    return `Number.isNaN(v)`;
+  if (value !== null && typeof value === "object")
+    return `valuesEqual(v, ${JSON.stringify(value)})`;
+  return `(v as unknown) === ${JSON.stringify(value)}`;
+};
+const ownChecks = (node, ctx) => {
+  const checks = [];
+  const type = readKey(node, "type");
+  if (typeof type === "string") {
+    checks.push({
+      condition: typeCondition(type),
+      report: `found.push(walkError(run, 'type', ${JSON.stringify(`must be ${type}`)}, ${JSON.stringify({ type })}))`
+    });
+  } else if (Array.isArray(type)) {
+    const types = type;
+    checks.push({
+      condition: `(${types.map(typeCondition).join(" || ")})`,
+      report: `found.push(walkError(run, 'type', ${JSON.stringify(`must be ${types.join(" or ")}`)}, ${JSON.stringify({ type })}))`
+    });
+  }
+  const values = readKey(node, "enum");
+  if (Array.isArray(values)) {
+    const label = values.map((value) => JSON.stringify(value)).join(", ");
+    checks.push({
+      condition: values.length === 0 ? "false" : `(${values.map(equalsCondition).join(" || ")})`,
+      report: `found.push(walkError(run, 'enum', ${JSON.stringify(`must be one of: ${label}`)}, ${JSON.stringify({ allowedValues: values })}))`
+    });
+  }
+  if (Object.hasOwn(node, "const")) {
+    const value = node["const"];
+    checks.push({
+      condition: equalsCondition(value),
+      report: `found.push(walkError(run, 'const', ${JSON.stringify(`must be ${JSON.stringify(value)}`)}, ${JSON.stringify({ allowedValue: value })}))`
+    });
+  }
+  const leaf = leafKeywords(node);
+  if (leaf !== null) {
+    const test = namedTest(leaf, ctx.repair);
+    if (test !== true) {
+      const explain = ctx.repair.matcher.explain(leaf);
+      checks.push({
+        condition: test === false ? "false" : `${test}(v)`,
+        report: explain === null ? `found.push(walkError(run, 'false schema', 'boolean schema is false', {}))` : `for (const error of ${explain}(v, walkPath(run))) found.push(error)`
+      });
+    }
+  }
+  return checks;
+};
+const coercibleTypes = (node) => {
+  const type = readKey(node, "type");
+  const types = typeof type === "string" ? [type] : Array.isArray(type) ? type : [];
+  return types.length > 0 && types.every((entry) => SCALAR_TYPES.has(entry)) ? JSON.stringify(types) : null;
+};
+const walkChild = (walker, key, write) => [
+  `run.path.push(${key})`,
+  `const n = ${walker}(c, run)`,
+  `run.path.pop()`,
+  `if (n !== c) ${write}`
+];
+const inlineTypeId = (node, typeSuffix) => {
+  const branchName = (key) => {
+    const branch = readKey(node, key);
+    if (typeof branch !== "object" || branch === null)
+      return null;
+    const ref = readKey(branch, "$ref");
+    return typeof ref === "string" && Object.keys(branch).length === 1 ? refToName(ref, typeSuffix) : null;
+  };
+  const thenName = branchName("then");
+  const elseName = branchName("else");
+  const text = JSON.stringify(node);
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++)
+    hash = Math.imul(hash ^ text.charCodeAt(i), 16777619);
+  const digest = (hash >>> 0).toString(16).padStart(8, "0");
+  return thenName !== null && elseName !== null ? `${thenName}|${elseName}#${digest}` : `inline#${digest}`;
+};
+const falseWalker = (ctx, walkers) => {
+  const existing = walkers.get(false);
+  if (existing)
+    return existing;
+  const drop = ctx.lookupFor(false);
+  const name = "_walkFalse";
+  walkers.set(false, name);
+  ctx.repair.helpers.push([
+    `const ${name}: RepairWalk = (v, run) =>`,
+    `  walkRepair(run, v, [walkError(run, 'false schema', 'boolean schema is false', {})], ${drop}, () => false, null)`
+  ].join("\n"));
+  return name;
+};
+const emitWalk = (schema, ctx, walkers, isRoot) => {
+  if (schema === false)
+    return falseWalker(ctx, walkers);
+  if (!isSchemaObject(schema))
+    return null;
+  if (walkers.has(schema))
+    return walkers.get(schema) ?? null;
+  const node = schema;
+  const helpers = ctx.repair.helpers;
+  const ref = readKey(node, "$ref");
+  const refWalker = typeof ref === "string" ? repairWalkNameFor(refToName(ref, ctx.repair.typeSuffix)) : null;
+  const checks = ownChecks(node, ctx);
+  const properties = schemaMap(node, "properties") ?? {};
+  const required = readKey(node, "required")?.filter((key) => typeof key === "string");
+  const hasObjectPart = Object.keys(properties).length > 0 || required !== void 0 && required.length > 0 || readKey(node, "additionalProperties") !== void 0 || readKey(node, "patternProperties") !== void 0;
+  const items = subschema(node, "items");
+  const hasConditional = readKey(node, "if") !== void 0 || Array.isArray(readKey(node, "allOf"));
+  const ownsObjectType = readKey(node, "type") === "object";
+  if (refWalker !== null && checks.length === 0 && !hasObjectPart && items === void 0 && !hasConditional && !isRoot) {
+    walkers.set(schema, refWalker);
+    return refWalker;
+  }
+  const id = ctx.repair.next();
+  const name = `_walk${id}`;
+  walkers.set(schema, name);
+  const typeId = JSON.stringify(isRoot ? ctx.typeName : inlineTypeId(node, ctx.repair.typeSuffix));
+  const lookup = ctx.lookupFor(schema);
+  const body = [];
+  if (refWalker !== null) {
+    body.push(`v = ${refWalker}(v, run)`, `if (v === REPAIR_DROP) return v`);
+  }
+  if (checks.length > 0) {
+    const ok = checks.map((check) => check.condition).join(" && ");
+    const okName = `_walkOk${id}`;
+    const fixName = `_walkFix${id}`;
+    helpers.push(`const ${okName} = (v: unknown, ${/\brun\b/.test(ok) ? "run" : "_run"}: RepairRun): boolean => ${ok}`);
+    helpers.push([
+      `const ${fixName} = (v: unknown, run: RepairRun): unknown => {`,
+      `  const found: ValidationError[] = []`,
+      ...checks.map((check) => `  if (!(${check.condition})) ${check.report}`),
+      `  return walkRepair(run, v, found, ${lookup ?? "null"}, ${okName}, ${coercibleTypes(node) ?? "null"})`,
+      `}`
+    ].join("\n"));
+    body.push(`if (!(${ok})) {`, `  const fixed = ${fixName}(v, run)`, `  if (fixed !== v) return fixed === REPAIR_DROP ? fixed : walkVerified(run, fixed, ${name})`, `}`);
+  }
+  const container = [];
+  if (hasObjectPart || ownsObjectType)
+    container.push(...objectPart(node, properties, required ?? [], lookup, id, ctx, walkers));
+  if (items !== void 0)
+    container.push(...arrayPart(items, ctx, walkers));
+  const conditional = conditionalPart(node, name, typeId, lookup, ctx, walkers);
+  if (container.length > 0) {
+    body.push(`if (++run.work > run.maxWork || run.path.length > run.maxDepth) return walkHalt(run, v)`);
+    body.push(...container);
+  }
+  body.push(...conditional);
+  if (body.length === 0) {
+    walkers.set(schema, null);
+    return null;
+  }
+  const bodyName = container.length > 0 ? `_walkBody${id}` : name;
+  helpers.push([`const ${bodyName}: RepairWalk = (v, run) => {`, ...body.map((line) => `  ${line}`), `  return v`, `}`].join("\n"));
+  if (container.length > 0) {
+    helpers.push(`const ${name}: RepairWalk = (v, run) => (run.memo === null ? ${bodyName}(v, run) : walkMemo(run, v, ${bodyName}))`);
+  }
+  return name;
+};
+const objectPart = (node, properties, required, lookup, id, ctx, walkers) => {
+  const inner = [];
+  const write = (key) => `o = walkSet(run, o, o !== src, ${key}, n)`;
+  const requiredSet = new Set(required);
+  for (const [key, child] of Object.entries(properties)) {
+    const walker = emitWalk(child, ctx, walkers, false);
+    const quoted = JSON.stringify(key);
+    if (requiredSet.has(key)) {
+      if (walker === null) {
+        inner.push(`if (!Object.hasOwn(o, ${quoted})) o = walkMissing(run, o, o !== src, ${quoted}, ${lookup ?? "null"}, null)`);
+      } else {
+        inner.push(`if (Object.hasOwn(o, ${quoted})) {`, `  const c = o[${quoted}]`, ...walkChild(walker, quoted, write(quoted)).map((line) => `  ${line}`), `} else o = walkMissing(run, o, o !== src, ${quoted}, ${lookup ?? "null"}, ${walker})`);
+      }
+    } else if (walker !== null) {
+      inner.push(`{`, `  const c = o[${quoted}]`, `  if (c !== undefined && Object.hasOwn(o, ${quoted})) {`, ...walkChild(walker, quoted, write(quoted)).map((line) => `    ${line}`), `  }`, `}`);
+    }
+  }
+  for (const key of required) {
+    if (Object.hasOwn(properties, key))
+      continue;
+    const quoted = JSON.stringify(key);
+    inner.push(`if (!Object.hasOwn(o, ${quoted})) o = walkMissing(run, o, o !== src, ${quoted}, ${lookup ?? "null"}, null)`);
+  }
+  inner.push(...mapPart(node, properties, id, ctx, walkers));
+  return [
+    `if (typeof v === 'object' && v !== null && !Array.isArray(v)) {`,
+    `  const src = v as Record<string, unknown>`,
+    `  let o = src`,
+    `  if (run.plain) o = walkProto(run, o, false)`,
+    ...inner.map((line) => `  ${line}`),
+    `  v = o`,
+    `}`
+  ];
+};
+const mapPart = (node, properties, id, ctx, walkers) => {
+  const patterns = Object.entries(schemaMap(node, "patternProperties") ?? {}).map(([source, child]) => ({
+    source,
+    walker: emitWalk(child, ctx, walkers, false)
+  }));
+  const additional = subschema(node, "additionalProperties");
+  const additionalWalker = additional === void 0 || additional === false ? null : emitWalk(additional, ctx, walkers, false);
+  const closed = additional === false;
+  const patternsMatter = patterns.some((pattern) => pattern.walker !== null) || closed || additionalWalker !== null;
+  if (!patternsMatter)
+    return [];
+  const helpers = ctx.repair.helpers;
+  const lines = [`for (const k in src) {`, `  if (!Object.hasOwn(src, k)) continue`];
+  const declared = Object.keys(properties);
+  if (declared.length > 0) {
+    const setName = `_walkDeclared${id}`;
+    helpers.push(`const ${setName} = new Set(${JSON.stringify(declared)})`);
+    lines.push(`  if (${setName}.has(k)) continue`);
+  }
+  lines.push(`  if (o !== src && !Object.hasOwn(o, k)) continue`);
+  const needsMatched = patterns.length > 0 && (closed || additionalWalker !== null);
+  if (needsMatched)
+    lines.push(`  let matched = false`);
+  patterns.forEach((pattern, index) => {
+    const regexName = `_walkPattern${id}_${index}`;
+    helpers.push(`const ${regexName} = new RegExp(${JSON.stringify(pattern.source)}, ${JSON.stringify(regexFlagsFor(pattern.source))})`);
+    const walk = pattern.walker === null ? [] : [
+      `const c = o[k]`,
+      ...walkChild(pattern.walker, "k", `{`),
+      `  o = walkSet(run, o, o !== src, k, n)`,
+      `  if (n === REPAIR_DROP) continue`,
+      `}`
+    ];
+    if (!needsMatched && walk.length === 0)
+      return;
+    lines.push(`  if (${regexName}.test(k)) {`);
+    if (needsMatched)
+      lines.push(`    matched = true`);
+    lines.push(...walk.map((line) => `    ${line}`), `  }`);
+  });
+  const otherwise = needsMatched ? `if (!matched) ` : "";
+  if (closed) {
+    lines.push(`  ${otherwise}o = walkExtra(run, o, o !== src, k)`);
+  } else if (additionalWalker !== null) {
+    lines.push(`  ${otherwise}{`, `    const c = o[k]`, ...walkChild(additionalWalker, "k", `o = walkSet(run, o, o !== src, k, n)`).map((line) => `    ${line}`), `  }`);
+  }
+  lines.push(`}`);
+  return lines;
+};
+const arrayPart = (items, ctx, walkers) => {
+  const walker = emitWalk(items, ctx, walkers, false);
+  if (walker === null)
+    return [];
+  return [
+    `if (Array.isArray(v)) {`,
+    `  const src: unknown[] = v`,
+    `  let a = src`,
+    `  let dropped = false`,
+    `  for (let i = 0; i < src.length; i++) {`,
+    `    const c = src[i]`,
+    ...walkChild(walker, "i", `{`).map((line) => `    ${line}`),
+    `      if (n === REPAIR_DROP) dropped = true`,
+    `      a = walkSetItem(run, a, a !== src, i, n)`,
+    `    }`,
+    `  }`,
+    `  v = dropped ? walkCompact(a) : a`,
+    `}`
+  ];
+};
+const conditionalPart = (node, self, typeId, lookup, ctx, walkers) => {
+  const lines = [];
+  const leave = lookup === null ? "return v" : "return walkUnscope(run, v)";
+  const branch = (schema) => {
+    if (schema === void 0)
+      return [];
+    const walker = emitWalk(schema, ctx, walkers, false);
+    const out = walker === null ? [] : [`v = ${walker}(v, run)`, `if (v === REPAIR_DROP) ${leave}`];
+    if (isReferenceSchema(schema, ctx.rootSchema))
+      out.push(`walkRef(run, v, ${self}, ${typeId})`);
+    return out;
+  };
+  const ifSchema = subschema(node, "if");
+  const thenSchema = subschema(node, "then");
+  const elseSchema = subschema(node, "else");
+  if (ifSchema !== void 0 && (thenSchema !== void 0 || elseSchema !== void 0)) {
+    const test = namedTest(ifSchema, ctx.repair);
+    if (test === true)
+      lines.push(...branch(thenSchema));
+    else if (test === false)
+      lines.push(...branch(elseSchema));
+    else {
+      const thenLines = branch(thenSchema);
+      const elseLines = branch(elseSchema);
+      if (thenLines.length > 0) {
+        lines.push(`if (${test}(v)) {`, ...thenLines.map((line) => `  ${line}`));
+        if (elseLines.length > 0)
+          lines.push(`} else {`, ...elseLines.map((line) => `  ${line}`));
+        lines.push(`}`);
+      } else if (elseLines.length > 0) {
+        lines.push(`if (!${test}(v)) {`, ...elseLines.map((line) => `  ${line}`), `}`);
+      }
+    }
+  }
+  const allOf = readKey(node, "allOf");
+  if (Array.isArray(allOf)) {
+    for (const entry of allOf)
+      lines.push(...branch(entry));
+  }
+  if (lines.length === 0 || lookup === null)
+    return lines;
+  return [`walkScope(run, ${lookup})`, ...lines, `walkUnscope(run, v)`];
+};
+const emitRepairWalk = (schema, ctx) => emitWalk(schema, ctx, /* @__PURE__ */ new Map(), true);
+export {
+  emitRepairWalk,
+  repairWalkNameFor
+};

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

@@ -26,7 +26,12 @@ export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string
  * fallback runs the whole validator and builds every error on the way to `false`,
  * so there the coercer walks first instead.
  */
-export declare const generateBooleanGuardSource: (schema: JSONSchema, typeName: string, unknownKeys?: UnknownKeysStrategy, formats?: ReadonlySet<string>) => {
+export declare const generateBooleanGuardSource: (schema: JSONSchema, typeName: string, unknownKeys?: UnknownKeysStrategy, formats?: ReadonlySet<string>, refs?: {
+    /** The suffix `$ref`-derived names carry, so a ref's guard is called by its real name. */
+    readonly suffix?: string;
+    /** The whole document, for a ref that resolves inside it. */
+    readonly rootSchema?: Record<string, unknown>;
+}) => {
     code: string;
     standalone: boolean;
 };
@@ -96,11 +101,24 @@ export declare const createSubschemaMatcher: (suffix: string, rootSchema: Record
      * tested, which on a union-heavy document was most of what coercing it cost.
      */
     test: (sub: JSONSchema) => boolean | string;
+    /**
+     * The early-return body of {@link test}, or `null` where `test` would have to
+     * fall back to its buffered expression — a guard then calls the validator.
+     */
+    guardBody: (sub: JSONSchema) => boolean | string | null;
     /**
      * The same test as a named function, hoisted with the rest and shared with
      * every other test of the same subschema in this file — or a constant, or
      * `null` for a body only the buffered form of {@link test} can express.
      */
     named: (sub: JSONSchema) => boolean | string | null;
+    /**
+     * The name of a hoisted function that says why a value fails `sub` — every
+     * error `validateX` would report for it, rooted at the path it is handed — or
+     * `null` when `sub` has no checks to explain anything with. The repair walk
+     * calls it once a position has already failed, so it costs nothing on valid
+     * input.
+     */
+    explain: (sub: JSONSchema) => string | null;
     declarations: (text: string) => string[];
 };

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

@@ -20,6 +20,7 @@ const checkerName = (typeName) => `check${typeName}`;
 const propertyRead = (objVar, key) => safeAccessor(objVar, key);
 const PROTOTYPE_MEMBERS = new Set(Object.getOwnPropertyNames(Object.prototype));
 const protoLocalName = (key, depth) => `_own${depth}_${key}`;
+const propertyLocalName = (key, index, depth) => PROTOTYPE_MEMBERS.has(key) ? protoLocalName(key, depth) : `_v${depth}_${index}`;
 const hasOwnCheck = (objVar, key) => {
   if (PROTOTYPE_MEMBERS.has(key))
     return `Object.hasOwn(${objVar}, ${JSON.stringify(key)})`;
@@ -214,7 +215,7 @@ const generateMissingRequiredChecks = (schema, ctx) => {
   }
   return lines;
 };
-const generatePropertyChecks = (key, propSchema, isRequired, suffix, ctx) => {
+const generatePropertyChecks = (key, index, propSchema, isRequired, suffix, ctx) => {
   if (propSchema === false) {
     const path = `\`${ctx.pathPrefix}/${pointerSegment(key)}\``;
     const parentPath = ctx.depth === 0 ? "_path" : `\`${ctx.pathPrefix}\``;
@@ -234,18 +235,18 @@ const generatePropertyChecks = (key, propSchema, isRequired, suffix, ctx) => {
       `  }`
     ];
   }
-  const raw = PROTOTYPE_MEMBERS.has(key) ? protoLocalName(key, ctx.depth) : propertyRead(ctx.objVar, key);
+  const raw = propertyLocalName(key, index, ctx.depth);
   const lines = [
-    ...generatePropertyCheckLines(key, propSchema, isRequired, suffix, ctx),
+    ...generatePropertyCheckLines(key, raw, propSchema, isRequired, suffix, ctx),
     // `unevaluated*` is a sibling of everything else the property declares, and
     // several of the branches above return early, so it is appended here rather
     // than emitted inside them. The checks carry their own runtime type guard, so
     // an absent optional property is inert and needs no presence gate.
     ...generateUnevaluatedChecks(raw, `\`${ctx.pathPrefix}/${pointerSegment(key)}\``, propSchema, suffix, ctx)
   ];
-  if (lines.length === 0 || !PROTOTYPE_MEMBERS.has(key))
+  if (!readsBinding(raw, lines.join("\n")))
     return lines;
-  return [`  const ${protoLocalName(key, ctx.depth)} = ${propertyRead(ctx.objVar, key)}`, ...lines];
+  return [`  const ${raw} = ${propertyRead(ctx.objVar, key)}`, ...lines];
 };
 const singleIfBlock = (lines) => {
   if (lines.length < 3)
@@ -267,7 +268,11 @@ const generateKeywordChecks = (key, raw, path, schema, suffix, ctx, presence) =>
     const target = refToName(schema.$ref, suffix);
     const delegate = ctx.sink === FAIL_FAST_SINK ? [`  const _r = ${checkerName(target)}(${raw}, ${path})`, `  if (_r !== true) return _r`] : ctx.sink === MATCH_BOOL_SINK ? [`  if (!${ctx.refGuard(target)}(${raw})) return false`] : [
       `  const _r = ${validatorName(target)}(${raw}, ${path})`,
-      `  if (_r !== true) ${ctx.sink}.push(..._r.errors)`
+      // A loop rather than a spread: spreading passes every error as an
+      // argument, and a document with tens of thousands of errors under
+      // one reference overflows the engine's argument limit with a
+      // RangeError instead of returning them.
+      `  if (_r !== true) for (const _e of _r.errors) ${ctx.sink}.push(_e)`
     ];
     if (presence === "")
       lines.push(`  {`, ...delegate.map((line) => `  ${line}`), `  }`);
@@ -330,7 +335,7 @@ const generateKeywordChecks = (key, raw, path, schema, suffix, ctx, presence) =>
   }
   return lines;
 };
-const generatePropertyCheckLines = (key, propSchema, isRequired, suffix, ctx) => {
+const generatePropertyCheckLines = (key, raw, propSchema, isRequired, suffix, ctx) => {
   const parentPath = ctx.depth === 0 ? "_path" : `\`${ctx.pathPrefix}\``;
   const missing = [
     `  if (${missingCheck(ctx.objVar, key)}) {`,
@@ -341,7 +346,6 @@ const generatePropertyCheckLines = (key, propSchema, isRequired, suffix, ctx) =>
       return [...missing, `  }`];
     return [];
   }
-  const raw = PROTOTYPE_MEMBERS.has(key) ? protoLocalName(key, ctx.depth) : propertyRead(ctx.objVar, key);
   const path = `\`${ctx.pathPrefix}/${pointerSegment(key)}\``;
   if (isRequired) {
     const valueLines = generateKeywordChecks(key, raw, path, propSchema, suffix, ctx, "");
@@ -425,7 +429,7 @@ const generateConstraintChecks = (key, raw, path, propSchema, suffix, ctx) => {
     if (hasRef(itemSchema) && !declaresKeywordOutside(itemSchema, ["$ref"])) {
       const failFast = ctx.sink === FAIL_FAST_SINK;
       const target = refToName(itemSchema.$ref, suffix);
-      const onFailure = failFast ? "return _ir" : `${ctx.sink}.push(..._ir.errors)`;
+      const onFailure = failFast ? "return _ir" : `for (const _e of _ir.errors) ${ctx.sink}.push(_e)`;
       lines.push(`  if (Array.isArray(${raw})) {`);
       lines.push(`    for (let ${iv} = ${firstTailIndex}; ${iv} < ${raw}.length; ${iv}++) {`);
       if (ctx.sink === MATCH_BOOL_SINK) {
@@ -864,8 +868,8 @@ const generateInlineObjectChecks = (key, propSchema, raw, suffix, ctx) => {
   const required = new Set(hasRequired(propSchema) ? propSchema.required : []);
   const properties = hasProperties(propSchema) ? propSchema.properties : {};
   const innerLines = [];
-  for (const [childKey, childSchema] of Object.entries(properties)) {
-    innerLines.push(...generatePropertyChecks(childKey, childSchema, required.has(childKey), suffix, child));
+  for (const [index, [childKey, childSchema]] of Object.entries(properties).entries()) {
+    innerLines.push(...generatePropertyChecks(childKey, index, childSchema, required.has(childKey), suffix, child));
   }
   innerLines.push(...generateMissingRequiredChecks(propSchema, child));
   innerLines.push(...generatePatternAndAdditionalChecks(propSchema, suffix, child));
@@ -1193,8 +1197,8 @@ const generateObjectValidator = (schema, typeName, suffix, rootSchema, unknownKe
   const properties = hasProperties(schema) ? schema.properties : {};
   const ctx = createRootContext(rootSchema, formats, branchErrors, failFast);
   const propertyLines = [];
-  for (const [key, propSchema] of Object.entries(properties)) {
-    const checks = generatePropertyChecks(key, propSchema, required.has(key), suffix, ctx);
+  for (const [index, [key, propSchema]] of Object.entries(properties).entries()) {
+    const checks = generatePropertyChecks(key, index, propSchema, required.has(key), suffix, ctx);
     if (checks.length > 0) {
       propertyLines.push(...checks);
     }
@@ -1467,18 +1471,38 @@ const typeDescribesEveryAcceptedValue = (schema) => {
   return !IMPLICIT_OBJECT_KEYWORDS.some((keyword) => declaresKey(s, keyword));
 };
 const generateBooleanGuard = (schema, typeName, _suffix = "", unknownKeys = DEFAULT_UNKNOWN_KEYS, formats = NO_FORMATS) => generateBooleanGuardSource(schema, typeName, unknownKeys, formats).code;
-const generateBooleanGuardSource = (schema, typeName, unknownKeys = DEFAULT_UNKNOWN_KEYS, formats = NO_FORMATS) => {
+const generateBooleanGuardSource = (schema, typeName, unknownKeys = DEFAULT_UNKNOWN_KEYS, formats = NO_FORMATS, refs = {}) => {
   const name = guardName(typeName);
   const returns = typeDescribesEveryAcceptedValue(rewriteNullable(schema)) ? `input is ${typeName}` : "boolean";
-  const fallback = `export const ${name} = (input: unknown): ${returns} => ${validatorName(typeName)}(input) === true`;
+  const fallback = () => {
+    const matcher = createSubschemaMatcher(refs.suffix ?? "", refs.rootSchema ?? (isSchemaObject(schema) ? schema : void 0), formats, "_guard");
+    const body = matcher.guardBody(schema);
+    if (typeof body !== "string" || !readsBinding("input", body)) {
+      return {
+        code: `export const ${name} = (input: unknown): ${returns} => ${validatorName(typeName)}(input) === true`,
+        standalone: false
+      };
+    }
+    const declarations = matcher.declarations(body);
+    const code = [
+      ...declarations.length > 0 ? [declarations.join("\n\n"), ""] : [],
+      `export const ${name} = (input: unknown): ${returns} => {`,
+      // Some checks build a path for a key or an index before they know whether
+      // they fail. Nothing reports it here, so it is rooted at nothing.
+      ...readsBinding("_path", body) ? [`  const _path = ''`] : [],
+      body,
+      `}`
+    ].join("\n");
+    return { code, standalone: true };
+  };
   const rewritten = rewriteNullable(schema);
   const ctx = createGuardContext(unknownKeys, formats);
   if (declaresObjectType(rewritten)) {
     if (!objectRootIsSelfContained(rewritten))
-      return { code: fallback, standalone: false };
+      return fallback();
     const block = booleanObjectParts(rewritten, "input", "obj", ctx);
     if (block === null)
-      return { code: fallback, standalone: false };
+      return fallback();
     const body = isFlatGuardBlock(block) ? [`  return (`, block.conditions.map((part) => `    ${part}`).join(" &&\n"), `  )`] : [...renderGuardBlock(block, "return false", "  ", "lines", unknownKeys), `  return true`];
     const code = [
       `export const ${name} = (input: unknown): ${returns} => {`,
@@ -1492,7 +1516,7 @@ const generateBooleanGuardSource = (schema, typeName, unknownKeys = DEFAULT_UNKN
   }
   const expr = booleanLeafExpr(rewritten, "input", ctx);
   if (expr === null)
-    return { code: fallback, standalone: false };
+    return fallback();
   return { code: `export const ${name} = (input: unknown): ${returns} => ${expr}`, standalone: true };
 };
 const generateScalarValidator = (schema, typeName, suffix, rootSchema, formats, branchErrors, failFast) => {
@@ -1790,12 +1814,23 @@ const createSubschemaMatcher = (suffix, rootSchema, formats, hoistNamespace, ref
   return true`;
       return `  return ${generateMatchesExpr("input", rewritten, suffix, ctx, true)}`;
     },
+    guardBody: (sub) => {
+      if (sub === false)
+        return false;
+      const state = { on: false, blocked: false };
+      const checks = generateValueChecks("", "input", "`${_path}`", rewriteNullable(sub), suffix, { ...ctx, sink: MATCH_BOOL_SINK, failFast: state, branchErrors: false }, true);
+      if (checks.length === 0)
+        return true;
+      return state.blocked ? null : `${checks.join("\n")}
+  return true`;
+    },
     named: (sub) => {
       if (sub === false)
         return false;
       const name = namedMatcher(rewriteNullable(sub), suffix, ctx);
       return name === "true" ? true : name;
     },
+    explain: (sub) => namedBranchErrors(rewriteNullable(sub), suffix, ctx),
     declarations: (text) => keptHoisted(ctx.hoisted, text)
   };
 };

package/dist/validators/generators/repair-context.d.ts

@@ -0,0 +1,39 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import type { createSubschemaMatcher } from './generate-validator-function.js';
+/**
+ * What the repairing half of one file is built from: its declarations, its
+ * numbering, and the tests the lookup and the walk share. One context per file,
+ * so the lookup and the walk emitted into it can never name two things alike.
+ */
+export type RepairContext = {
+    readonly typeSuffix: string;
+    /** Declarations, in the order they must appear. */
+    readonly helpers: string[];
+    /** Supplies the next unique suffix for a declaration. */
+    next: () => number;
+    /** The validator's own yes/no tests, for `propertyNames`, an `if`, and the walk. */
+    readonly matcher: ReturnType<typeof createSubschemaMatcher>;
+    /**
+     * The lookup already emitted for a subschema, by identity. The walk asks for
+     * the lookup of every node it checks, and a node must answer with the one
+     * function rather than a second copy of it.
+     */
+    readonly lookups: Map<unknown, string | null>;
+    /** The yes/no test already emitted for a subschema, by identity. */
+    readonly tests: Map<unknown, boolean | string>;
+    /** The shared lookup a `false` schema answers with, once something needs it. */
+    drop: string | null;
+};
+/**
+ * A named yes/no test of a value against `sub`, `true` when every value passes,
+ * or `false` when none does.
+ *
+ * It is the validator's own test, so the lookup, the walk and `validateX` agree
+ * on which branch a document takes. A body only the buffered form can express
+ * gets a function of its own here, as the coercer does it.
+ */
+export declare const namedTest: (sub: JSONSchema, ctx: RepairContext) => boolean | string;
+/** A schema map keyword (`properties`, …), read as own properties only. */
+export declare const schemaMap: (schema: Record<string, unknown>, key: string) => Record<string, JSONSchema> | undefined;
+/** A subschema keyword (`then`, `items`, …), when it holds a schema at all. */
+export declare const subschema: (schema: Record<string, unknown>, key: string) => JSONSchema | undefined;

package/dist/validators/generators/repair-context.js

@@ -0,0 +1,35 @@
+import { readKey } from "@amritk/helpers/read-key";
+const namedTest = (sub, ctx) => {
+  const known = ctx.tests.get(sub);
+  if (known !== void 0)
+    return known;
+  const named = ctx.matcher.named(sub);
+  if (named !== null) {
+    ctx.tests.set(sub, named);
+    return named;
+  }
+  const body = ctx.matcher.test(sub);
+  if (typeof body !== "string") {
+    ctx.tests.set(sub, body);
+    return body;
+  }
+  const name = `_repairTest${ctx.next()}`;
+  const parameter = /\binput\b/.test(body) ? "input" : "_input";
+  const path = /\b_path\b/.test(body) ? [`  const _path = ''`] : [];
+  ctx.helpers.push([`const ${name} = (${parameter}: unknown): boolean => {`, ...path, body, `}`].join("\n"));
+  ctx.tests.set(sub, name);
+  return name;
+};
+const schemaMap = (schema, key) => {
+  const value = readKey(schema, key);
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+};
+const subschema = (schema, key) => {
+  const value = readKey(schema, key);
+  return typeof value === "boolean" || typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+};
+export {
+  namedTest,
+  schemaMap,
+  subschema
+};