@amritk/generate-validators 0.12.2 → 0.13.1

package/AI.md

@@ -40,7 +40,8 @@ const files = await buildValidatorSchema(schema, 'Document')
    validator accepts. `unevaluatedProperties`/`unevaluatedItems` *are* generated;
    four shapes still refuse (coverage through a `$dynamicRef`, an unresolvable or
    cyclic `$ref` at the same instance location, a walk deeper than eight
-   applicators, a node under `additionalItems`), and generation **throws** for
-   those rather than widening the verdict.
+   applicators, a node under an *inert* `additionalItems` — one with no array
+   `items`, or with `prefixItems` alongside), and generation **throws** for those
+   rather than widening the verdict.
 
 Only the `.` entry. Install: `bun add @amritk/generate-validators`.

package/README.md

@@ -160,7 +160,10 @@ conjunct of a validator that also asserts them — while conditional applicators
 condition, hoisted out of the per-key loop. Four shapes still refuse, each named as
 a shape rather than as a keyword: coverage running through a `$dynamicRef`, an
 unresolvable or cyclic `$ref` at the same instance location, a walk deeper than
-eight applicators, and a node under `additionalItems`.
+eight applicators, and a node under an *inert* `additionalItems` — one with no
+array `items` to be the tail of, or with a `prefixItems` that took the positions
+out from under it. The draft-07 tail itself is validated, so the draft-07
+spelling of a schema whose 2020-12 spelling generates is accepted too.
 
 One edge worth calling out: **`NaN` fails a constrained number but satisfies an
 unconstrained one.** Every bound is emitted as the negated *pass* condition
@@ -180,7 +183,7 @@ official [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema
 (the required Draft 2020-12 tests — 1281 cases), compiles and links the emitted
 files in memory, and runs the suite's instances through the real generated code:
 
-**1271 / 1281 cases pass (99.2%).**
+**1274 / 1281 cases pass (99.5%).**
 
 The suite's `remotes/` documents and the 2020-12 dialect metaschema are supplied
 through the `schemas` option, which is how the suite intends a validator that does
@@ -188,12 +191,11 @@ no I/O to answer the retrieval step. Everything else — applying the base URIs,
 walking anchors across documents, naming and emitting a file per definition — the
 generator still has to do.
 
-Of the 10 that do not pass: five `$dynamicRef`s whose binding depends on the
+Of the 7 that do not pass: four `$dynamicRef`s whose binding depends on the
 evaluation path (a generator emits one function per definition, shared by every
 path that reaches it, so it cannot bind per path), two definitions in different
-embedded resources that reduce to one filename, two `$id`-scoped in-document
-pointers, and `$vocabulary`. Nothing on the list is a keyword that silently
-returns the wrong answer.
+embedded resources that reduce to one filename, and `$vocabulary`. Nothing on the
+list is a keyword that silently returns the wrong answer.
 
 Every case is named in
 `src/generators/conformance-expected-failures.test-utils.ts` with its reason, and

package/dist/generators/assert-unevaluated-generatable.js

@@ -13,7 +13,7 @@ const SINGLE_SUBSCHEMA_KEYS = [
 ];
 const SUBSCHEMA_LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
 const SUBSCHEMA_MAP_KEYS = ["properties", "patternProperties", "dependentSchemas", "dependencies"];
-const UNENFORCED_SUBSCHEMA_KEYS = ["additionalItems"];
+const additionalItemsIsEnforced = (node) => Array.isArray(node["items"]) && !Array.isArray(node["prefixItems"]);
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const check = (node, typeName, rootSchema, match, enforced) => {
   const record = node;
@@ -59,10 +59,8 @@ const assertUnevaluatedGeneratable = (schema, typeName, rootSchema, match) => {
         if (!Array.isArray(entry))
           visit(entry, enforced);
     }
-    for (const key of UNENFORCED_SUBSCHEMA_KEYS) {
-      if (key in node)
-        visit(node[key], false);
-    }
+    if ("additionalItems" in node)
+      visit(node["additionalItems"], enforced && additionalItemsIsEnforced(node));
   };
   visit(schema, true);
 };

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

@@ -6,6 +6,12 @@ export type GeneratedFile = {
     filename: string;
     content: string;
 };
+/**
+ * The runtime contract every generated validator imports: the `ValidationResult`
+ * 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 with a human-readable message and a JSON Pointer\n * path indicating where in the document the error occurred.\n */\nexport type ValidationError = {\n  message: string\n  path: string\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 * 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): boolean => {\n  if (a === b) return true\n  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) 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])) 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])) return false\n  }\n  return true\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. A native `Set` dedupes the all-primitive case\n * in one linear pass; object/array elements fall back to an exact pairwise\n * structural comparison.\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  for (let i = 0; i < len; i++) {\n    for (let j = i + 1; j < len; j++) {\n      if (valuesEqual(arr[i], arr[j])) return false\n    }\n  }\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";
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all
  * `$ref` / `$dynamicRef` references recursively (via the shared

package/dist/generators/build-schema.js

@@ -74,12 +74,31 @@ export const allUnique = (arr: readonly unknown[]): boolean => {
   }
   return true
 }
+
+/**
+ * Escapes one JSON Pointer segment (RFC 6901): \`~\` \u2192 \`~0\`, \`/\` \u2192 \`~1\`, in that
+ * order. Generated error paths are built from *runtime* keys wherever the schema
+ * did not name them \u2014 a \`patternProperties\` match, an \`additionalProperties\`
+ * sweep, a \`propertyNames\` loop \u2014 and a key containing a \`/\` would otherwise read
+ * back as two segments, so an error on \`{"a/b": \u2026}\` pointed at \`/a/b\`, which is
+ * the child \`b\` of a property \`a\`. Keys the schema *does* name are escaped at
+ * generation time instead, and \`@amritk/runtime-validators\` escapes the same way,
+ * so all three agree.
+ *
+ * The \`indexOf\` pre-test keeps the common key \u2014 no \`/\`, no \`~\` \u2014 off the replace
+ * path entirely, which is what the interpreter does for the same reason.
+ */
+export const escapePointer = (key: string): string =>
+  key.indexOf('/') !== -1 || key.indexOf('~') !== -1 ? key.replace(/~/g, '~0').replace(/\\//g, '~1') : key
 `;
 const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas) => {
   const files = [];
   walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
-    if (node.filename === "validation-result" || node.filename === "index")
-      return;
+    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";
+      throw new Error(`${owner} generates the file "${node.filename}.ts", which is reserved for ${purpose}. Rename the definition (or pass a different root type name) so it gets a file of its own.`);
+    }
     const content = generateValidatorFile(node.schema, node.typeName, {
       rootSchema: node.rootSchema,
       typeSuffix,
@@ -92,5 +111,6 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
   return files;
 };
 export {
+  VALIDATION_RESULT_CONTENT,
   buildValidatorSchema
 };

package/dist/generators/collect-emitted-refs.d.ts

@@ -23,4 +23,4 @@
  * root document there is nothing to resolve the target against, so the extra
  * refs are simply not collected.
  */
-export declare const collectEmittedRefs: (value: unknown, refs?: string[], rootSchema?: Record<string, unknown>) => string[];
+export declare const collectEmittedRefs: (value: unknown, refs?: string[], rootSchema?: Record<string, unknown>, includeTypeOnly?: boolean) => string[];

package/dist/generators/collect-emitted-refs.js

@@ -1,10 +1,26 @@
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+import { foldsToConstant } from "./folds-to-constant.js";
+import { tupleShapeOf } from "./tuple-shape.js";
 import { unevaluatedItemsExpr, unevaluatedPropertiesExpr } from "./unevaluated-match.js";
-const collectEmittedRefs = (value, refs = [], rootSchema) => {
+const armsOf = (schema) => {
+  if (!("if" in schema))
+    return [];
+  const condition = schema["if"];
+  if (!isSchemaObject(condition) && typeof condition !== "boolean")
+    return [];
+  const decided = foldsToConstant(condition);
+  if (decided === true)
+    return ["then"];
+  if (decided === false)
+    return ["else"];
+  return ["then", "else"];
+};
+const collectEmittedRefs = (value, refs = [], rootSchema, includeTypeOnly = false) => {
   if (typeof value !== "object" || value === null)
     return refs;
   if (Array.isArray(value)) {
     for (const item of value)
-      collectEmittedRefs(item, refs, rootSchema);
+      collectEmittedRefs(item, refs, rootSchema, includeTypeOnly);
     return refs;
   }
   const schema = value;
@@ -13,23 +29,36 @@ const collectEmittedRefs = (value, refs = [], rootSchema) => {
   }
   if (typeof schema["$ref"] === "string") {
     refs.push(schema["$ref"]);
-    return refs;
   }
   for (const mapKey of ["properties", "patternProperties", "dependentSchemas", "dependencies"]) {
     const map = schema[mapKey];
     if (typeof map === "object" && map !== null && !Array.isArray(map)) {
       for (const sub of Object.values(map))
-        collectEmittedRefs(sub, refs, rootSchema);
+        collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly);
+    }
+  }
+  const { tuple, tail } = tupleShapeOf(schema);
+  if (tail !== void 0)
+    collectEmittedRefs(tail, refs, rootSchema, includeTypeOnly);
+  if (includeTypeOnly && Array.isArray(schema["items"])) {
+    const additional = schema["additionalItems"];
+    if (additional !== void 0 && additional !== tail) {
+      collectEmittedRefs(additional, refs, rootSchema, includeTypeOnly);
     }
   }
   for (const key of [
-    "items",
     "additionalProperties",
     "propertyNames",
     "contains",
     "if",
-    "then",
-    "else",
+    // `then` / `else` only apply when there is an `if` to branch on, and neither
+    // emitter reads them without one — so a `$ref` there is never referenced,
+    // and collecting it refused schemas whose ref happened to be unresolvable.
+    //
+    // An `if` the emitter can decide picks its arm here too, and unlike `anyOf`
+    // the type generator reads neither arm — it types the whole node `unknown` —
+    // so the dropped arm is referenced by nobody. See {@link armsOf}.
+    ...armsOf(schema),
     "not",
     // The `unevaluated*` subschemas are validated against the leftover keys /
     // indices, so a `$ref` inside one becomes a `validateX(...)` call like any
@@ -38,15 +67,18 @@ const collectEmittedRefs = (value, refs = [], rootSchema) => {
     "unevaluatedItems"
   ]) {
     if (key in schema)
-      collectEmittedRefs(schema[key], refs, rootSchema);
+      collectEmittedRefs(schema[key], refs, rootSchema, includeTypeOnly);
   }
-  for (const key of ["oneOf", "anyOf", "allOf", "prefixItems"]) {
+  for (const key of ["oneOf", "anyOf", "allOf"]) {
     const list = schema[key];
-    if (Array.isArray(list)) {
-      for (const sub of list)
-        collectEmittedRefs(sub, refs, rootSchema);
-    }
+    if (!Array.isArray(list))
+      continue;
+    for (const sub of list)
+      collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly);
   }
+  if (tuple !== void 0)
+    for (const sub of tuple)
+      collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly);
   return refs;
 };
 const collectCoverageRefs = (schema, refs, rootSchema) => {

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

@@ -8,19 +8,15 @@ const buildImport = (ref, suffix) => {
   const validatorName = `validate${typeName}`;
   return `import { type ${typeName}, ${validatorName} } from './${filename}.js'`;
 };
-const canonicalFilename = (ref) => {
-  const base = ref.endsWith("-or-reference") ? ref.replace("-or-reference", "") : ref;
-  return refToFilename(base);
-};
 const collectValidatorImports = (schema, options) => {
   const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
   const rootSchema = options?.rootSchema;
   const typeSuffix = options?.typeSuffix ?? "";
-  const refs = collectEmittedRefs(schema, [], rootSchema);
+  const refs = collectEmittedRefs(schema, [], rootSchema, true);
   const seen = /* @__PURE__ */ new Set();
   const imports = [];
   for (const ref of refs) {
-    const filename = canonicalFilename(ref);
+    const filename = refToFilename(ref);
     if (seen.has(filename))
       continue;
     if (selfFilename && filename === selfFilename)
@@ -31,8 +27,7 @@ const collectValidatorImports = (schema, options) => {
         continue;
     }
     seen.add(filename);
-    const importRef = ref.endsWith("-or-reference") ? ref.replace("-or-reference", "") : ref;
-    imports.push(buildImport(importRef, typeSuffix));
+    imports.push(buildImport(ref, typeSuffix));
   }
   return imports;
 };

package/dist/generators/enforced-keywords.d.ts

@@ -0,0 +1,21 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Every keyword this generator turns into a runtime check. Annotations
+ * (`title`, `description`, `default`, `$defs`, `format`, …) are deliberately
+ * absent: they change no verdict, so a node carrying only those is still "just"
+ * whatever its one validation keyword says.
+ */
+export declare const ENFORCED_KEYWORDS: Set<string>;
+/**
+ * True when a node declares an enforced keyword outside the set an emitter
+ * `owns`.
+ *
+ * The specialised emitters — the top-level `$ref` delegation, the `const` and
+ * `enum` roots, the flat boolean guards — each recognise one keyword and write
+ * out a shape built around it. That shape has nowhere to put a sibling, so every
+ * one of them used to drop the siblings silently: `{ $ref, minLength: 3 }`
+ * accepted `"q"`, `{ type: 'string', const: 1 }` accepted `1`. Asking this first
+ * lets each of them keep its tight output for the node it really does describe,
+ * and hand anything richer to the general path.
+ */
+export declare const declaresKeywordOutside: (schema: JSONSchema, owned: readonly string[]) => boolean;

package/dist/generators/enforced-keywords.js

@@ -0,0 +1,60 @@
+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) => {
+  if (!isSchemaObject(schema))
+    return false;
+  for (const keyword of Object.keys(schema)) {
+    if (owned.includes(keyword))
+      continue;
+    if (ENFORCED_KEYWORDS.has(keyword))
+      return true;
+  }
+  return false;
+};
+export {
+  ENFORCED_KEYWORDS,
+  declaresKeywordOutside
+};

package/dist/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) => boolean | undefined;

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

@@ -0,0 +1,39 @@
+import { isSchemaObject } from "@amritk/helpers/schema-guards";
+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) => {
+  if (schema === true)
+    return true;
+  if (schema === false)
+    return false;
+  if (!isSchemaObject(schema))
+    return void 0;
+  return Object.keys(schema).every((key) => ANNOTATION_KEYWORDS.has(key)) ? true : void 0;
+};
+export {
+  foldsToConstant
+};

package/dist/generators/generate-files.js

@@ -14,10 +14,11 @@ const generateValidatorFile = (schema, typeName, options) => {
   });
   const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema);
   const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix);
-  let result = `import type { ValidationResult, ValidationError } from './validation-result.js'
-`;
   const body = validatorFunction + booleanGuard;
-  const runtimeHelpers = ["valuesEqual", "allUnique"].filter((name) => body.includes(`${name}(`));
+  const resultTypes = ["ValidationResult", .../\bValidationError\b/.test(body) ? ["ValidationError"] : []];
+  let result = `import type { ${resultTypes.join(", ")} } from './validation-result.js'
+`;
+  const runtimeHelpers = ["valuesEqual", "allUnique", "escapePointer"].filter((name) => body.includes(`${name}(`));
   if (runtimeHelpers.length > 0) {
     result += `import { ${runtimeHelpers.join(", ")} } from './validation-result.js'
 `;