schema-components 1.18.1 → 1.20.0

package/dist/core/adapter.d.mts

@@ -1,5 +1,5 @@
-import { T as SchemaMeta, m as JsonObject } from "../types-D_5ST7SS.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { T as SchemaMeta, m as JsonObject } from "../types-C9zw9wbX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
 
 //#region src/core/adapter.d.ts
 type SchemaInput = Record<string, unknown>;

package/dist/core/adapter.mjs

@@ -1,8 +1,9 @@
 import { getProperty, hasProperty, isObject } from "./guards.mjs";
+import { SchemaNormalisationError } from "./errors.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { dereference } from "./ref.mjs";
-import { detectJsonSchemaDraft, detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2 } from "./version.mjs";
-import { i as normaliseOpenApiSchemas, r as normaliseJsonSchema$1 } from "../normalise-tL9FckAk.mjs";
+import { detectOpenApiVersion, inferJsonSchemaDraftWithReason, isSwagger2, matchJsonSchemaDraftUri } from "./version.mjs";
+import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema$1 } from "../normalise-CMMEl4cd.mjs";
 import { z } from "zod";
 //#region src/core/adapter.ts
 /**
@@ -30,9 +31,105 @@ function detectSchemaKind(input) {
 * but TypeScript cannot represent "has _zod.def" as the $ZodType parameter
 * that z.toJSONSchema expects. This is the library boundary equivalent of
 * object → Record<string, unknown> — the type mismatch is genuinely unavoidable.
+*
+* Any exception thrown by z.toJSONSchema is classified into a
+* SchemaNormalisationError so the caller does not have to re-parse error
+* message strings. The classification covers:
+*
+* - Nested Zod 3 schemas inside a Zod 4 tree (which surface as
+*   "Cannot read properties of undefined (reading 'def')") → zod3-unsupported
+* - Transforms ("Transforms cannot be represented") → zod-transform-unsupported
+* - Dynamic catch values whose handler throws ("Dynamic catch values are not
+*   supported") → zod-type-unrepresentable with zodType "dynamic-catch"
+* - Unrepresentable types — bigint, date, map, set, symbol, function, custom,
+*   undefined, void, NaN, and the literal-only forms `z.literal(undefined)`
+*   ("undefined-literal") and `z.literal(<bigint>)` ("bigint-literal") →
+*   zod-type-unrepresentable
+* - The catch-all "Non-representable type encountered: <type>" fallback Zod
+*   emits for any new schema kind without a registered processor →
+*   zod-type-unrepresentable with zodType set to the offending def.type
+* - Anything else → zod-conversion-failed
+*
+* The original error is preserved on each classified error via the `cause`
+* field so consumers can still inspect the Zod stack trace.
 */
 function callToJsonSchema(schema) {
-	return z.toJSONSchema(schema);
+	try {
+		return z.toJSONSchema(schema);
+	} catch (err) {
+		throw classifyZodConversionError(err, schema);
+	}
+}
+/**
+* Error messages emitted by Zod 4's z.toJSONSchema for unrepresentable types.
+* Mapping is exact-prefix on the message and the corresponding Zod type name
+* surfaced to the consumer via SchemaNormalisationError.zodType.
+*
+* Sources (verbatim message prefixes):
+* - zod/src/v4/core/json-schema-processors.ts L104 (bigint), L110 (symbol),
+*   L126 (undefined), L132 (void), L150 (date), L169 (literal-undefined),
+*   L175 (literal-bigint), L204 (NaN), L246 (custom), L252 (function),
+*   L264 (map), L270 (set), L521 (dynamic catch).
+* - zod/src/v4/core/to-json-schema.ts L182 (non-representable type fallback).
+*
+* The kept message prefix is the shortest substring that uniquely identifies
+* the source — the test in tests/zod-error-wording-contract.unit.test.ts
+* asserts each prefix is still present in the live Zod output so a Zod
+* patch upgrade that changes wording fails the build.
+*
+* Note: the more specific literal-* prefixes precede the generic "BigInt"
+* prefix so the literal classifications win. JavaScript object iteration
+* order preserves insertion order, and the loop short-circuits on first
+* match, so ordering here is load-bearing.
+*/
+const UNREPRESENTABLE_ZOD_TYPES = [
+	["Literal `undefined` cannot be represented", "undefined-literal"],
+	["BigInt literals cannot be represented", "bigint-literal"],
+	["BigInt cannot be represented", "bigint"],
+	["Date cannot be represented", "date"],
+	["Map cannot be represented", "map"],
+	["Set cannot be represented", "set"],
+	["Symbols cannot be represented", "symbol"],
+	["Function types cannot be represented", "function"],
+	["Custom types cannot be represented", "custom"],
+	["Undefined cannot be represented", "undefined"],
+	["Void cannot be represented", "void"],
+	["NaN cannot be represented", "nan"]
+];
+/**
+* Marker for Zod's catch-all message when a brand-new schema type has no
+* registered processor (e.g. ahead of a Zod patch adding a new schema kind).
+*
+* Source: zod/src/v4/core/to-json-schema.ts L182
+*   `[toJSONSchema]: Non-representable type encountered: ${def.type}`
+*/
+const NON_REPRESENTABLE_TYPE_MARKER = "[toJSONSchema]: Non-representable type encountered:";
+/**
+* Marker for dynamic catch failures — Zod throws when `def.catchValue(...)`
+* itself throws while building the JSON Schema default.
+*
+* Source: zod/src/v4/core/json-schema-processors.ts L521
+*/
+const DYNAMIC_CATCH_MARKER = "Dynamic catch values are not supported";
+/**
+* The cryptic error produced when z.toJSONSchema encounters a nested Zod 3
+* schema (one without `_zod.def`). Reproduced verbatim from Node's TypeError
+* for property access on undefined.
+*/
+const NESTED_ZOD3_MARKER = "Cannot read properties of undefined";
+function classifyZodConversionError(err, schema) {
+	const message = err instanceof Error ? err.message : String(err);
+	if (message.includes(NESTED_ZOD3_MARKER)) return new SchemaNormalisationError("A nested Zod 3 schema was found inside a Zod 4 schema. schema-components requires Zod 4 throughout the schema tree. See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", schema, "zod3-unsupported", void 0, err);
+	if (message.includes("Transforms cannot be represented")) return new SchemaNormalisationError("Zod transforms cannot be represented in JSON Schema. Remove the .transform() call, or pre-transform the input before passing it to the component.", schema, "zod-transform-unsupported", void 0, err);
+	if (message.includes(DYNAMIC_CATCH_MARKER)) return new SchemaNormalisationError("Zod catch values that depend on runtime computation cannot be represented in JSON Schema. Provide a static catch value or remove the .catch() call.", schema, "zod-type-unrepresentable", "dynamic-catch", err);
+	for (const [prefix, typeName] of UNREPRESENTABLE_ZOD_TYPES) if (message.includes(prefix)) return new SchemaNormalisationError(`Zod type ${typeName} cannot be represented in JSON Schema and is not supported by schema-components. Original message: ${message}`, schema, "zod-type-unrepresentable", typeName, err);
+	const nonReprIndex = message.indexOf(NON_REPRESENTABLE_TYPE_MARKER);
+	if (nonReprIndex !== -1) {
+		const trailing = message.slice(nonReprIndex + 51).trim();
+		const typeName = trailing.length > 0 ? trailing.split(/\s+/)[0] : void 0;
+		return new SchemaNormalisationError(`Zod encountered a schema kind${typeName !== void 0 ? ` "${typeName}"` : ""} with no JSON Schema processor registered. This usually means Zod added a new schema type that schema-components does not yet support. Original message: ${message}`, schema, "zod-type-unrepresentable", typeName, err);
+	}
+	return new SchemaNormalisationError(`z.toJSONSchema() failed: ${message}`, schema, "zod-conversion-failed", void 0, err);
 }
 function normaliseSchema(input, ref, options) {
 	if (ref === void 0 && isObject(input)) {
@@ -46,14 +143,14 @@ function normaliseSchema(input, ref, options) {
 			result = normaliseZod4(input);
 			break;
 		case "zod3":
-			result = normaliseZod3();
+			result = normaliseZod3(input);
 			break;
 		case "openapi":
-			if (!isObject(input)) throw new Error("Invalid OpenAPI document");
+			if (!isObject(input)) throw new SchemaNormalisationError("Invalid OpenAPI document", input, "openapi-invalid");
 			result = normaliseOpenApi(input, ref, options);
 			break;
 		case "jsonSchema":
-			if (!isObject(input)) throw new Error("Invalid JSON Schema");
+			if (!isObject(input)) throw new SchemaNormalisationError("Invalid JSON Schema", input, "invalid-json-schema");
 			result = normaliseJsonSchema(input, options?.diagnostics);
 			break;
 	}
@@ -62,10 +159,10 @@ function normaliseSchema(input, ref, options) {
 }
 function normaliseZod4(input) {
 	const zod = getProperty(input, "_zod");
-	if (!isObject(zod)) throw new Error("Invalid Zod 4 schema: missing _zod property");
-	if (!("def" in zod)) throw new Error("Invalid Zod 4 schema: missing _zod.def");
+	if (!isObject(zod)) throw new SchemaNormalisationError("Invalid Zod 4 schema: missing _zod property", input, "invalid-zod");
+	if (!("def" in zod)) throw new SchemaNormalisationError("Invalid Zod 4 schema: missing _zod.def", input, "invalid-zod");
 	const jsonSchema = callToJsonSchema(input);
-	if (!isObject(jsonSchema)) throw new Error("z.toJSONSchema() did not produce an object");
+	if (!isObject(jsonSchema)) throw new SchemaNormalisationError("z.toJSONSchema() did not produce an object", input, "invalid-zod");
 	return {
 		jsonSchema,
 		zodSchema: input,
@@ -75,7 +172,8 @@ function normaliseZod4(input) {
 }
 function normaliseJsonSchema(jsonSchema, diagnostics) {
 	let draft;
-	if (typeof jsonSchema.$schema !== "string") {
+	const $schema = jsonSchema.$schema;
+	if (typeof $schema !== "string") {
 		const inferred = inferJsonSchemaDraftWithReason(jsonSchema);
 		draft = inferred.draft;
 		emitDiagnostic(diagnostics, {
@@ -87,16 +185,31 @@ function normaliseJsonSchema(jsonSchema, diagnostics) {
 				draft: inferred.draft
 			}
 		});
-	} else draft = detectJsonSchemaDraft(jsonSchema);
-	const normalised = normaliseJsonSchema$1(jsonSchema, draft);
+	} else {
+		const matched = matchJsonSchemaDraftUri($schema);
+		if (matched === void 0) {
+			draft = "draft-2020-12";
+			emitDiagnostic(diagnostics, {
+				code: "assumed-draft",
+				message: `Unknown $schema URI "${$schema}"; assuming draft-2020-12`,
+				pointer: "",
+				detail: {
+					inferredFrom: "unknown-uri",
+					draft,
+					uri: $schema
+				}
+			});
+		} else draft = matched;
+	}
+	const normalised = normaliseJsonSchema$1(jsonSchema, draft, diagnostics);
 	return {
 		jsonSchema: normalised,
 		rootMeta: extractRootMetaFromJson(normalised),
 		rootDocument: normalised
 	};
 }
-function normaliseZod3() {
-	throw new Error("Zod 3 schemas are not supported. schema-components requires Zod 4. Detected: Zod 3 (has _def without _zod). See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4");
+function normaliseZod3(input) {
+	throw new SchemaNormalisationError("Zod 3 schemas are not supported. schema-components requires Zod 4. Detected: Zod 3 (has _def without _zod). See the Zod 4 migration guide at https://zod.dev/v4/migration or run: pnpm add zod@^4", input, "zod3-unsupported");
 }
 /**
 * Mapping of Swagger 2.0 $ref prefixes to their OpenAPI 3.x equivalents.
@@ -143,7 +256,7 @@ function resolveOpenApiRef(doc, ref) {
 		if (!isObject(resolved)) throw new Error(`OpenAPI ref not found: ${ref}`);
 		return resolved;
 	}
-	const pathMatch = /^\/(.+)\/(get|post|put|patch|delete)$/.exec(ref);
+	const pathMatch = /^\/(.+)\/(get|post|put|patch|delete|head|options|trace)$/.exec(ref);
 	if (pathMatch?.[1] !== void 0 && pathMatch[2] !== void 0) {
 		const pathStr = pathMatch[1];
 		const method = pathMatch[2];

package/dist/core/constraints.d.mts

@@ -1,5 +1,5 @@
-import { D as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-D_5ST7SS.mjs";
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { D as StringConstraints, f as FileConstraints, t as ArrayConstraints, x as ObjectConstraints, y as NumberConstraints } from "../types-C9zw9wbX.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
 
 //#region src/core/constraints.d.ts
 declare function extractStringConstraints(schema: Record<string, unknown>, diagnostics?: DiagnosticsOptions, pointer?: string): StringConstraints;

package/dist/core/diagnostics.d.mts

@@ -1,2 +1,2 @@
-import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-BYk63jsC.mjs";
+import { a as appendPointer, i as DiagnosticsOptions, n as DiagnosticCode, o as emitDiagnostic, r as DiagnosticSink, t as Diagnostic } from "../diagnostics-CbBPsxSt.mjs";
 export { Diagnostic, DiagnosticCode, DiagnosticSink, DiagnosticsOptions, appendPointer, emitDiagnostic };

package/dist/core/errors.d.mts

@@ -1,2 +1,2 @@
-import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-C5zRC2PU.mjs";
+import { i as SchemaRenderError, n as SchemaFieldError, r as SchemaNormalisationError, t as SchemaError } from "../errors-C2iABcn9.mjs";
 export { SchemaError, SchemaFieldError, SchemaNormalisationError, SchemaRenderError };

package/dist/core/errors.mjs

@@ -32,10 +32,24 @@ var SchemaError = class extends Error {
 */
 var SchemaNormalisationError = class extends SchemaError {
 	kind;
-	constructor(message, schema, kind) {
+	/**
+	* For `zod-type-unrepresentable`, the offending Zod type name
+	* (e.g. "bigint", "date", "map", "set"). `undefined` for other kinds.
+	*/
+	zodType;
+	/**
+	* The original underlying error, when this normalisation error wraps
+	* another exception (typically the error thrown by `z.toJSONSchema()`).
+	* Preserves the source stack trace so the root cause is not lost when
+	* the classifier translates the message.
+	*/
+	cause;
+	constructor(message, schema, kind, zodType, cause) {
 		super(message, schema);
 		this.name = "SchemaNormalisationError";
 		this.kind = kind;
+		this.zodType = zodType;
+		this.cause = cause;
 	}
 };
 /**

package/dist/core/fieldOrder.d.mts

@@ -1,4 +1,4 @@
-import { M as WalkedField } from "../types-D_5ST7SS.mjs";
+import { M as WalkedField } from "../types-C9zw9wbX.mjs";
 
 //#region src/core/fieldOrder.d.ts
 /**

package/dist/core/formats.d.mts

@@ -1,18 +1,14 @@
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+
 //#region src/core/formats.d.ts
 /**
- * Built-in format patterns for JSON Schema string validation.
- *
- * Maps standard JSON Schema/OpenAPI `format` values to RegExp patterns
- * or predicate validators. Used by the constraint extractor to derive
- * `formatPattern` alongside the existing `format` string, and by the
- * `validate` helper for runtime format checking.
- *
- * Formats that cannot be validated by regex (iri, regex) use predicate
- * functions instead. `validateFormat` dispatches to whichever is available.
- *
- * The user's explicit `pattern` constraint always takes precedence —
- * `formatPattern` is exposed as a separate field for renderers.
+ * Maximum length of a string that will be compiled by `new RegExp(...)`.
+ * Patterns that exceed this cap are rejected without compilation. A
+ * pathological pattern (e.g. `(a+)+`) doesn't need to be long to hang,
+ * but the cap is cheap defence and stops obviously hostile input before
+ * it reaches the regex engine.
  */
+declare const MAX_REGEX_PATTERN_LENGTH = 500;
 /**
  * A format validator: either a RegExp pattern or a predicate function.
  */
@@ -21,13 +17,24 @@ type FormatValidator = RegExp | ((value: string) => boolean);
  * Recognised JSON Schema formats with their validation patterns.
  * Unknown formats emit an `unknown-format` diagnostic and skip derivation.
  */
+/**
+ * Email format pattern, exported as a named const so callers that need a
+ * guaranteed `RegExp` (rather than the `RegExp | undefined` shape of
+ * `FORMAT_PATTERNS[name]` under `noUncheckedIndexedAccess`) can import it
+ * directly. Used by the URI safety helpers for mailto address checks.
+ */
+declare const EMAIL_FORMAT_PATTERN: RegExp;
 declare const FORMAT_PATTERNS: Readonly<Record<string, RegExp>>;
 /**
  * Validate a string value against format constraints.
  * Returns `true` when the value matches the format,
  * `false` when it does not, and `undefined` when the format
  * is not recognised (no validator available).
+ *
+ * `diagnostics` and `pointer` are forwarded to validators that can
+ * surface structured diagnostics — currently the `regex` format, which
+ * emits `pattern-invalid` for over-length or malformed input.
  */
-declare function validateFormat(value: string, format: string): boolean | undefined;
+declare function validateFormat(value: string, format: string, diagnostics?: DiagnosticsOptions, pointer?: string): boolean | undefined;
 //#endregion
-export { FORMAT_PATTERNS, FormatValidator, validateFormat };
+export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, FormatValidator, MAX_REGEX_PATTERN_LENGTH, validateFormat };

package/dist/core/formats.mjs

@@ -1,11 +1,27 @@
+import { emitDiagnostic } from "./diagnostics.mjs";
 //#region src/core/formats.ts
 /**
+* Maximum length of a string that will be compiled by `new RegExp(...)`.
+* Patterns that exceed this cap are rejected without compilation. A
+* pathological pattern (e.g. `(a+)+`) doesn't need to be long to hang,
+* but the cap is cheap defence and stops obviously hostile input before
+* it reaches the regex engine.
+*/
+const MAX_REGEX_PATTERN_LENGTH = 500;
+/**
 * Recognised JSON Schema formats with their validation patterns.
 * Unknown formats emit an `unknown-format` diagnostic and skip derivation.
 */
+/**
+* Email format pattern, exported as a named const so callers that need a
+* guaranteed `RegExp` (rather than the `RegExp | undefined` shape of
+* `FORMAT_PATTERNS[name]` under `noUncheckedIndexedAccess`) can import it
+* directly. Used by the URI safety helpers for mailto address checks.
+*/
+const EMAIL_FORMAT_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 const FORMAT_PATTERNS = {
 	uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
-	email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+	email: EMAIL_FORMAT_PATTERN,
 	"date-time": /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/,
 	date: /^\d{4}-\d{2}-\d{2}$/,
 	time: /^\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?$/,
@@ -19,11 +35,30 @@ const FORMAT_PATTERNS = {
 	"relative-json-pointer": /^(0|[1-9][0-9]*)(#?([/]([^/~]|~0|~1)*)*)?$/,
 	duration: /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/,
 	"idn-email": /^[^\s@]+@[^\s@]+\.[^\s@]+$/u,
-	"idn-hostname": /^[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?(\.[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?)*$/iu
+	"idn-hostname": /^[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?(\.[a-z0-9\u00a1-\uffff]([a-z0-9\u00a1-\uffff-]{0,61}[a-z0-9\u00a1-\uffff])?)*$/iu,
+	cuid: /^[cC][0-9a-z]{6,}$/,
+	cuid2: /^[0-9a-z]+$/,
+	nanoid: /^[a-zA-Z0-9_-]{21}$/,
+	cidrv4: /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/,
+	cidrv6: /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$/,
+	base64: /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/,
+	base64url: /^[A-Za-z0-9_-]*$/,
+	e164: /^\+[1-9]\d{6,14}$/,
+	emoji: /^(\p{Extended_Pictographic}|\p{Emoji_Component})+$/u,
+	ulid: /^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$/,
+	xid: /^[0-9a-vA-V]{20}$/,
+	ksuid: /^[A-Za-z0-9]{27}$/,
+	lowercase: /^[^A-Z]*$/,
+	uppercase: /^[^a-z]*$/,
+	jwt: /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/
 };
 /**
 * Format validators that use predicate functions instead of regex.
 * These are checked in `validateFormat` when no regex pattern exists.
+*
+* The `regex` format is intentionally absent here — it requires a
+* length cap and structured diagnostic emission and is handled via
+* {@link validateRegexFormat} directly from {@link validateFormat}.
 */
 const PREDICATE_VALIDATORS = {
 	iri: (value) => {
@@ -49,19 +84,76 @@ const PREDICATE_VALIDATORS = {
 		} catch {
 			return false;
 		}
+	},
+	"json-string": (value) => {
+		try {
+			JSON.parse(value);
+			return true;
+		} catch {
+			return false;
+		}
 	}
 };
 /**
+* Validate that a string is a syntactically valid regular expression.
+*
+* Hardened against ReDoS-style abuse:
+* - Values longer than {@link MAX_REGEX_PATTERN_LENGTH} are treated as
+*   "format unmatched" without ever being compiled.
+* - Any `SyntaxError` thrown by `new RegExp(...)` (malformed pattern,
+*   invalid flags, unbalanced groups) is caught and treated as "format
+*   unmatched".
+*
+* In both cases a diagnostic is emitted when a sink is supplied so
+* callers can surface the offending value to the schema author.
+*/
+function validateRegexFormat(value, diagnostics, pointer) {
+	if (value.length > 500) {
+		emitDiagnostic(diagnostics, {
+			code: "pattern-invalid",
+			message: `Pattern length (${String(value.length)}) exceeds maximum (${String(500)}); treating as unmatched`,
+			pointer,
+			detail: {
+				reason: "length-exceeded",
+				length: value.length,
+				maxLength: 500
+			}
+		});
+		return false;
+	}
+	try {
+		new RegExp(value);
+		return true;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		emitDiagnostic(diagnostics, {
+			code: "pattern-invalid",
+			message: `Failed to compile pattern as RegExp: ${message}; treating as unmatched`,
+			pointer,
+			detail: {
+				reason: "compile-error",
+				error: message
+			}
+		});
+		return false;
+	}
+}
+/**
 * Validate a string value against format constraints.
 * Returns `true` when the value matches the format,
 * `false` when it does not, and `undefined` when the format
 * is not recognised (no validator available).
+*
+* `diagnostics` and `pointer` are forwarded to validators that can
+* surface structured diagnostics — currently the `regex` format, which
+* emits `pattern-invalid` for over-length or malformed input.
 */
-function validateFormat(value, format) {
+function validateFormat(value, format, diagnostics, pointer = "") {
 	const pattern = FORMAT_PATTERNS[format];
 	if (pattern !== void 0) return pattern.test(value);
+	if (format === "regex") return validateRegexFormat(value, diagnostics, pointer);
 	const predicate = PREDICATE_VALIDATORS[format];
 	if (predicate !== void 0) return predicate(value);
 }
 //#endregion
-export { FORMAT_PATTERNS, validateFormat };
+export { EMAIL_FORMAT_PATTERN, FORMAT_PATTERNS, MAX_REGEX_PATTERN_LENGTH, validateFormat };

package/dist/core/merge.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
 
 //#region src/core/merge.d.ts
 /**

package/dist/core/normalise.d.mts

@@ -1,5 +1,5 @@
-import { i as DiagnosticsOptions } from "../diagnostics-BYk63jsC.mjs";
-import { n as JsonSchemaDraft, r as OpenApiVersionInfo } from "../version-B5NV-35j.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-CbBPsxSt.mjs";
+import { i as OpenApiVersionInfo, r as JsonSchemaDraft } from "../version-D-u7aMfy.mjs";
 
 //#region src/core/normalise.d.ts
 type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
@@ -8,9 +8,32 @@ type NodeTransform = (node: Record<string, unknown>) => Record<string, unknown>;
  * and recursing into every sub-schema location.
  */
 declare function deepNormalise(schema: Record<string, unknown>, transform: NodeTransform): Record<string, unknown>;
+/**
+ * Per-node context threaded through `deepNormaliseWithContext`.
+ *
+ * Carries the diagnostics sink and the JSON Pointer to the current
+ * node so per-node transforms can emit pointer-accurate diagnostics
+ * when they translate or reject legacy constructs.
+ */
+interface NodeContext {
+  diagnostics: DiagnosticsOptions | undefined;
+  pointer: string;
+}
+type NodeTransformWithContext = (node: Record<string, unknown>, ctx: NodeContext) => Record<string, unknown>;
+/**
+ * Deep-normalise a JSON Schema object, threading a context (diagnostics
+ * sink + JSON Pointer) through each recursive call. Used by the JSON
+ * Schema normalisation path so per-node transforms can emit diagnostics
+ * with accurate pointers.
+ *
+ * Mirrors `deepNormalise` structurally — keep the two in sync when
+ * adding new sub-schema locations.
+ */
+declare function deepNormaliseWithContext(schema: Record<string, unknown>, transform: NodeTransformWithContext, ctx: NodeContext): Record<string, unknown>;
 /**
  * Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
- * to number form.
+ * to number form, plus the other Draft 04 translations applied to a
+ * single node.
  *
  * In Draft 04:
  * - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
@@ -22,13 +45,23 @@ declare function deepNormalise(schema: Record<string, unknown>, transform: NodeT
  *
  * The transform converts boolean form to number form so the walker can
  * treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+ *
+ * This function preserves the no-context signature for the OpenAPI 3.0
+ * and Swagger 2.0 normalisers that compose it directly. The JSON Schema
+ * normalisation path uses {@link normaliseDraft04NodeWithContext} via
+ * {@link deepNormaliseWithContext} to thread diagnostics.
  */
 declare function normaliseDraft04Node(node: Record<string, unknown>): Record<string, unknown>;
 /**
  * Normalise a JSON Schema to canonical Draft 2020-12 form.
  * Deep-clones the input — the original is never mutated.
+ *
+ * When `diagnostics` is supplied, per-node transforms emit diagnostics
+ * for legacy-keyword rewrites and invalid constructs (e.g. `divisibleBy`
+ * conflicts, non-string entries in a `dependentRequired` array, legacy
+ * `dependencies` reaching the 2020-12 path).
  */
-declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: JsonSchemaDraft): Record<string, unknown>;
+declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: JsonSchemaDraft, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 /**
  * Normalise an OpenAPI document's schemas for walker consumption.
  * Handles version-specific keyword transformations.
@@ -38,4 +71,4 @@ declare function normaliseJsonSchema(schema: Record<string, unknown>, draft: Jso
  */
 declare function normaliseOpenApiSchemas(doc: Record<string, unknown>, version: OpenApiVersionInfo, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 //#endregion
-export { NodeTransform, deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };
+export { NodeContext, NodeTransform, NodeTransformWithContext, deepNormalise, deepNormaliseWithContext, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/normalise.mjs

@@ -1,2 +1,2 @@
-import { i as normaliseOpenApiSchemas, n as normaliseDraft04Node, r as normaliseJsonSchema, t as deepNormalise } from "../normalise-tL9FckAk.mjs";
-export { deepNormalise, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };
+import { a as normaliseOpenApiSchemas, i as normaliseJsonSchema, n as deepNormaliseWithContext, r as normaliseDraft04Node, t as deepNormalise } from "../normalise-CMMEl4cd.mjs";
+export { deepNormalise, deepNormaliseWithContext, normaliseDraft04Node, normaliseJsonSchema, normaliseOpenApiSchemas };

package/dist/core/openapi30.d.mts

@@ -32,10 +32,39 @@ declare function normaliseOpenApi30Discriminator(node: Record<string, unknown>):
  */
 declare function normaliseOpenApi30Combined(node: Record<string, unknown>): Record<string, unknown>;
 /**
- * Deep-normalise all schemas in an OpenAPI 3.0.x document.
- * Walks components/schemas, path operations, parameters, request bodies,
- * and responses — applying `nullable` normalisation to each schema.
+ * Per-schema normaliser supplied by the caller. Given a Schema Object,
+ * returns the normalised (deep-cloned) Schema Object. The visitor is
+ * agnostic to which transforms run inside.
+ */
+type SchemaNormaliser = (schema: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Deep-clone the parent first, then patch back any keys whose values were
+ * rewritten by the visitor. This preserves immutability of the original
+ * document while keeping the visitor straightforward to write.
+ */
+/**
+ * Deep-normalise every Schema Object in an OpenAPI document.
+ *
+ * Walks: `paths.*` (operations + path-level parameters), `webhooks.*`
+ * (3.1), `components.schemas`, `components.parameters`,
+ * `components.responses`, `components.requestBodies`,
+ * `components.headers`, `components.callbacks`, `components.pathItems`
+ * (3.1). For each Schema-bearing location, applies the supplied
+ * `normaliseSchema` function.
+ *
+ * The walker is structural (it understands OAS document shapes) and
+ * delegates the per-schema transformation. For OAS 3.0 the caller
+ * passes a full Draft 04 + nullable + discriminator + example
+ * normaliser; for OAS 3.1 the caller passes a discriminator-only
+ * normaliser so the walker's discriminated-union detection sees the
+ * injected `const`s regardless of OAS minor version.
+ */
+declare function deepNormaliseOpenApiDoc(doc: Record<string, unknown>, normaliseSchema: SchemaNormaliser): Record<string, unknown>;
+/**
+ * Backwards-compatible wrapper retaining the historic `deepNormalise`
+ * signature used by callers in `normalise.ts`. Always applies the full
+ * 3.0 combined transform via `deepNormalise(schema, normaliseOpenApi30Combined)`.
  */
 declare function deepNormaliseOpenApi30Doc(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>): Record<string, unknown>;
 //#endregion
-export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };
+export { deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/openapi30.mjs

@@ -1,2 +1,2 @@
-import { c as normaliseOpenApi30Discriminator, l as normaliseOpenApi30Node, o as deepNormaliseOpenApi30Doc, s as normaliseOpenApi30Combined } from "../normalise-tL9FckAk.mjs";
-export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };
+import { c as deepNormaliseOpenApiDoc, d as normaliseOpenApi30Node, l as normaliseOpenApi30Combined, s as deepNormaliseOpenApi30Doc, u as normaliseOpenApi30Discriminator } from "../normalise-CMMEl4cd.mjs";
+export { deepNormaliseOpenApi30Doc, deepNormaliseOpenApiDoc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/ref.d.mts

@@ -1,2 +1,2 @@
-import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-Ckt5liZs.mjs";
+import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-C8JbwfiS.mjs";
 export { ExternalResolver, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/renderer.d.mts

@@ -1,2 +1,2 @@
-import { a as HtmlRenderProps, c as RenderFunction, d as getHtmlRenderFn, f as getRenderFunction, h as typeToKey, i as HtmlRenderFunction, l as RenderProps, m as mergeResolvers, n as BaseFieldProps, o as HtmlResolver, p as mergeHtmlResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as buildRenderProps } from "../renderer-BAGoX4AK.mjs";
+import { a as HtmlRenderProps, c as RenderFunction, d as getHtmlRenderFn, f as getRenderFunction, h as typeToKey, i as HtmlRenderFunction, l as RenderProps, m as mergeResolvers, n as BaseFieldProps, o as HtmlResolver, p as mergeHtmlResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as buildRenderProps } from "../renderer-SOIbJBtk.mjs";
 export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/renderer.mjs

@@ -33,6 +33,7 @@ const RESOLVER_KEYS = [
 	"string",
 	"number",
 	"boolean",
+	"null",
 	"enum",
 	"object",
 	"array",
@@ -45,17 +46,21 @@ const RESOLVER_KEYS = [
 	"recursive",
 	"literal",
 	"file",
+	"never",
 	"unknown"
 ];
 /**
 * Map a schema type to the resolver key that handles it.
-* `discriminatedUnion` → `union`. Unknown types → `unknown`.
+* Every WalkedField variant has a direct resolver key — exhaustive switch
+* ensures new variants surface as a type error rather than silently
+* falling through to "unknown".
 */
 function typeToKey(type) {
 	switch (type) {
 		case "string":
 		case "number":
 		case "boolean":
+		case "null":
 		case "enum":
 		case "object":
 		case "array":
@@ -68,8 +73,8 @@ function typeToKey(type) {
 		case "recursive":
 		case "literal":
 		case "file":
+		case "never":
 		case "unknown": return type;
-		default: return "unknown";
 	}
 }
 /**