@amritk/validation 0.2.0

package/dist/validators/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>, includeTypeOnly?: boolean, inlinedRefs?: Set<string>) => string[];

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

@@ -0,0 +1,112 @@
+import { declaresKey, readKey } from "@amritk/helpers/read-key";
+import { referencedConditional } from "@amritk/helpers/referenced-conditional";
+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 armsOf = (schema) => {
+  if (!declaresKey(schema, "if"))
+    return [];
+  const condition = readKey(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, inlinedRefs = /* @__PURE__ */ new Set()) => {
+  if (typeof value !== "object" || value === null)
+    return refs;
+  if (Array.isArray(value)) {
+    for (const item of value)
+      collectEmittedRefs(item, refs, rootSchema, includeTypeOnly, inlinedRefs);
+    return refs;
+  }
+  const schema = value;
+  if (rootSchema !== void 0 && (declaresKey(schema, "unevaluatedProperties") || declaresKey(schema, "unevaluatedItems"))) {
+    collectCoverageRefs(schema, refs, rootSchema);
+  }
+  const ref = readKey(schema, "$ref");
+  if (typeof ref === "string") {
+    refs.push(ref);
+  }
+  for (const mapKey of ["properties", "patternProperties", "dependentSchemas", "dependencies"]) {
+    const map = readKey(schema, mapKey);
+    if (typeof map === "object" && map !== null && !Array.isArray(map)) {
+      for (const sub of Object.values(map))
+        collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly, inlinedRefs);
+    }
+  }
+  const { tuple, tail } = tupleShapeOf(schema);
+  if (tail !== void 0)
+    collectEmittedRefs(tail, refs, rootSchema, includeTypeOnly, inlinedRefs);
+  if (includeTypeOnly && Array.isArray(readKey(schema, "items"))) {
+    const additional = readKey(schema, "additionalItems");
+    if (additional !== void 0 && additional !== tail) {
+      collectEmittedRefs(additional, refs, rootSchema, includeTypeOnly, inlinedRefs);
+    }
+  }
+  for (const key of [
+    "additionalProperties",
+    "propertyNames",
+    "contains",
+    "if",
+    // `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
+    // other — and without it the generated file would call an import it never asked for.
+    "unevaluatedProperties",
+    "unevaluatedItems"
+  ]) {
+    if (declaresKey(schema, key))
+      collectEmittedRefs(schema[key], refs, rootSchema, includeTypeOnly, inlinedRefs);
+  }
+  for (const key of ["oneOf", "anyOf", "allOf"]) {
+    const list = readKey(schema, key);
+    if (!Array.isArray(list))
+      continue;
+    for (const sub of list) {
+      collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly, inlinedRefs);
+      if (key !== "allOf" || !includeTypeOnly)
+        continue;
+      const memberRef = isSchemaObject(sub) ? readKey(sub, "$ref") : void 0;
+      if (typeof memberRef === "string" && inlinedRefs.has(memberRef))
+        continue;
+      const inlined = referencedConditional(sub, rootSchema);
+      if (inlined === void 0)
+        continue;
+      if (typeof memberRef === "string")
+        inlinedRefs.add(memberRef);
+      for (const arm of ["if", "then", "else"]) {
+        if (declaresKey(inlined, arm))
+          collectEmittedRefs(readKey(inlined, arm), refs, rootSchema, includeTypeOnly, inlinedRefs);
+      }
+    }
+  }
+  if (tuple !== void 0)
+    for (const sub of tuple)
+      collectEmittedRefs(sub, refs, rootSchema, includeTypeOnly, inlinedRefs);
+  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/validators/generators/collect-validator-imports.d.ts

@@ -0,0 +1,86 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling how validator imports are collected.
+ */
+type CollectValidatorImportsOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/encoding`).
+     * Prevents a file from importing itself.
+     */
+    readonly selfRef?: string | undefined;
+    /**
+     * The root schema document. URI refs that cannot be resolved within it
+     * are excluded from the import list (they were never generated as files).
+     */
+    readonly rootSchema?: Record<string, unknown> | undefined;
+    /**
+     * Suffix appended to every type/validator name derived from a `$ref`. Must
+     * match the suffix used when generating the referenced files. Defaults to `''`.
+     */
+    readonly typeSuffix?: string;
+    /**
+     * Extension on every emitted relative specifier. `'js'` is the NodeNext form a
+     * compiled consumer needs; `'ts'` is the literal on-disk path, which is what
+     * runs under Node's type stripping with no build step.
+     */
+    readonly importExt?: 'js' | 'ts';
+    /**
+     * Whether the file being generated reads each half of a `$ref`'s import — the
+     * type, the validator, or both.
+     *
+     * The two halves come apart in both directions. A `$ref` in a position the type
+     * generator does not read (an `if` arm, whose whole node it types `unknown`) is
+     * called and never named; one in a position only the *type* reads (a tuple's
+     * rest, taken from `additionalItems`) is named and never called; and a ref
+     * inside a branch that folded away is neither. Importing a half nothing reads
+     * leaves it unused, which is `TS6133` in the generated file for any consumer
+     * with `noUnusedLocals` — this repo, and anything inheriting its flags.
+     *
+     * Defaults to "both", which is what every caller wanted before anyone asked the
+     * question.
+     */
+    readonly reads?: (names: {
+        readonly typeName: string;
+        readonly validatorName: string;
+        readonly checkerName: string;
+        readonly coercerName: string;
+        readonly repairerName: string;
+    }) => {
+        readonly type: boolean;
+        readonly validator: boolean;
+        /**
+         * The `$ref` target's fail-fast validator. Only a file generated with the
+         * check half on names it, and then only from inside its own `checkX` — the
+         * accumulating body still calls `validateX`, so the two halves of one import
+         * come apart exactly like the coercing and repairing ones do.
+         */
+        readonly checker?: boolean;
+        /**
+         * The `$ref` target's value-coercing walk. Only a file generated with
+         * coercion on names it, and even then only where the ref sits somewhere the
+         * coercion pass walks — so it comes apart from the other two halves the same
+         * way they come apart from each other.
+         */
+        readonly coercer?: boolean;
+        /**
+         * The `$ref` target's position lookup, which answers what a repair at some
+         * position under it repairs to. Only a file generated with repair on names
+         * it, and a repairing file always coerces too — so this half never appears
+         * without {@link coercer}, though the reverse is ordinary.
+         */
+        readonly repairer?: boolean;
+    };
+};
+/**
+ * Collects import statements for all $ref dependencies of a schema.
+ * Each import brings in both the generated TypeScript type and validator function.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { contact: { $ref: '#/$defs/contact' } } }
+ * collectValidatorImports(schema)
+ * // ["import { type Contact, validateContact } from './contact'"]
+ * ```
+ */
+export declare const collectValidatorImports: (schema: JSONSchema, options?: CollectValidatorImportsOptions) => string[];
+export {};

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

@@ -0,0 +1,62 @@
+import { refToFilename } from "@amritk/helpers/ref-to-filename";
+import { refToName } from "@amritk/helpers/ref-to-name";
+import { resolveRef } from "@amritk/helpers/resolve-ref";
+import { collectEmittedRefs } from "./collect-emitted-refs.js";
+const buildImport = (ref, suffix, reads, importExt) => {
+  const filename = refToFilename(ref);
+  const typeName = refToName(ref, suffix);
+  const validatorName = `validate${typeName}`;
+  const checkerName = `check${typeName}`;
+  const coercerName = `coerce${typeName}Value`;
+  const repairerName = `repair${typeName}At`;
+  const { type, validator, checker = false, coercer = false, repairer = false } = reads({
+    typeName,
+    validatorName,
+    checkerName,
+    coercerName,
+    repairerName
+  });
+  const values = [
+    ...validator ? [validatorName] : [],
+    ...checker ? [checkerName] : [],
+    ...coercer ? [coercerName] : [],
+    ...repairer ? [repairerName] : []
+  ];
+  if (type && values.length > 0)
+    return `import { type ${typeName}, ${values.join(", ")} } from './${filename}.${importExt}'`;
+  if (values.length > 0)
+    return `import { ${values.join(", ")} } from './${filename}.${importExt}'`;
+  if (type)
+    return `import type { ${typeName} } from './${filename}.${importExt}'`;
+  return null;
+};
+const collectValidatorImports = (schema, options) => {
+  const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
+  const rootSchema = options?.rootSchema;
+  const typeSuffix = options?.typeSuffix ?? "";
+  const reads = options?.reads ?? (() => ({ type: true, validator: true }));
+  const importExt = options?.importExt ?? "js";
+  const refs = collectEmittedRefs(schema, [], rootSchema, true);
+  const seen = /* @__PURE__ */ new Set();
+  const imports = [];
+  for (const ref of refs) {
+    const filename = refToFilename(ref);
+    if (seen.has(filename))
+      continue;
+    if (selfFilename && filename === selfFilename)
+      continue;
+    if (rootSchema) {
+      const resolved = resolveRef(ref, rootSchema);
+      if (!resolved)
+        continue;
+    }
+    const statement = buildImport(ref, typeSuffix, reads, importExt);
+    seen.add(filename);
+    if (statement !== null)
+      imports.push(statement);
+  }
+  return imports;
+};
+export {
+  collectValidatorImports
+};

package/dist/validators/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/validators/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/validators/generators/enforced-keywords.d.ts

@@ -0,0 +1,33 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Every keyword this generator turns into a runtime check. Annotations
+ * (`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>;
+/**
+ * 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[], 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;