@amritk/generate-validators 0.16.1 → 0.17.0

package/AI.md

@@ -27,20 +27,27 @@ const files = await buildValidatorSchema(schema, 'Document')
    `validateFoo` returns `true | { valid: false; errors: ValidationError[] }`.
    Check `if (result !== true)` for the failure path — `if (result.valid)` is
    wrong.
-2. **Small signature:** `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?)`
+2. **Small signature:** `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?, formats?)`
    — async, no `strict`/`typesOnly`/options object. Returns `GeneratedFile[]` in
    memory (you write them). `unknownKeys` (`'count-keys'` by default,
    `'count-enumerable'` for Node-only output) picks how a closed object's guard
    counts keys; nothing in the generated code detects its runtime.
 3. **Output includes a shared `validation-result.ts`** (`ValidationError`,
-   `ValidationResult`, helpers) plus the `index.ts` barrel.
+   `ValidationResult`, helpers) plus the `index.ts` barrel — and a `formats.ts`
+   when `formats` is passed. Each error is
+   `{ message, path, keyword, params }`, the shape
+   `@amritk/runtime-validators` reports, so branch on `keyword` rather than
+   matching message text.
 4. **`NaN` fails a *constrained* number** (`minimum`/`maximum`/`multipleOf` all
    reject it) and satisfies a bare `{ "type": "number" }`, which is Ajv's answer
    too. 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;
+5. **`format` emits no check unless you pass `formats`.** By default it stays an
+   annotation, like the interpreter given no formats — but *not* like the
+   interpreter run with `{ formats: 'all' }` (`@amritk/lint`,
+   `createApi({ formats })`), which rejects strings such a validator accepts.
+   Pass `formats` (`'all'` or a list, or `--formats` on the CLI) and both
+   `validateX` and `isX` check them, against a `formats.ts` emitted alongside.
+   Set it to whatever validates the same schemas at runtime. `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 an *inert* `additionalItems` — one with no array

package/README.md

@@ -22,7 +22,11 @@
 Each generated file exports:
 
 - A TypeScript `type` definition for the schema
-- A `validateFoo(input: unknown, _path?: string): ValidationResult` function
+- A `validateFoo(input: unknown, _path?: string): ValidationResult` function, whose
+  errors carry the keyword that rejected the value and that keyword's own values
+  (`{ message, path, keyword, params }`) — the shape
+  [`@amritk/runtime-validators`](../runtime-validators) reports, so an error from
+  either can be rendered, translated or branched on by the same code
 - 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
@@ -84,7 +88,7 @@ if (!result.valid) {
 
 ## API
 
-### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?)`
+### `buildValidatorSchema(rootSchema, rootTypeName, typeSuffix?, schemas?, unknownKeys?, formats?)`
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
@@ -93,6 +97,7 @@ if (!result.valid) {
 | `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. |
 | `unknownKeys` | `'count-keys' \| 'count-enumerable'` | `'count-keys'` | How the fast paths prove a closed object (`additionalProperties: false`) has no undeclared key: `Object.keys(obj).length` (fastest on Bun) or a `for…in` count (fastest on Node). See [Choosing how keys are counted](#choosing-how-keys-are-counted). |
+| `formats` | `'all' \| string[]` | — | String `format`s the generated validators enforce. Unset leaves `format` an annotation, as JSON Schema reads it. See [Semantics](#semantics). |
 
 Returns: `Promise<GeneratedFile[]>` where `GeneratedFile = { filename: string; content: string }`.
 
@@ -169,12 +174,26 @@ is not. And a self-referential object reaches a verdict — the structural
 comparison stops at 512 levels — where it used to throw a `RangeError` out of a
 function whose signature promises a `ValidationResult`.
 
-**`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.
+**`format` is enforced when you ask for it.** JSON Schema treats `format` as an
+annotation, and so does this generator by default: `{ type: 'string', format:
+'uuid' }` produces the `typeof` check and nothing more, which matches the
+interpreter given no formats.
+
+Pass `formats` (`'all'`, or the names to check) and both `validateX` and the flat
+`isX` check them — the guard has to see the same set as the validator, or the two
+would disagree, which is the one thing it may never do. The checks are emitted
+into a `formats.ts` beside the validators, holding only the formats the schema
+names, because generated output is dependency-free and cannot import
+`@amritk/runtime-validators`' table.
+
+Two implementations of one rule is what drifts, so they are not merely assumed to
+agree: `emit-format-checks.test.ts` runs both over the official suite's whole
+optional/format corpus and requires the same verdict on every case.
+
+Set it to whatever validates the same schemas at runtime — `@amritk/lint` and
+`createApi({ formats })` run the interpreter with formats on — and the build-time
+and runtime answers agree. Leave it unset and they agree too, on the annotation
+reading.
 
 **`unevaluatedProperties` / `unevaluatedItems` are generated**, not refused. Each
 emits a flat expression computing what the interpreter computes as annotations: per
@@ -212,7 +231,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:
 
-**1274 / 1281 cases pass (99.5%).**
+**1276 / 1281 cases pass (99.6%).**
 
 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
@@ -220,10 +239,9 @@ 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 7 that do not pass: four `$dynamicRef`s whose binding depends on the
+Of the 5 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, and `$vocabulary`. Nothing on the
+path that reaches it, so it cannot bind per path), and `$vocabulary`. Nothing on the
 list is a keyword that silently returns the wrong answer.
 
 Every case is named in
@@ -322,10 +340,12 @@ are within a whisker of each other on both engines. 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.
+`email`), and Ajv, typia, zod, and TypeBox all check it, while the benchmark
+generates mjst's validators without `formats` — the default, where `format` is an
+annotation (see [Semantics](#semantics)). So on `small` and `order`, mjst is
+doing slightly less work than the columns beside it; pass `formats` and it does
+the same work. The parity samples fail other constraints too, which is why the
+verdicts still agree either way.
 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

package/dist/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 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 * 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";
+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 * 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";
 /**
  * Builds all TypeScript validator files from a JSON Schema by traversing all
  * `$ref` / `$dynamicRef` references recursively (via the shared
@@ -56,4 +56,4 @@ export declare const VALIDATION_RESULT_CONTENT = "/**\n * A single validation er
  * })
  * ```
  */
-export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy) => Promise<GeneratedFile[]>;
+export declare const buildValidatorSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string, schemas?: Readonly<Record<string, unknown>>, unknownKeys?: UnknownKeysStrategy, formats?: 'all' | readonly string[]) => Promise<GeneratedFile[]>;

package/dist/generators/build-schema.js

@@ -1,14 +1,28 @@
 import { generateIndexBarrel } from "@amritk/helpers/generate-index-barrel";
 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";
 const VALIDATION_RESULT_CONTENT = `/**
- * A single validation error with a human-readable message and a JSON Pointer
- * path indicating where in the document the error occurred.
+ * A single validation error: what went wrong, where, and which keyword said so.
+ *
+ * The shape matches \`@amritk/runtime-validators\`, so an error from a generated
+ * validator and one from the runtime interpreter can be handled by the same
+ * code \u2014 grouped, translated, or branched on \u2014 without knowing which produced it.
  */
 export type ValidationError = {
+  /** Human-readable description of what went wrong. */
   message: string
+  /** JSON Pointer to the offending value inside the instance. */
   path: string
+  /** The JSON Schema keyword that rejected the value \u2014 \`type\`, \`required\`, \`minimum\`, \u2026 */
+  keyword: string
+  /**
+   * The keyword's own values, as far as they explain the failure: the bound that
+   * was exceeded, the property that was missing, the allowed values that were not
+   * matched. Empty for a keyword with nothing to add beyond its name.
+   */
+  params: Record<string, unknown>
 }
 
 /**
@@ -225,7 +239,8 @@ const RESERVED_WORDS = /* @__PURE__ */ new Set([
   "with",
   "yield"
 ]);
-const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS) => {
+const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", schemas, unknownKeys = DEFAULT_UNKNOWN_KEYS, formats) => {
+  const enforced = formats === "all" ? new Set(Object.keys(FORMAT_FRAGMENTS)) : new Set((formats ?? []).filter((name) => Object.hasOwn(FORMAT_FRAGMENTS, name)));
   const files = [];
   walkRefGraph(rootSchema, rootTypeName, { typeSuffix, ...schemas !== void 0 ? { schemas } : {} }, (node) => {
     if (node.filename === "validation-result" || node.filename === "index") {
@@ -246,11 +261,16 @@ const buildValidatorSchema = async (rootSchema, rootTypeName, typeSuffix = "", s
       rootSchema: node.rootSchema,
       typeSuffix,
       unknownKeys,
+      formats: enforced,
       ...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);
+  if (formatModule !== "")
+    files.push({ filename: "formats.ts", content: formatModule });
   files.push({ filename: "index.ts", content: generateIndexBarrel(files) });
   return files;
 };

package/dist/generators/emit-format-checks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The `format` checks, as emittable source.
+ *
+ * Generated validators are dependency-free straight-line TypeScript — that is
+ * most of what makes them fast and all of what makes them readable — so a
+ * generated validator cannot import `@amritk/runtime-validators`' format table.
+ * It gets its own copy, and only of the formats the schema actually names.
+ *
+ * Two implementations of one rule is exactly the situation that drifts, so it is
+ * pinned rather than trusted: `emit-format-checks.test.ts` runs this source and
+ * the interpreter's table over the official suite's whole optional/format corpus
+ * and requires the same verdict on every case. A divergence fails the build.
+ *
+ * Each entry is a source *fragment*: a `const` declaration whose name is
+ * {@link formatCheckName}. Fragments may depend on shared helpers, named in
+ * `needs`, which are emitted once ahead of them.
+ *
+ * Nearly every string here is code for the *generated* file, so a `${…}` in one
+ * is a template hole in the emitted source rather than an interpolation that was
+ * meant to happen here — which is what `noTemplateCurlyInString` exists to catch
+ * and what makes it a false positive throughout this file.
+ */
+/** The identifier a format's check is emitted under. */
+export declare const formatCheckName: (format: string) => string;
+type FormatFragment = {
+    /** The JSON type the check takes — a format asserts about one and is silent about the rest. */
+    readonly family: 'string' | 'number';
+    /** Names of {@link SHARED} helpers this fragment reads. */
+    readonly needs?: readonly string[];
+    /** The `const <name> = …` declaration, with `<name>` already substituted. */
+    readonly source: (name: string) => string;
+};
+/**
+ * Every format the generator can emit a check for — the same set
+ * `@amritk/runtime-validators` enforces, and deliberately not a subset: a
+ * generator that silently skipped some would be the exact footgun this closes.
+ */
+export declare const FORMAT_FRAGMENTS: Readonly<Record<string, FormatFragment>>;
+/** The JSON type a format asserts about, or `undefined` when nothing defines it. */
+export declare const formatFamily: (format: string) => 'string' | 'number' | undefined;
+/**
+ * The source of a `formats.ts` module defining a check for each format in
+ * `formats`, or `''` when none of them is one this generator knows.
+ *
+ * Only the formats the schema actually names are emitted, along with whichever
+ * shared helpers those need — so a schema declaring one `uuid` gets one regex
+ * rather than the whole table.
+ */
+export declare const emitFormatModule: (formats: Iterable<string>) => string;
+export {};

package/dist/generators/emit-format-checks.js

@@ -0,0 +1,248 @@
+const formatCheckName = (format) => `isFormat${format.split(/[^A-Za-z0-9]+/).filter((part) => part !== "").map((part) => part[0]?.toUpperCase() + part.slice(1)).join("")}`;
+const SHARED = {
+  _asciiLabel: `const _asciiLabel = '[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?'`,
+  _idnLabel: `const _idnLabel = '[\\\\p{L}\\\\p{N}](?:[\\\\p{L}\\\\p{N}\\\\p{M}-]{0,61}[\\\\p{L}\\\\p{N}\\\\p{M}])?'`,
+  _ipv4Octets: [
+    `const _ipv4Octet = '(?:25[0-5]|2[0-4]\\\\d|1\\\\d\\\\d|[1-9]?\\\\d)'`,
+    "const _ipv4Octets = `(?:${_ipv4Octet}\\\\.){3}${_ipv4Octet}`"
+  ].join("\n"),
+  _ipv6Body: [
+    `const _h16 = '[0-9a-fA-F]{1,4}'`,
+    "const _ls32 = `(?:${_h16}:${_h16}|${_ipv4Octets})`",
+    "const _ipv6Body =",
+    "  `(?:(?:${_h16}:){6}${_ls32}` +",
+    "  `|::(?:${_h16}:){5}${_ls32}` +",
+    "  `|(?:${_h16})?::(?:${_h16}:){4}${_ls32}` +",
+    "  `|(?:(?:${_h16}:){0,1}${_h16})?::(?:${_h16}:){3}${_ls32}` +",
+    "  `|(?:(?:${_h16}:){0,2}${_h16})?::(?:${_h16}:){2}${_ls32}` +",
+    "  `|(?:(?:${_h16}:){0,3}${_h16})?::(?:${_h16}:)${_ls32}` +",
+    "  `|(?:(?:${_h16}:){0,4}${_h16})?::${_ls32}` +",
+    "  `|(?:(?:${_h16}:){0,5}${_h16})?::${_h16}` +",
+    "  `|(?:(?:${_h16}:){0,6}${_h16})?::)`"
+  ].join("\n"),
+  _uriGrammar: [
+    `const _subDelims = "!$&'()*+,;="`,
+    `const _pctEncoded = '%[0-9A-Fa-f]{2}'`,
+    "const _ucschar =",
+    "  '\\\\u00A0-\\\\uD7FF\\\\uF900-\\\\uFDCF\\\\uFDF0-\\\\uFFEF' +",
+    "  '\\\\u{10000}-\\\\u{1FFFD}\\\\u{20000}-\\\\u{2FFFD}\\\\u{30000}-\\\\u{3FFFD}\\\\u{40000}-\\\\u{4FFFD}' +",
+    "  '\\\\u{50000}-\\\\u{5FFFD}\\\\u{60000}-\\\\u{6FFFD}\\\\u{70000}-\\\\u{7FFFD}\\\\u{80000}-\\\\u{8FFFD}' +",
+    "  '\\\\u{90000}-\\\\u{9FFFD}\\\\u{A0000}-\\\\u{AFFFD}\\\\u{B0000}-\\\\u{BFFFD}\\\\u{C0000}-\\\\u{CFFFD}' +",
+    "  '\\\\u{D0000}-\\\\u{DFFFD}\\\\u{E1000}-\\\\u{EFFFD}'",
+    `const _iprivate = '\\\\uE000-\\\\uF8FF\\\\u{F0000}-\\\\u{FFFFD}\\\\u{100000}-\\\\u{10FFFD}'`,
+    'const _uriGrammar = (extraUnreserved: string, privateQuery = ""): { uri: string; reference: string } => {',
+    "  const unreserved = `A-Za-z0-9\\\\-._~${extraUnreserved}`",
+    "  const scheme = '[A-Za-z][A-Za-z0-9+\\\\-.]*'",
+    "  const pchar = `(?:[${unreserved}${_subDelims}:@]|${_pctEncoded})`",
+    "  const segment = `${pchar}*`",
+    "  const segmentNz = `${pchar}+`",
+    "  const segmentNzNc = `(?:[${unreserved}${_subDelims}@]|${_pctEncoded})+`",
+    "  const userinfo = `(?:[${unreserved}${_subDelims}:]|${_pctEncoded})*`",
+    "  const ipvFuture = `[Vv][0-9A-Fa-f]+\\\\.[${unreserved}${_subDelims}:]+`",
+    "  const ipLiteral = `\\\\[(?:${_ipv6Body}|${ipvFuture})\\\\]`",
+    "  const regName = `(?:[${unreserved}${_subDelims}]|${_pctEncoded})*`",
+    "  const host = `(?:${ipLiteral}|${_ipv4Octets}|${regName})`",
+    "  const authority = `(?:${userinfo}@)?${host}(?::\\\\d*)?`",
+    "  const pathAbempty = `(?:/${segment})*`",
+    "  const pathAbsolute = `/(?:${segmentNz}(?:/${segment})*)?`",
+    "  const pathRootless = `${segmentNz}(?:/${segment})*`",
+    "  const pathNoscheme = `${segmentNzNc}(?:/${segment})*`",
+    "  const hierPart = `(?://${authority}${pathAbempty}|${pathAbsolute}|${pathRootless}|)`",
+    "  const relativePart = `(?://${authority}${pathAbempty}|${pathAbsolute}|${pathNoscheme}|)`",
+    "  const query = `(?:\\\\?(?:${pchar}|[/?${privateQuery}])*)?`",
+    "  const fragment = `(?:#(?:${pchar}|[/?])*)?`",
+    "  return {",
+    "    uri: `^${scheme}:${hierPart}${query}${fragment}$`,",
+    "    reference: `^(?:${scheme}:${hierPart}|${relativePart})${query}${fragment}$`,",
+    "  }",
+    "}",
+    'const _asciiUri = _uriGrammar("")',
+    "const _iriUri = _uriGrammar(_ucschar, _iprivate)"
+  ].join("\n"),
+  _isDate: [
+    "const _dateShape = /^(\\d\\d\\d\\d)-(\\d\\d)-(\\d\\d)$/",
+    "const _daysInMonth = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]",
+    "const _isLeapYear = (year: number): boolean => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)",
+    "const _isDate = (value: string): boolean => {",
+    "  const matches = _dateShape.exec(value)",
+    "  if (matches === null) return false",
+    "  const year = +(matches[1] as string)",
+    "  const month = +(matches[2] as string)",
+    "  const day = +(matches[3] as string)",
+    "  if (month < 1 || month > 12 || day < 1) return false",
+    "  return day <= (month === 2 && _isLeapYear(year) ? 29 : (_daysInMonth[month] as number))",
+    "}"
+  ].join("\n"),
+  _timeCheck: [
+    "const _timeShape = /^(\\d\\d):(\\d\\d):(\\d\\d)(?:\\.\\d+)?(?:([Zz])|([+-])(\\d\\d):(\\d\\d))?$/",
+    "const _timeCheck =",
+    "  (requireOffset: boolean) =>",
+    "  (value: string): boolean => {",
+    "    const matches = _timeShape.exec(value)",
+    "    if (matches === null) return false",
+    "    const hour = +(matches[1] as string)",
+    "    const minute = +(matches[2] as string)",
+    "    const second = +(matches[3] as string)",
+    "    const zulu = matches[4] !== undefined",
+    '    const offsetSign = matches[5] === "-" ? -1 : 1',
+    "    const hasOffset = zulu || matches[5] !== undefined",
+    "    if (requireOffset && !hasOffset) return false",
+    "    const offsetHours = +(matches[6] ?? 0)",
+    "    const offsetMinutes = +(matches[7] ?? 0)",
+    "    if (hour > 23 || minute > 59 || second > 60 || offsetHours > 23 || offsetMinutes > 59) return false",
+    "    if (second < 60) return true",
+    "    const utcMinute = minute - offsetMinutes * offsetSign",
+    "    const utcHour = hour - offsetHours * offsetSign - (utcMinute < 0 ? 1 : 0)",
+    "    return (utcHour === 23 || utcHour === -1) && (utcMinute === 59 || utcMinute === -1)",
+    "  }",
+    "const _dateTimeSeparator = /t|\\s/i",
+    "const _dateTimeCheck = (time: (value: string) => boolean) => (value: string) => {",
+    "  const parts = value.split(_dateTimeSeparator)",
+    "  return parts.length === 2 && _isDate(parts[0] as string) && time(parts[1] as string)",
+    "}"
+  ].join("\n"),
+  _emailPattern: [
+    `const _asciiAtom = "[a-zA-Z0-9!#$%&'*+/=?^_\`{|}~-]"`,
+    `const _idnAtom = "[\\\\p{L}\\\\p{N}\\\\p{M}!#$%&'*+/=?^_\`{|}~-]"`,
+    "const _emailPattern = (atom: string, label: string, unicode: boolean): RegExp =>",
+    '  new RegExp(`^${atom}+(?:\\\\.${atom}+)*@(?:${label}\\\\.)+${label}$`, unicode ? "u" : "")'
+  ].join("\n")
+};
+const SHARED_NEEDS = {
+  _ipv6Body: ["_ipv4Octets"],
+  _uriGrammar: ["_ipv4Octets", "_ipv6Body"],
+  _timeCheck: ["_isDate"]
+};
+const regexFragment = (family, pattern, needs) => ({
+  family,
+  ...needs === void 0 ? {} : { needs },
+  source: (name) => `const ${name} = (value: string): boolean => ${pattern}.test(value)`
+});
+const builtFragment = (family, expression, needs) => ({
+  family,
+  needs,
+  source: (name) => `const ${name} = ${expression}`
+});
+const FORMAT_FRAGMENTS = {
+  email: builtFragment("string", "_emailPattern(_asciiAtom, _asciiLabel, false).test.bind(_emailPattern(_asciiAtom, _asciiLabel, false))", ["_emailPattern", "_asciiLabel"]),
+  "idn-email": builtFragment("string", "_emailPattern(_idnAtom, _idnLabel, true).test.bind(_emailPattern(_idnAtom, _idnLabel, true))", ["_emailPattern", "_idnLabel"]),
+  date: builtFragment("string", "_isDate", ["_isDate"]),
+  time: builtFragment("string", "_timeCheck(true)", ["_timeCheck"]),
+  "iso-time": builtFragment("string", "_timeCheck(false)", ["_timeCheck"]),
+  "date-time": builtFragment("string", "_dateTimeCheck(_timeCheck(true))", ["_timeCheck"]),
+  "iso-date-time": builtFragment("string", "_dateTimeCheck(_timeCheck(false))", ["_timeCheck"]),
+  duration: builtFragment("string", [
+    "((): ((value: string) => boolean) => {",
+    "  const second = '\\\\d+S'",
+    "  const minute = `\\\\d+M(?:${second})?`",
+    "  const hour = `\\\\d+H(?:${minute})?`",
+    "  const time = `T(?:${hour}|${minute}|${second})`",
+    "  const day = '\\\\d+D'",
+    "  const month = `\\\\d+M(?:${day})?`",
+    "  const year = `\\\\d+Y(?:${month})?`",
+    "  const date = `(?:${year}|${month}|${day})(?:${time})?`",
+    "  const pattern = new RegExp(`^P(?:${date}|${time}|\\\\d+W)$`)",
+    "  return (value) => pattern.test(value)",
+    "})()"
+  ].join("\n"), []),
+  uuid: regexFragment("string", "/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/"),
+  uri: builtFragment("string", "((re) => (value: string) => re.test(value))(new RegExp(_asciiUri.uri))", [
+    "_uriGrammar"
+  ]),
+  "uri-reference": builtFragment("string", "((re) => (value: string) => re.test(value))(new RegExp(_asciiUri.reference))", ["_uriGrammar"]),
+  iri: builtFragment("string", '((re) => (value: string) => re.test(value))(new RegExp(_iriUri.uri, "u"))', [
+    "_uriGrammar"
+  ]),
+  "iri-reference": builtFragment("string", '((re) => (value: string) => re.test(value))(new RegExp(_iriUri.reference, "u"))', ["_uriGrammar"]),
+  url: builtFragment("string", "((re) => (value: string) => /^(?:https?|ftp):\\/\\/[^/?#]/.test(value) && re.test(value))(new RegExp(_asciiUri.uri))", ["_uriGrammar"]),
+  "uri-template": builtFragment("string", [
+    "((): ((value: string) => boolean) => {",
+    "  const literal = `(?:[!#$&(-;=?-\\\\[\\\\]_a-z~${_ucschar}${_iprivate}]|${_pctEncoded})`",
+    "  const varchar = `(?:[A-Za-z0-9_]|${_pctEncoded})`",
+    "  const varname = `${varchar}(?:\\\\.?${varchar})*`",
+    "  const modifier = '(?::[1-9]\\\\d{0,3}|\\\\*)?'",
+    "  const varspec = `${varname}${modifier}`",
+    "  const expression = `\\\\{[+#./;?&=,!@|]?${varspec}(?:,${varspec})*\\\\}`",
+    '  const pattern = new RegExp(`^(?:${literal}|${expression})*$`, "iu")',
+    "  return (value) => pattern.test(value)",
+    "})()"
+  ].join("\n"), ["_uriGrammar"]),
+  "json-pointer": regexFragment("string", "/^(?:\\/(?:[^~/]|~[01])*)*$/"),
+  "json-pointer-uri-fragment": regexFragment("string", "/^#(?:\\/(?:[^~/]|~[01])*)*$/"),
+  "relative-json-pointer": regexFragment("string", "/^(?:0|[1-9]\\d*)(?:#|(?:\\/(?:[^~/]|~[01])*)*)$/"),
+  hostname: builtFragment("string", "((re) => (value: string) => re.test(value))(new RegExp(`^(?=.{1,253}$)${_asciiLabel}(?:\\\\.${_asciiLabel})*$`))", ["_asciiLabel"]),
+  "idn-hostname": builtFragment("string", '((re) => (value: string) => re.test(value))(new RegExp(`^(?=.{1,253}$)${_idnLabel}(?:\\\\.${_idnLabel})*$`, "u"))', ["_idnLabel"]),
+  ipv4: builtFragment("string", "((re) => (value: string) => re.test(value))(new RegExp(`^${_ipv4Octets}$`))", [
+    "_ipv4Octets"
+  ]),
+  ipv6: builtFragment("string", "((re) => (value: string) => re.test(value))(new RegExp(`^${_ipv6Body}$`))", [
+    "_ipv6Body"
+  ]),
+  regex: {
+    family: "string",
+    source: (name) => `const ${name} = (value: string): boolean => {
+  try {
+    new RegExp(value)
+    return true
+  } catch {
+    return false
+  }
+}`
+  },
+  byte: regexFragment("string", "/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/"),
+  binary: { family: "string", source: (name) => `const ${name} = (_value: string): boolean => true` },
+  password: { family: "string", source: (name) => `const ${name} = (_value: string): boolean => true` },
+  int32: {
+    family: "number",
+    source: (name) => `const ${name} = (value: number): boolean => Number.isInteger(value) && value >= -(2 ** 31) && value <= 2 ** 31 - 1`
+  },
+  int64: { family: "number", source: (name) => `const ${name} = (value: number): boolean => Number.isInteger(value)` },
+  float: { family: "number", source: (name) => `const ${name} = (_value: number): boolean => true` },
+  double: { family: "number", source: (name) => `const ${name} = (_value: number): boolean => true` }
+};
+const formatFamily = (format) => Object.hasOwn(FORMAT_FRAGMENTS, format) ? FORMAT_FRAGMENTS[format].family : void 0;
+const emitFormatModule = (formats) => {
+  const wanted = [...new Set(formats)].filter((format) => Object.hasOwn(FORMAT_FRAGMENTS, format)).sort();
+  if (wanted.length === 0)
+    return "";
+  const needed = /* @__PURE__ */ new Set();
+  const require2 = (helper) => {
+    if (needed.has(helper))
+      return;
+    needed.add(helper);
+    for (const nested of SHARED_NEEDS[helper] ?? [])
+      require2(nested);
+  };
+  for (const format of wanted) {
+    for (const helper of FORMAT_FRAGMENTS[format].needs ?? [])
+      require2(helper);
+  }
+  const helpers = Object.keys(SHARED).filter((helper) => needed.has(helper));
+  const checks = wanted.map((format) => {
+    const fragment = FORMAT_FRAGMENTS[format];
+    const name = formatCheckName(format);
+    return `${fragment.source(name)}
+export { ${name} }`;
+  });
+  return [
+    "/**",
+    " * `format` checks for the formats this schema declares.",
+    " *",
+    " * Generated alongside the validators that call them, so the emitted code",
+    " * stays dependency-free. Behaviour matches `@amritk/runtime-validators` run",
+    " * with the same formats enabled \u2014 a differential test over the official",
+    " * suite's optional/format corpus holds the two together.",
+    " */",
+    "",
+    ...helpers.map((helper) => SHARED[helper]),
+    "",
+    ...checks,
+    ""
+  ].join("\n");
+};
+export {
+  FORMAT_FRAGMENTS,
+  emitFormatModule,
+  formatCheckName,
+  formatFamily
+};

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

@@ -1,9 +1,14 @@
 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.
+ * (`title`, `description`, `default`, `$defs`, …) are deliberately absent: they
+ * change no verdict, so a node carrying only those is still "just" whatever its
+ * one validation keyword says.
+ *
+ * `format` is the one keyword whose membership is not fixed. It is an annotation
+ * by default — the 2020-12 reading, and the interpreter's — and an assertion
+ * when the caller asks for formats to be enforced, so every predicate here takes
+ * the enforced set rather than reading a constant.
  */
 export declare const ENFORCED_KEYWORDS: Set<string>;
 /**
@@ -18,4 +23,11 @@ export declare const ENFORCED_KEYWORDS: Set<string>;
  * 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;
+export declare const declaresKeywordOutside: (schema: JSONSchema, owned: readonly string[], formats?: ReadonlySet<string>) => boolean;
+/** No formats enforced — the default, and what makes `format` an annotation. */
+export declare const NO_FORMATS: ReadonlySet<string>;
+/**
+ * Whether this node's `format` is one the caller asked to enforce, making it an
+ * assertion rather than an annotation.
+ */
+export declare const enforcesFormat: (schema: Record<string, unknown>, formats: ReadonlySet<string>) => boolean;

package/dist/generators/enforced-keywords.js

@@ -43,18 +43,28 @@ const ENFORCED_KEYWORDS = /* @__PURE__ */ new Set([
   "unevaluatedProperties",
   "unevaluatedItems"
 ]);
-const declaresKeywordOutside = (schema, owned) => {
+const declaresKeywordOutside = (schema, owned, formats = NO_FORMATS) => {
   if (!isSchemaObject(schema))
     return false;
-  for (const keyword of Object.keys(schema)) {
+  const record = schema;
+  for (const keyword of Object.keys(record)) {
     if (owned.includes(keyword))
       continue;
     if (ENFORCED_KEYWORDS.has(keyword))
       return true;
+    if (keyword === "format" && enforcesFormat(record, formats))
+      return true;
   }
   return false;
 };
+const NO_FORMATS = /* @__PURE__ */ new Set();
+const enforcesFormat = (schema, formats) => {
+  const format = schema["format"];
+  return typeof format === "string" && formats.has(format);
+};
 export {
   ENFORCED_KEYWORDS,
-  declaresKeywordOutside
+  NO_FORMATS,
+  declaresKeywordOutside,
+  enforcesFormat
 };

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

@@ -12,4 +12,4 @@
  * 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;
+export declare const foldsToConstant: (schema: unknown, formats?: ReadonlySet<string>) => boolean | undefined;