@amritk/generate-validators 0.11.11 → 0.12.0

package/AI.md

@@ -34,5 +34,13 @@ const files = await buildValidatorSchema(schema, 'Document')
    `ValidationResult`, helpers) plus the `index.ts` barrel.
 4. **`NaN` satisfies numeric bounds** (`minimum`/`maximum`/`multipleOf`) — differs
    from Ajv. Draft-07 schemas are auto-upgraded to 2020-12.
+5. **`format` emits no check.** It stays an annotation, like the interpreter's
+   default — but *not* like the interpreter run with `{ formats: 'all' }`
+   (`@amritk/lint`, `createApi({ formats })`), which rejects strings a generated
+   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.
 
 Only the `.` entry. Install: `bun add @amritk/generate-validators`.

package/README.md

@@ -23,6 +23,9 @@ Each generated file exports:
 
 - A TypeScript `type` definition for the schema
 - A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+- An `isFoo(input: unknown): input is Foo` boolean type guard — a single flat
+  predicate (no error array, no cold-path call) reaching the same verdict as
+  `validateFoo`, for the common "is this valid?" question
 
 A shared `validation-result.ts` template and an `index.ts` barrel are emitted alongside the generated files.
 
@@ -81,15 +84,40 @@ if (!result.valid) {
 
 ## API
 
-### `buildValidatorSchema(rootSchema, rootTypeName)`
+### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?)`
 
-| Parameter | Type | Description |
-|:---|:---|:---|
-| `rootSchema` | `JSONSchema` | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. Draft-07 schemas are upgraded to 2020-12 automatically. |
-| `rootTypeName` | `string` | Name used for the root type (e.g. `"Document"`). |
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `rootSchema` | `JSONSchema` | — | The root schema to traverse. `$ref` and `$dynamicRef` are resolved recursively. Draft-07 schemas are upgraded to 2020-12 automatically. |
+| `rootTypeName` | `string` | — | Name used for the root type (e.g. `"Document"`). |
+| `typeSuffix` | `string` | `''` | Suffix appended to every `$ref`-derived type name (`'Object'` turns `Contact` into `ContactObject`). The root type name is unaffected. |
+| `schemas` | `Record<string, unknown>` | — | Documents you have **already loaded**, keyed by the absolute URI a `$ref` names them by. See below. |
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
+#### Referencing another document
+
+A `$ref` to a URI is resolvable once you hand over the document behind it:
+
+```typescript
+const files = await buildValidatorSchema({ $ref: 'https://example.com/user.json' }, 'Document', '', {
+  'https://example.com/user.json': userSchema,
+})
+```
+
+Each registered document becomes a resource of the generated document: its `$id`,
+its `$anchor`s and `$dynamicAnchor`s and its own embedded resources all resolve, a
+`$ref` from one registered document into another resolves, and each definition
+reached gets a file and a type like any other. A document with no `$id` resolves
+its relative `$ref`s against the URI you registered it under; one whose `$id`
+disagrees answers to both.
+
+Nothing is fetched — you cannot pass a URL, only a document — so generation stays
+a pure function of its inputs. Loading is yours to do, or
+[`@amritk/resolve-refs`](../resolve-refs)'. Registering more than the schema uses
+costs nothing: only the documents actually reached are emitted. A `$ref` to a URI
+nobody registered still stops the build, with a message naming the ref.
+
 ---
 
 ## Semantics
@@ -103,13 +131,81 @@ per-item work (a bare `string[]` is free; a closed object with several fields is
 meaningfully slower), which is why array-heavy schemas validate more slowly than
 scalar/object ones.
 
-One divergence is worth calling out: **`NaN` satisfies a constrained number.**
-Because the numeric bound checks are the exact negation of the error condition
-(e.g. `!(x < minimum)`), and every comparison against `NaN` is `false`, a `NaN`
-passes `minimum`/`maximum`/`exclusive*`/`multipleOf`. This matches the interpreter
-but differs from validators (e.g. Ajv) that reject `NaN` for `type: "number"`.
-`NaN` never appears in parsed JSON; guard against it upstream if your values can
-be non-JSON.
+**A schema needs no `type` for its keywords to be enforced.** `{ minLength: 2 }`,
+`{ required: ['a'] }` and `{ uniqueItems: true }` each emit their check behind a
+runtime test for the family they constrain, so they reject a bad string / object /
+array and *ignore* every other kind of value — which is what JSON Schema means by
+a type-less constraint, and what the interpreter does. One consequence is worth
+knowing: object keywords no longer imply `type: 'object'`, so `validateX` accepts
+`42` against `{ properties: { … } }`, while the emitted TypeScript type still
+describes the object case (as `FromSchema` does in `@amritk/runtime-validators`).
+The verdict is the contract and it matches the interpreter exactly; for that one
+shape `isX` is a weaker type guard than the type it names. Declare a `type` — as
+almost every real schema does — and the guard is exact again.
+
+**`format` emits no check.** JSON Schema treats `format` as an annotation, and so
+does this generator: `{ type: 'string', format: 'uuid' }` produces the `typeof`
+check and nothing more. That matches the interpreter's default, but *not* the
+interpreter run with `{ formats: 'all' }` — as `@amritk/lint` and
+`createApi({ formats })` do — so a generated validator accepts strings those
+reject.
+
+**`unevaluatedProperties` / `unevaluatedItems` are generated**, not refused. Each
+emits a flat expression computing what the interpreter computes as annotations: per
+key or index, a boolean that is true when some keyword evaluated it. Keywords that
+must succeed for the value to be valid at all (`allOf` members, a `$ref` target, a
+satisfied `contains`) count unconditionally — sound, because the test is one
+conjunct of a validator that also asserts them — while conditional applicators
+(`anyOf` / `oneOf` branches, `if` / `then` / `else`, `dependentSchemas`) carry their
+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`.
+
+One edge worth calling out: **`NaN` fails a constrained number but satisfies an
+unconstrained one.** Every bound is emitted as the negated *pass* condition
+(`!(x >= minimum)`, not `x < minimum`), and `NaN` compares `false` against every
+operator, so it fails the bound — and `multipleOf` rejects it on both branches of
+the shared `@amritk/helpers/multiple-of-check`. A bare `{ type: 'number' }` with
+no constraint still accepts it, as Ajv does. This matches
+`@amritk/runtime-validators` exactly, and the match is pinned value-by-value in
+`interpreter-parity.test.ts` rather than asserted here. `NaN` never appears in
+parsed JSON, so this only matters for values built in memory.
+
+### Conformance, measured
+
+The semantics above are measured, not asserted.
+`src/generators/conformance.test.ts` generates a validator for each schema in the
+official [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
+(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%).**
+
+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
+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
+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.
+
+Every case is named in
+`src/generators/conformance-expected-failures.test-utils.ts` with its reason, and
+the test fails if a case moves in *either* direction — a regression breaks the
+build, and so does a case that starts passing without its entry being removed.
+
+If you need one of those refusals to be an answer instead, validate with
+[`@amritk/runtime-validators`](../runtime-validators), which passes the same corpus
+in full (**1281/1281**), at the cost of interpreting the schema at runtime.
+The corpus is vendored under
+[`fixtures/json-schema-test-suite`](../../fixtures/json-schema-test-suite); none
+of it is published.
 
 ---
 
@@ -129,23 +225,30 @@ Measured on Bun 1.3 (Linux x64), validating valid input at steady state:
 
 | schema | mjst (generated) | typia (transformed) | ajv (compiled) | typebox (compiled) | zod |
 |:--|--:|--:|--:|--:|--:|
-| small (4 fields) | **~48M** ops/s | ~5M ops/s | ~10.5M ops/s | ~5.3M ops/s | ~2M ops/s |
-| order (nested + array) | **~7.8M** ops/s | ~2.2M ops/s | ~3.5M ops/s | ~2.1M ops/s | ~0.5M ops/s |
-| assert-loose | **~184M** ops/s | ~183M ops/s | ~45M ops/s | ~63M ops/s | ~3.8M ops/s |
-| assert-strict | **~162M** ops/s | ~148M ops/s | ~22M ops/s | ~38M ops/s | ~1.3M ops/s |
+| small (4 fields) | **~49M** ops/s | ~6.4M ops/s | ~11M ops/s | ~5.7M ops/s | ~2.4M ops/s |
+| order (nested + array) | **~11M** ops/s | ~2.5M ops/s | ~4M ops/s | ~2.4M ops/s | ~0.52M ops/s |
+| assert-loose | **~177M** ops/s | ~162M ops/s | ~46M ops/s | ~70M ops/s | ~3.9M ops/s |
+| assert-strict | **~164M** ops/s | ~146M ops/s | ~20M ops/s | ~44M ops/s | ~1.5M ops/s |
 
 The `assert-loose` / `assert-strict` rows are the exact shape used by
 [`moltar/typescript-runtime-type-benchmarks`](https://github.com/moltar/typescript-runtime-type-benchmarks)
-(seven scalar roots plus a nested object): the boolean guard puts mjst clearly
-ahead of typia on `assert-strict` (with `additionalProperties: false`) and
-neck-and-neck with it on `assert-loose` — the two trade the lead run-to-run
-within noise. (typia and TypeBox still win the *invalid* path, where they bail on
+(seven scalar roots plus a nested object): the boolean guard keeps mjst ahead of
+typia on both, by ~10% on `assert-loose` and ~12% on `assert-strict` (with
+`additionalProperties: false`) — close enough that the two can trade the lead
+run-to-run. (typia and TypeBox still win the *invalid* path, where they bail on
 the first error rather than collecting a full error list.)
 
-Preparing a validator costs ~0.3–0.6 ms for mjst codegen and ~0.05–0.2 ms for a
-TypeBox `TypeCompiler` compile, versus ~9–12 ms for an Ajv compile. Every library
-agrees on every verdict; parity is asserted before timing (TypeBox is given
-uuid/email format checkers so every library does the same work). Each library is
+Preparing a validator costs ~0.3–0.7 ms for mjst codegen and ~0.04–0.3 ms for a
+TypeBox `TypeCompiler` compile, versus ~7–11 ms for an Ajv compile. Every library
+agrees on every verdict; parity is asserted before timing.
+
+One caveat on the first two rows: their schemas declare `format` (`uuid`,
+`email`), and Ajv, typia, zod, and TypeBox all check it, while mjst's generated
+validators treat it as an annotation (see [Semantics](#semantics)). So on `small`
+and `order`, mjst is doing slightly less work than the columns beside it — the
+parity samples fail other constraints too, which is why the verdicts still agree.
+The `assert-loose` / `assert-strict` rows carry no `format` and are the
+constraint-for-constraint comparison. Each library is
 timed in an isolated process over a pool of distinct inputs, reporting the median
 of many trials — so the optimiser can't hoist or eliminate the work and the
 numbers stay reproducible. Micro-benchmark figures vary by machine and runtime —

package/dist/generators/assert-generatable-refs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Throws when a schema would make the emitter call a validator that no file
+ * defines.
+ *
+ * The walker refuses an unresolvable `#`/HTTP `$ref` already, so those never get
+ * this far. A ref written against an `$id` does: the walker's queue skips it
+ * (nothing in the document is keyed by `int.json`), the import collector skips it
+ * for the same reason — and the emitter, which only ever looks at the ref
+ * *string*, happily writes `validateIntJson(input, _path)` anyway. The result is
+ * generated TypeScript that does not compile, which is a loud failure in the
+ * wrong place: it lands in the consumer's build, long after the schema that
+ * caused it is out of sight.
+ *
+ * Stopping here instead puts the failure next to its cause and names the ref, the
+ * same answer the resolvable-but-unsupported paths already give. Resolving these
+ * refs properly means tracking `$id` base URIs through the document, which is a
+ * separate feature — until it exists, refusing is the honest report.
+ */
+export declare const assertGeneratableRefs: (schema: unknown, typeName: string) => void;

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

@@ -0,0 +1,12 @@
+import { collectEmittedRefs } from "./collect-emitted-refs.js";
+const isGeneratableRef = (ref) => ref.startsWith("#") || ref.startsWith("http://") || ref.startsWith("https://");
+const assertGeneratableRefs = (schema, typeName) => {
+  for (const ref of collectEmittedRefs(schema)) {
+    if (isGeneratableRef(ref))
+      continue;
+    throw new Error(`[${typeName}] unresolvable $ref "${ref}": its target is not in this document, and generation reads no files, so the validator it would call is never emitted. Inline the other document first with @amritk/resolve-refs, rewrite the ref as an in-document pointer (e.g. "#/$defs/name") or an absolute http(s) URI keyed in "$defs", or validate this schema with the runtime interpreter, which takes documents you already have via its \`schemas\` option.`);
+  }
+};
+export {
+  assertGeneratableRefs
+};

package/dist/generators/assert-unevaluated-generatable.d.ts

@@ -0,0 +1,30 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+import { type UnevaluatedMatchFn } from './unevaluated-match.js';
+/**
+ * The message a node gets when its coverage cannot be worked out inline. Shared
+ * with the emitter so the gate and the code path it guards say the same thing.
+ */
+export declare const UNPROVABLE_COVERAGE_MESSAGE: (keyword: string) => string;
+/**
+ * Throws when a schema uses `unevaluatedProperties` / `unevaluatedItems` in a way
+ * the generated code cannot honour.
+ *
+ * Both keywords police whatever a value's *other* keywords left untouched, which
+ * the interpreter answers with annotations gathered during its walk. Generated
+ * code has no walk, so `unevaluated-match.ts` reconstructs the same answer as an
+ * expression — and where it cannot (a `$ref` that resolves to nothing or back to
+ * itself, a `$dynamicRef` whose target is only known at runtime, or a position
+ * this generator does not enforce at all), generation stops here.
+ *
+ * That is deliberately a refusal *per shape* rather than per keyword: the vast
+ * majority of `unevaluated*` schemas are expressible and are now generated. What
+ * is left is the handful the flat form genuinely cannot see through, and for
+ * those a build error is the honest report — far better than a validator that
+ * accepts documents the interpreter rejects.
+ *
+ * `$defs` / `definitions` are skipped: a referenced definition is generated as
+ * its own file and gated there, with its own fresh annotation scope (which is
+ * also what the spec says a `$ref` target gets), and an unreferenced one is never
+ * applied to anything.
+ */
+export declare const assertUnevaluatedGeneratable: (schema: JSONSchema, typeName: string, rootSchema: Record<string, unknown> | undefined, match: UnevaluatedMatchFn) => void;

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

@@ -0,0 +1,72 @@
+import { unevaluatedItemsExpr, unevaluatedPropertiesExpr } from "./unevaluated-match.js";
+const UNPROVABLE_COVERAGE_MESSAGE = (keyword) => `unsupported "${keyword}": working out which keys the schema already evaluated means reading through an applicator this generator cannot follow inline \u2014 an unresolvable or cyclic "$ref", or a "$dynamicRef", whose target is only known at validation time. Validate this schema with \`@amritk/runtime-validators\` instead.`;
+const SINGLE_SUBSCHEMA_KEYS = [
+  "additionalProperties",
+  "propertyNames",
+  "contains",
+  "not",
+  "if",
+  "then",
+  "else",
+  "unevaluatedProperties",
+  "unevaluatedItems"
+];
+const SUBSCHEMA_LIST_KEYS = ["allOf", "anyOf", "oneOf", "prefixItems"];
+const SUBSCHEMA_MAP_KEYS = ["properties", "patternProperties", "dependentSchemas", "dependencies"];
+const UNENFORCED_SUBSCHEMA_KEYS = ["additionalItems"];
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const check = (node, typeName, rootSchema, match, enforced) => {
+  const record = node;
+  for (const keyword of ["unevaluatedProperties", "unevaluatedItems"]) {
+    if (!(keyword in record) || record[keyword] === true)
+      continue;
+    if (!enforced) {
+      throw new Error(`[${typeName}] unsupported "${keyword}": it sits under "additionalItems", a subschema position this generator does not enforce, so the check would never run. Validate this schema with \`@amritk/runtime-validators\` instead.`);
+    }
+    const expression = keyword === "unevaluatedProperties" ? unevaluatedPropertiesExpr("_probe", node, rootSchema, 0, match) : unevaluatedItemsExpr("_probe", node, rootSchema, 0, match);
+    if (expression === null)
+      throw new Error(`[${typeName}] ${UNPROVABLE_COVERAGE_MESSAGE(keyword)}`);
+  }
+};
+const assertUnevaluatedGeneratable = (schema, typeName, rootSchema, match) => {
+  const visit = (node, enforced) => {
+    if (!isRecord(node))
+      return;
+    if ("unevaluatedProperties" in node || "unevaluatedItems" in node) {
+      check(node, typeName, rootSchema, match, enforced);
+    }
+    for (const key of SINGLE_SUBSCHEMA_KEYS) {
+      if (key in node)
+        visit(node[key], enforced);
+    }
+    const items = node["items"];
+    if (Array.isArray(items))
+      for (const entry of items)
+        visit(entry, enforced);
+    else if (items !== void 0)
+      visit(items, enforced);
+    for (const key of SUBSCHEMA_LIST_KEYS) {
+      const list = node[key];
+      if (Array.isArray(list))
+        for (const entry of list)
+          visit(entry, enforced);
+    }
+    for (const key of SUBSCHEMA_MAP_KEYS) {
+      const map = node[key];
+      if (!isRecord(map))
+        continue;
+      for (const entry of Object.values(map))
+        if (!Array.isArray(entry))
+          visit(entry, enforced);
+    }
+    for (const key of UNENFORCED_SUBSCHEMA_KEYS) {
+      if (key in node)
+        visit(node[key], false);
+    }
+  };
+  visit(schema, true);
+};
+export {
+  UNPROVABLE_COVERAGE_MESSAGE,
+  assertUnevaluatedGeneratable
+};

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

@@ -20,12 +20,28 @@ export type GeneratedFile = {
  *
  * @param rootSchema - The root JSON Schema to build from
  * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @param typeSuffix - Suffix appended to every type name derived from a `$ref`
+ *   (e.g. `'Object'` → `ContactObject`). Defaults to `''`. The root type name is
+ *   used verbatim and is not affected.
+ * @param schemas - Other schema documents you have **already loaded**, keyed by
+ *   the absolute URI a `$ref` names them by. Supplying them makes those URIs
+ *   resolvable, so the schema can reference a document that is not itself — each
+ *   one becomes a resource of the generated document, with its own `$id`,
+ *   anchors and nested resources all resolvable. Nothing is fetched here:
+ *   loading is yours to do (or `@amritk/resolve-refs`'), and a `$ref` to a URI
+ *   nobody registered still stops generation. Only the documents actually
+ *   referenced get files.
  * @returns An array of generated TypeScript files
  *
  * @example
  * ```typescript
  * const files = await buildValidatorSchema(schema, 'Document')
  * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'info.ts', ... }, ...]
+ *
+ * // Referencing a document you loaded yourself:
+ * const withRemote = await buildValidatorSchema({ $ref: 'https://example.com/user.json' }, 'Document', '', {
+ *   'https://example.com/user.json': userSchema,
+ * })
  * ```
  */
-export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string) => Promise<GeneratedFile[]>;
+export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string, schemas?: Readonly<Record<string, unknown>>) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -75,9 +75,9 @@ export const allUnique = (arr: readonly unknown[]): boolean => {
   return true
 }
 `;
-const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "") => {
+const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas) => {
   const files = [];
-  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+  walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
     if (node.filename === "validation-result" || node.filename === "index")
       return;
     const content = generateValidatorFile(node.schema, node.typeName, {

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

@@ -0,0 +1,26 @@
+/**
+ * Recursively walks a schema and yields every `$ref` the validator emitter turns
+ * into a `validateX(...)` call, in traversal order (duplicates included — the
+ * callers dedupe on what they key by).
+ *
+ * The emitter recurses into far more than properties/items/additionalProperties
+ * and the top-level combinators: it also delegates for `patternProperties`,
+ * `propertyNames`, `if`/`then`/`else`, `contains`, `prefixItems`,
+ * `dependentSchemas`, `not`, the `unevaluated*` subschemas, and objects nested
+ * inside any combinator branch. A `$ref` reached by *any* of those paths becomes
+ * a call in the output, so both the import collector and the generatability check
+ * have to see exactly this set — which is why the traversal lives here rather
+ * than in either of them.
+ *
+ * `$defs` / `definitions` are deliberately skipped: they are split into their own
+ * generated files rather than inlined into this one.
+ *
+ * Pass `rootSchema` to also pick up the refs an `unevaluated*` keyword reaches.
+ * Those are the one case where a call can appear in *this* file for a branch
+ * written in *another* definition: working out what a node's `$ref` target
+ * already evaluated means reading through that target's own `anyOf` / `oneOf` /
+ * `if`, and each of those branches is emitted here as a condition. Without the
+ * 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[];

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

@@ -0,0 +1,62 @@
+import { unevaluatedItemsExpr, unevaluatedPropertiesExpr } from "./unevaluated-match.js";
+const collectEmittedRefs = (value, refs = [], rootSchema) => {
+  if (typeof value !== "object" || value === null)
+    return refs;
+  if (Array.isArray(value)) {
+    for (const item of value)
+      collectEmittedRefs(item, refs, rootSchema);
+    return refs;
+  }
+  const schema = value;
+  if (rootSchema !== void 0 && ("unevaluatedProperties" in schema || "unevaluatedItems" in schema)) {
+    collectCoverageRefs(schema, 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);
+    }
+  }
+  for (const key of [
+    "items",
+    "additionalProperties",
+    "propertyNames",
+    "contains",
+    "if",
+    "then",
+    "else",
+    "not",
+    // The `unevaluated*` subschemas are validated against the leftover keys /
+    // indices, so a `$ref` inside one becomes a `validateX(...)` call like any
+    // other — and without it the generated file would call an import it never asked for.
+    "unevaluatedProperties",
+    "unevaluatedItems"
+  ]) {
+    if (key in schema)
+      collectEmittedRefs(schema[key], refs, rootSchema);
+  }
+  for (const key of ["oneOf", "anyOf", "allOf", "prefixItems"]) {
+    const list = schema[key];
+    if (Array.isArray(list)) {
+      for (const sub of list)
+        collectEmittedRefs(sub, refs, rootSchema);
+    }
+  }
+  return refs;
+};
+const collectCoverageRefs = (schema, refs, rootSchema) => {
+  const record = (_accessor, sub) => {
+    collectEmittedRefs(sub, refs);
+    return "true";
+  };
+  unevaluatedPropertiesExpr("_refs", schema, rootSchema, 0, record);
+  unevaluatedItemsExpr("_refs", schema, rootSchema, 0, record);
+};
+export {
+  collectEmittedRefs
+};

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

@@ -1,7 +1,7 @@
 import { refToFilename } from "@amritk/helpers/ref-to-filename";
 import { refToName } from "@amritk/helpers/ref-to-name";
 import { resolveRef } from "@amritk/helpers/resolve-ref";
-import { hasRef } from "@amritk/helpers/schema-guards";
+import { collectEmittedRefs } from "./collect-emitted-refs.js";
 const buildImport = (ref, suffix) => {
   const filename = refToFilename(ref);
   const typeName = refToName(ref, suffix);
@@ -12,47 +12,11 @@ const canonicalFilename = (ref) => {
   const base = ref.endsWith("-or-reference") ? ref.replace("-or-reference", "") : ref;
   return refToFilename(base);
 };
-const collectDirectRefs = (value, refs = []) => {
-  if (typeof value !== "object" || value === null)
-    return refs;
-  if (Array.isArray(value)) {
-    for (const item of value)
-      collectDirectRefs(item, refs);
-    return refs;
-  }
-  const schema = value;
-  if (hasRef(schema)) {
-    refs.push(schema.$ref);
-    return refs;
-  }
-  const subSchemaMaps = ["properties", "patternProperties", "dependentSchemas", "dependencies"];
-  for (const mapKey of subSchemaMaps) {
-    const map = schema[mapKey];
-    if (typeof map === "object" && map !== null && !Array.isArray(map)) {
-      for (const sub of Object.values(map))
-        collectDirectRefs(sub, refs);
-    }
-  }
-  const singleSubSchemas = ["items", "additionalProperties", "propertyNames", "contains", "if", "then", "else", "not"];
-  for (const key of singleSubSchemas) {
-    if (key in schema)
-      collectDirectRefs(schema[key], refs);
-  }
-  const arraySubSchemas = ["oneOf", "anyOf", "allOf", "prefixItems"];
-  for (const key of arraySubSchemas) {
-    const arr = schema[key];
-    if (Array.isArray(arr)) {
-      for (const sub of arr)
-        collectDirectRefs(sub, refs);
-    }
-  }
-  return refs;
-};
 const collectValidatorImports = (schema, options) => {
   const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
   const rootSchema = options?.rootSchema;
   const typeSuffix = options?.typeSuffix ?? "";
-  const refs = collectDirectRefs(schema);
+  const refs = collectEmittedRefs(schema, [], rootSchema);
   const seen = /* @__PURE__ */ new Set();
   const imports = [];
   for (const ref of refs) {

package/dist/generators/generate-files.js

@@ -8,8 +8,11 @@ const generateValidatorFile = (schema, typeName, options) => {
     rootSchema: options?.rootSchema,
     typeSuffix
   });
-  const typeDefinition = generateTypeDefinition(schema, typeName, { typeSuffix });
-  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix);
+  const typeDefinition = generateTypeDefinition(schema, typeName, {
+    typeSuffix,
+    ...options?.rootSchema !== void 0 ? { rootSchema: options.rootSchema } : {}
+  });
+  const validatorFunction = generateValidatorFunction(schema, typeName, typeSuffix, options?.rootSchema);
   const booleanGuard = generateBooleanGuard(schema, typeName, typeSuffix);
   let result = `import type { ValidationResult, ValidationError } from './validation-result.js'
 `;

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

@@ -1,6 +1,6 @@
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 /**
- * Generates the exported boolean type-guard `isTypeName(input): input is TypeName`.
+ * Generates the exported boolean guard `isTypeName`.
  *
  * Unlike `validateTypeName` (which returns rich `ValidationResult` errors), this
  * is a single flat boolean predicate — no error array, no cold-path call — so V8
@@ -8,6 +8,9 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * compiled checker. It returns the *same verdict* as the validator. When the
  * schema carries anything the flat form can't mirror exactly, it falls back to
  * `validateTypeName(input) === true`, which is always correct.
+ *
+ * The signature is `input is TypeName` whenever that narrowing is sound, and a
+ * plain `boolean` when it is not — see {@link typeDescribesEveryAcceptedValue}.
  */
 export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string, _suffix?: string) => string;
 /**
@@ -32,4 +35,4 @@ export declare const generateBooleanGuard: (schema: JSONSchema, typeName: string
  * // }
  * ```
  */
-export declare const generateValidatorFunction: (schema: JSONSchema, typeName: string, suffix?: string) => string;
+export declare const generateValidatorFunction: (schema: JSONSchema, typeName: string, suffix?: string, rootSchema?: Record<string, unknown>) => string;