@kubb/adapter-oas 5.0.0-beta.100 → 5.0.0-beta.102

package/dist/index.js

@@ -1,12 +1,12 @@
 import "./rolldown-runtime-C0LytTxp.js";
 import { ast, findCircularSchemas, narrowSchema } from "@kubb/ast";
 import { Diagnostics, createAdapter } from "@kubb/core";
-import path from "node:path";
 import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
 import { compileErrors, validate } from "@readme/openapi-parser";
 import { upgrade } from "@scalar/openapi-upgrader";
 import { bundle } from "api-ref-bundler";
-import { parse } from "yaml";
 import { childName, enumPropName, extractRefName, macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion, mergeAdjacentObjectsLazy } from "@kubb/kit";
 //#region src/constants.ts
 /**
@@ -105,7 +105,7 @@ const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
 */
 const enumDescriptionKeys = ["x-enumDescriptions", "x-enum-descriptions"];
 //#endregion
-//#region src/discriminator.ts
+//#region src/emit/discriminator/propagate.ts
 /**
 * Maps each child schema name to its discriminator patch data by scanning the given
 * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
@@ -181,42 +181,6 @@ function patchDiscriminatorNode(node, entry) {
 		properties: newProperties
 	};
 }
-/**
-* Creates a single-property object schema used as a discriminator literal.
-*
-* @example
-* ```ts
-* createDiscriminantNode({ propertyName: 'type', value: 'dog' })
-* // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
-* ```
-*/
-function createDiscriminantNode({ propertyName, value }) {
-	return ast.factory.createSchema({
-		type: "object",
-		primitive: "object",
-		properties: [ast.factory.createProperty({
-			name: propertyName,
-			schema: ast.factory.createSchema({
-				type: "enum",
-				primitive: "string",
-				enumValues: [value]
-			}),
-			required: true
-		})]
-	});
-}
-/**
-* Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
-*
-* @example
-* ```ts
-* findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
-* ```
-*/
-function findDiscriminator(mapping, ref) {
-	if (!mapping || !ref) return null;
-	return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null;
-}
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -345,7 +309,7 @@ async function read(path) {
 	return readFile(path, { encoding: "utf8" });
 }
 //#endregion
-//#region src/factory.ts
+//#region src/load/source.ts
 const urlRegExp = /^https?:\/+/i;
 async function readSource(sourcePath) {
 	if (urlRegExp.test(sourcePath)) {
@@ -356,12 +320,33 @@ async function readSource(sourcePath) {
 	}
 	return read(sourcePath);
 }
+/**
+* Reads and parses one source file or URL referenced during bundling: YAML/JSON is parsed into an
+* object, Markdown is returned as-is (bundled inline rather than dereferenced).
+*/
 async function resolveSource(sourcePath) {
 	const data = await readSource(sourcePath);
 	if (sourcePath.toLowerCase().endsWith(".md")) return data;
 	return parse(data);
 }
 /**
+* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* its parse error instead.
+*/
+async function assertInputExists(input) {
+	if (URL.canParse(input)) return;
+	if (!await exists(input)) throw new Diagnostics.Error({
+		code: Diagnostics.code.inputNotFound,
+		severity: "error",
+		message: `Cannot read the file set as \`input\` (or via \`kubb generate PATH\`): ${input}`,
+		help: "Check that the path exists and is readable, then set it as `input` or pass it as `kubb generate PATH`.",
+		location: { kind: "config" }
+	});
+}
+//#endregion
+//#region src/load/normalize.ts
+/**
 * Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
 *
 * External file schemas are hoisted into named `components.schemas` entries, so a property
@@ -426,21 +411,6 @@ async function parseFromConfig(source) {
 	return parseDocument(resolved);
 }
 /**
-* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
-* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
-* its parse error instead.
-*/
-async function assertInputExists(input) {
-	if (URL.canParse(input)) return;
-	if (!await exists(input)) throw new Diagnostics.Error({
-		code: Diagnostics.code.inputNotFound,
-		severity: "error",
-		message: `Cannot read the file set as \`input\` (or via \`kubb generate PATH\`): ${input}`,
-		help: "Check that the path exists and is readable, then set it as `input` or pass it as `kubb generate PATH`.",
-		location: { kind: "config" }
-	});
-}
-/**
 * Validates an OpenAPI document using `@readme/openapi-parser` with colorized error output.
 *
 * @example
@@ -517,135 +487,272 @@ const jsonMimeFragments = [
 function isJsonMimeType(mimeType) {
 	return jsonMimeFragments.some((fragment) => mimeType.includes(fragment));
 }
-//#endregion
-//#region src/refs.ts
-const _refCache = /* @__PURE__ */ new WeakMap();
 /**
-* Resolves a local JSON pointer reference from a document.
-*
-* Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
-* resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
-* build there is no sink to collect it, so it throws instead.
+* Picks a media-type entry from a `content` map: the first JSON-like media type, falling back to
+* the first declared one. Returns `false` when `content` has no entries.
 *
 * @example
 * ```ts
-* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
+* pickContentEntry({ 'application/xml': xmlEntry, 'application/json': jsonEntry })
+* // ['application/json', jsonEntry]
 * ```
 */
-function resolveRef(document, $ref) {
-	const origRef = $ref;
-	$ref = $ref.trim();
-	if ($ref === "") return null;
-	if (!$ref.startsWith("#")) return null;
-	$ref = globalThis.decodeURIComponent($ref.substring(1));
-	let docCache = _refCache.get(document);
-	if (!docCache) {
-		docCache = /* @__PURE__ */ new Map();
-		_refCache.set(document, docCache);
-	}
-	if (docCache.has($ref)) return docCache.get($ref);
-	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
-	if (!current) {
-		const diagnostic = {
-			code: Diagnostics.code.refNotFound,
-			severity: "error",
-			message: `Could not find a definition for ${origRef}.`,
-			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
-			location: {
-				kind: "schema",
-				pointer: origRef,
-				ref: origRef
-			}
-		};
-		if (!Diagnostics.report(diagnostic)) throw new Diagnostics.Error(diagnostic);
-		return null;
-	}
-	docCache.set($ref, current);
-	return current;
+function pickContentEntry(content) {
+	const mediaTypes = Object.keys(content);
+	const available = mediaTypes.find(isJsonMimeType) ?? mediaTypes[0];
+	return available ? [available, content[available]] : false;
 }
+//#endregion
+//#region src/model/components.ts
 /**
-* Resolves a `$ref` object while preserving the original `$ref` field on the result.
+* Extracts the inline schema from a media-type `content` map.
 *
-* Useful for parser flows that need both dereferenced fields and pointer
-* identity (for naming/import purposes). Non-reference values are returned as-is.
+* Prefers `preferredContentType` when given, otherwise uses the first key in the map.
+* Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
 *
 * @example
 * ```ts
-* dereferenceWithRef(document, { $ref: '#/components/schemas/Pet' })
-* // { $ref: '#/components/schemas/Pet', type: 'object', properties: { ... } }
+* extractSchemaFromContent(operation.content, 'application/json')
+* // SchemaObject | null
 * ```
 */
-function dereferenceWithRef(document, schema) {
-	if (isReference(schema)) return {
-		...schema,
-		...resolveRef(document, schema.$ref),
-		$ref: schema.$ref
-	};
-	return schema;
+function extractSchemaFromContent(content, preferredContentType) {
+	if (!content) return null;
+	const firstContentType = Object.keys(content)[0] ?? "application/json";
+	const schema = content[preferredContentType ?? firstContentType]?.schema;
+	if (isReference(schema)) return null;
+	return schema ?? null;
+}
+/**
+* Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
+*/
+function* collectRefs(schema) {
+	if (Array.isArray(schema)) {
+		for (const item of schema) yield* collectRefs(item);
+		return;
+	}
+	if (schema && typeof schema === "object") for (const key in schema) {
+		const value = schema[key];
+		if (!(key === "$ref" && typeof value === "string")) {
+			yield* collectRefs(value);
+			continue;
+		}
+		if (value.startsWith("#/components/schemas/")) {
+			const name = value.slice(21);
+			if (name) yield name;
+		}
+	}
 }
 /**
-* Resolves a `$ref` slot in place: when `container[key]` holds a `$ref`, replaces it with the
-* resolved value and returns that value. Returns `null` when the slot is empty, cannot be resolved,
-* or is still a `$ref` after resolving. A non-`$ref` value is returned untouched, without writing.
+* Returns a copy of `schemas` topologically sorted by `$ref` dependency.
+*
+* Referenced schemas appear before the schemas that depend on them, so code generators
+* can emit types in the correct order. Cycles are silently skipped.
 *
 * @example
 * ```ts
-* derefInPlace<ResponseObject>({ document, container: operation.schema.responses, key: '200' })
+* const sorted = sortSchemas({ Order: orderSchema, Pet: petSchema })
+* // Pet appears before Order when Order.$ref points at Pet
 * ```
 */
-function derefInPlace({ document, container, key }) {
-	const value = container[key];
-	if (!isReference(value)) return value ? value : null;
-	const resolved = resolveRef(document, value.$ref);
-	container[key] = resolved;
-	return resolved && !isReference(resolved) ? resolved : null;
+function sortSchemas(schemas) {
+	const deps = /* @__PURE__ */ new Map();
+	for (const [name, schema] of Object.entries(schemas)) deps.set(name, [...new Set(collectRefs(schema))]);
+	const sorted = [];
+	const visited = /* @__PURE__ */ new Set();
+	function visit(name, stack) {
+		if (visited.has(name) || stack.has(name)) return;
+		stack.add(name);
+		for (const child of deps.get(name) ?? []) if (deps.has(child)) visit(child, stack);
+		stack.delete(name);
+		visited.add(name);
+		sorted.push(name);
+	}
+	for (const name of Object.keys(schemas)) visit(name, /* @__PURE__ */ new Set());
+	const result = {};
+	for (const name of sorted) result[name] = schemas[name];
+	return result;
 }
-//#endregion
-//#region src/operation.ts
+const semanticSuffixes = {
+	schemas: "Schema",
+	responses: "Response",
+	requestBodies: "Request"
+};
 /**
-* Slugifies a path for the `operationId` fallback: non-alphanumerics collapse to single dashes,
-* with no leading or trailing dash.
+* Picks the collision suffix for one name-colliding schema: none when the name is unique,
+* a semantic suffix (`Schema`, `Response`, `Request`) when the collision spans sources, otherwise
+* a numeric suffix (`2`, `3`, …) for same-source collisions.
 */
-function slugify(value) {
-	return value.replace(/[^a-zA-Z0-9]/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "");
+function collisionSuffix({ isSingle, hasMultipleSources, source, index }) {
+	if (isSingle) return "";
+	if (hasMultipleSources) return semanticSuffixes[source];
+	if (index === 0) return "";
+	return String(index + 1);
 }
 /**
-* Returns the operation's `operationId`, falling back to `<method>_<slugified-path>` when absent.
+* Collects component schemas from one or more sources and resolves name collisions.
+*
+* Sources default to `['schemas', 'requestBodies', 'responses']`. Returned schemas are
+* topologically sorted by `$ref` dependency so generators emit types in the correct order.
+*
+* When two or more schemas normalize to the same PascalCase name:
+* - Same source → numeric suffix (`2`, `3`, …).
+* - Different sources → semantic suffix (`Schema`, `Response`, `Request`).
+*
+* @example
+* ```ts
+* const { schemas, renames } = getSchemas(document, { contentType: 'application/json' }, refs)
+* ```
 */
-function getOperationId({ path, method, schema }) {
-	const { operationId } = schema;
-	if (typeof operationId === "string" && operationId.length > 0) return operationId;
-	return `${method}_${slugify(path).toLowerCase()}`;
+function getSchemas(document, { contentType }, refs) {
+	const components = document.components;
+	function resolveSchemaRef(schema) {
+		if (!isReference(schema)) return schema;
+		const resolved = refs.resolve(schema.$ref);
+		return resolved && !isReference(resolved) ? resolved : schema;
+	}
+	const candidates = [...Object.entries(components?.schemas ?? {}).map(([name, schema]) => ({
+		schema: resolveSchemaRef(schema),
+		source: "schemas",
+		originalName: name
+	})), ...["responses", "requestBodies"].flatMap((source) => Object.entries(components?.[source] ?? {}).flatMap(([name, item]) => {
+		const schema = extractSchemaFromContent(item.content, contentType);
+		return schema ? [{
+			schema: resolveSchemaRef(schema),
+			source,
+			originalName: name
+		}] : [];
+	}))];
+	const normalizedNames = /* @__PURE__ */ new Map();
+	for (const item of candidates) {
+		const key = pascalCase(item.originalName);
+		const bucket = normalizedNames.get(key) ?? [];
+		bucket.push(item);
+		normalizedNames.set(key, bucket);
+	}
+	const schemas = {};
+	const renames = /* @__PURE__ */ new Map();
+	for (const [, items] of normalizedNames) {
+		const isSingle = items.length === 1;
+		const hasMultipleSources = !isSingle && new Set(items.map((item) => item.source)).size > 1;
+		items.forEach((item, index) => {
+			const suffix = collisionSuffix({
+				isSingle,
+				hasMultipleSources,
+				source: item.source,
+				index
+			});
+			const uniqueName = item.originalName + suffix;
+			schemas[uniqueName] = item.schema;
+			if (suffix) renames.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
+		});
+	}
+	return {
+		schemas: sortSchemas(schemas),
+		renames
+	};
 }
+//#endregion
+//#region src/model/server.ts
 /**
-* Returns the declared response status codes, skipping `x-` extensions and non-object entries.
+* Reads the server URL from the document's `servers` array at `server.index`,
+* interpolating any `server.variables` into the URL template.
+*
+* Returns `null` when `server.index` is omitted or out of range.
+*
+* @example Resolve the first server
+* `resolveBaseUrl({ document, server: { index: 0 } })`
+*
+* @example Override a path variable
+* `resolveBaseUrl({ document, server: { index: 0, variables: { version: 'v2' } } })`
 */
-function getResponseStatusCodes({ schema }) {
-	const responses = schema.responses;
-	if (!responses || isReference(responses)) return [];
-	return Object.keys(responses).filter((key) => !key.startsWith("x-") && !!responses[key] && typeof responses[key] === "object");
+function resolveBaseUrl({ document, server }) {
+	const index = server?.index;
+	const entry = index !== void 0 ? document.servers?.at(index) : void 0;
+	return entry?.url ? resolveServerUrl(entry, server?.variables) : null;
 }
 /**
-* Returns the response object for a status code, resolving a `$ref` in place. `false` when absent.
+* Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
+* Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
+* Throws if an override value is not in the variable's `enum` list.
+*
+* @example
+* ```ts
+* resolveServerUrl(
+*   { url: 'https://{env}.api.example.com', variables: { env: { default: 'dev', enum: ['dev', 'prod'] } } },
+*   { env: 'prod' },
+* )
+* // 'https://prod.api.example.com'
+* ```
 */
-function getResponseByStatusCode({ document, operation, statusCode }) {
-	const responses = operation.schema.responses;
+function resolveServerUrl(server, overrides) {
+	if (!server.variables) return server.url;
+	let url = server.url;
+	for (const [key, variable] of Object.entries(server.variables)) {
+		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
+		if (value === void 0) continue;
+		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Diagnostics.Error({
+			code: Diagnostics.code.invalidServerVariable,
+			severity: "error",
+			message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`,
+			help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
+			location: {
+				kind: "document",
+				pointer: "#/servers"
+			}
+		});
+		url = url.replaceAll(`{${key}}`, value);
+	}
+	return url;
+}
+//#endregion
+//#region src/operation.ts
+/**
+* Slugifies a path for the `operationId` fallback: non-alphanumerics collapse to single dashes,
+* with no leading or trailing dash.
+*/
+function slugify(value) {
+	return value.replace(/[^a-zA-Z0-9]/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "");
+}
+/**
+* Returns the operation's `operationId`, falling back to `<method>_<slugified-path>` when absent.
+*/
+function getOperationId({ path, method, schema }) {
+	const { operationId } = schema;
+	if (typeof operationId === "string" && operationId.length > 0) return operationId;
+	return `${method}_${slugify(path).toLowerCase()}`;
+}
+/**
+* Returns the declared response status codes, skipping `x-` extensions and non-object entries.
+*/
+function getResponseStatusCodes({ schema }) {
+	const responses = schema.responses;
+	if (!responses || isReference(responses)) return [];
+	return Object.keys(responses).filter((key) => !key.startsWith("x-") && !!responses[key] && typeof responses[key] === "object");
+}
+/**
+* Returns the response object for a status code, resolving a `$ref` through `refs`. `false` when absent.
+*/
+function getResponseByStatusCode({ operation, refs, statusCode }) {
+	const responses = operation.schema.responses;
 	if (!responses || isReference(responses)) return false;
-	return derefInPlace({
-		document,
-		container: responses,
-		key: statusCode
-	}) ?? false;
+	return refs.deref(responses[statusCode]) ?? false;
 }
 /**
-* Resolves the request body (dereferencing a `$ref` in place) and returns its content map, or
+* Resolves the operation's request body, dereferencing a `$ref` through `refs`. Returns `null`
+* when the operation has no request body or it cannot be resolved.
+*/
+function getRequestBody({ operation, refs }) {
+	return refs.deref(operation.schema.requestBody);
+}
+/**
+* Resolves the request body (a `$ref` through `refs`) and returns its content map, or
 * `undefined` when the operation has no request body.
 */
-function getRequestBodyContent({ document, operation }) {
-	return derefInPlace({
-		document,
-		container: operation.schema,
-		key: "requestBody"
+function getRequestBodyContent({ operation, refs }) {
+	return getRequestBody({
+		operation,
+		refs
 	})?.content;
 }
 /**
@@ -653,25 +760,23 @@ function getRequestBodyContent({ document, operation }) {
 * Otherwise picks the first JSON-like media type, then the first declared one, as a
 * `[mediaType, object]` tuple.
 */
-function getRequestContent({ document, operation, mediaType }) {
+function getRequestContent({ operation, refs, mediaType }) {
 	const content = getRequestBodyContent({
-		document,
-		operation
+		operation,
+		refs
 	});
 	if (!content) return false;
 	if (mediaType) return mediaType in content ? content[mediaType] : false;
-	const mediaTypes = Object.keys(content);
-	const available = mediaTypes.find((mt) => isJsonMimeType(mt)) ?? mediaTypes[0];
-	return available ? [available, content[available]] : false;
+	return pickContentEntry(content);
 }
 /**
 * Returns the primary request content type. Prefers a JSON-like media type (the last one wins
 * when several are declared), then the first declared one, defaulting to `'application/json'`.
 */
-function getRequestContentType({ document, operation }) {
+function getRequestContentType({ operation, refs }) {
 	const content = getRequestBodyContent({
-		document,
-		operation
+		operation,
+		refs
 	});
 	const mediaTypes = content ? Object.keys(content) : [];
 	let result = mediaTypes[0] ?? "application/json";
@@ -684,22 +789,18 @@ function getRequestContentType({ document, operation }) {
 *
 * @example
 * ```ts
-* for (const operation of getOperations(document)) {
+* for (const operation of getOperations(document, refs)) {
 *   parseOperation(options, operation)
 * }
 * ```
 */
-function getOperations(document) {
+function getOperations(document, refs) {
 	const operations = [];
 	const paths = document.paths;
 	if (!paths) return operations;
 	for (const path of Object.keys(paths)) {
 		if (path.startsWith("x-")) continue;
-		const pathItem = derefInPlace({
-			document,
-			container: paths,
-			key: path
-		});
+		const pathItem = refs.deref(paths[path]);
 		if (!pathItem) continue;
 		const item = pathItem;
 		for (const method of Object.keys(item)) {
@@ -709,65 +810,15 @@ function getOperations(document) {
 			operations.push({
 				path,
 				method,
-				schema
+				schema,
+				pathItem
 			});
 		}
 	}
 	return operations;
 }
 //#endregion
-//#region src/resolvers.ts
-/**
-* Reads the server URL from the document's `servers` array at `server.index`,
-* interpolating any `server.variables` into the URL template.
-*
-* Returns `null` when `server.index` is omitted or out of range.
-*
-* @example Resolve the first server
-* `resolveBaseUrl({ document, server: { index: 0 } })`
-*
-* @example Override a path variable
-* `resolveBaseUrl({ document, server: { index: 0, variables: { version: 'v2' } } })`
-*/
-function resolveBaseUrl({ document, server }) {
-	const index = server?.index;
-	const entry = index !== void 0 ? document.servers?.at(index) : void 0;
-	return entry?.url ? resolveServerUrl(entry, server?.variables) : null;
-}
-/**
-* Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
-* Resolution order: `overrides[key]` → `variable.default` → left unreplaced.
-* Throws if an override value is not in the variable's `enum` list.
-*
-* @example
-* ```ts
-* resolveServerUrl(
-*   { url: 'https://{env}.api.example.com', variables: { env: { default: 'dev', enum: ['dev', 'prod'] } } },
-*   { env: 'prod' },
-* )
-* // 'https://prod.api.example.com'
-* ```
-*/
-function resolveServerUrl(server, overrides) {
-	if (!server.variables) return server.url;
-	let url = server.url;
-	for (const [key, variable] of Object.entries(server.variables)) {
-		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
-		if (value === void 0) continue;
-		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Diagnostics.Error({
-			code: Diagnostics.code.invalidServerVariable,
-			severity: "error",
-			message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`,
-			help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
-			location: {
-				kind: "document",
-				pointer: "#/servers"
-			}
-		});
-		url = url.replaceAll(`{${key}}`, value);
-	}
-	return url;
-}
+//#region src/emit/schemaShape.ts
 /**
 * Returns the Kubb `SchemaType` for a given OAS `format` string, or `null` if not found.
 * Formats not in `formatMap` (e.g., `int64`, `date-time`) are handled separately by parser options.
@@ -794,96 +845,57 @@ function getPrimitiveType(type) {
 	return "string";
 }
 /**
-* Returns all parameters for an operation, merging path-level and operation-level entries.
-* Operation-level parameters override path-level ones with the same `in:name` key.
-* Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
-*
-* @example
-* ```ts
-* getParameters(document, operation)
-* // [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }]
-* ```
+* Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
+* Returns `null` when `dateType: false`, so the format falls through to `string`.
 */
-function getParameters(document, operation) {
-	const resolveParams = (params) => params.map((p) => dereferenceWithRef(document, p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
-	const operationParams = resolveParams(operation.schema?.parameters || []);
-	const pathItem = document.paths?.[operation.path];
-	const pathLevelParams = resolveParams(pathItem && !isReference(pathItem) && pathItem.parameters ? pathItem.parameters : []);
-	const paramMap = /* @__PURE__ */ new Map();
-	for (const p of pathLevelParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
-	for (const p of operationParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
-	return Array.from(paramMap.values());
-}
-function getResponseBody(responseBody, contentType) {
-	if (!responseBody) return false;
-	if (isReference(responseBody)) return false;
-	const body = responseBody;
-	if (!body.content) return false;
-	if (contentType) {
-		if (!(contentType in body.content)) return false;
-		return body.content[contentType];
+function getDateType(options, format) {
+	if (!options.dateType) return null;
+	if (format === "date-time") {
+		if (options.dateType === "date") return {
+			type: "date",
+			representation: "date"
+		};
+		if (options.dateType === "stringOffset") return {
+			type: "datetime",
+			offset: true
+		};
+		if (options.dateType === "stringLocal") return {
+			type: "datetime",
+			local: true
+		};
+		return {
+			type: "datetime",
+			offset: false
+		};
 	}
-	const contentTypes = Object.keys(body.content);
-	const availableContentType = contentTypes.find(isJsonMimeType) ?? contentTypes[0];
-	if (!availableContentType) return false;
-	return body.content[availableContentType];
-}
-function resolveResponseRefs(document, operation) {
-	const responses = operation.schema.responses;
-	if (!responses) return;
-	for (const key in responses) derefInPlace({
-		document,
-		container: responses,
-		key
-	});
+	if (format === "date") return {
+		type: "date",
+		representation: options.dateType === "date" ? "date" : "string"
+	};
+	return {
+		type: "time",
+		representation: options.dateType === "date" ? "date" : "string"
+	};
 }
 /**
-* Returns the response schema for a given operation and HTTP status code.
-*
-* Returns an empty object `{}` when no response body schema is available.
-*
-* @example
-* ```ts
-* getResponseSchema(document, operation, 200)         // SchemaObject
-* getResponseSchema(document, operation, '4XX')       // {}
-* ```
+* Reads a schema's numeric `exclusiveMinimum`/`exclusiveMaximum` bounds (the OAS 3.1 numeric
+* form). Either key is `undefined` when absent or, for the legacy OAS 3.0 boolean form, not a
+* number.
 */
-function getResponseSchema(document, operation, statusCode, options = {}) {
-	resolveResponseRefs(document, operation);
-	const responseBody = getResponseBody(getResponseByStatusCode({
-		document,
-		operation,
-		statusCode
-	}), options.contentType);
-	if (responseBody === false) return {};
-	const schema = responseBody.schema;
-	if (!schema) return {};
-	return dereferenceWithRef(document, schema);
+function getExclusiveBounds(schema) {
+	return {
+		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
+		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
+	};
 }
 /**
-* Returns the request body schema for an operation, or `null` when absent.
-*
-* @example
-* ```ts
-* getRequestSchema(document, operation) // SchemaObject | null
-* ```
+* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
+* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
+* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
 */
-function getRequestSchema(document, operation, options = {}) {
-	if (operation.schema.requestBody) operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody);
-	const requestBody = getRequestContent({
-		document,
-		operation,
-		mediaType: options.contentType
-	});
-	if (requestBody === false) return null;
-	const mediaType = Array.isArray(requestBody) ? requestBody[0] : options.contentType;
-	const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
-	if (mediaType === "application/octet-stream" && (!schema || Object.keys(schema).length === 0)) return {
-		type: "string",
-		contentMediaType: "application/octet-stream"
-	};
-	if (!schema) return null;
-	return dereferenceWithRef(document, schema);
+function extractExamples(schema) {
+	if (Array.isArray(schema.examples)) return schema.examples;
+	return schema.example !== void 0 ? [schema.example] : void 0;
 }
 /**
 * Returns `true` when `fragment` carries any JSON Schema keyword that makes it
@@ -892,8 +904,7 @@ function getRequestSchema(document, operation, options = {}) {
 * A fragment with a structural keyword can't be safely merged into a parent schema.
 */
 function hasStructuralKeywords(fragment) {
-	for (const key in fragment) if (structuralKeys.has(key)) return true;
-	return false;
+	return Object.keys(fragment).some((key) => structuralKeys.has(key));
 }
 /**
 * Flattens a keyword-only `allOf` into its parent schema.
@@ -924,192 +935,15 @@ function flattenSchema(schema) {
 	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) merged[key] ??= value;
 	return merged;
 }
+//#endregion
+//#region src/emit/createNode.ts
 /**
-* Extracts the inline schema from a media-type `content` map.
-*
-* Prefers `preferredContentType` when given, otherwise uses the first key in the map.
-* Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
-*
-* @example
-* ```ts
-* extractSchemaFromContent(operation.content, 'application/json')
-* // SchemaObject | null
-* ```
-*/
-function extractSchemaFromContent(content, preferredContentType) {
-	if (!content) return null;
-	const firstContentType = Object.keys(content)[0] ?? "application/json";
-	const schema = content[preferredContentType ?? firstContentType]?.schema;
-	if (schema && "$ref" in schema) return null;
-	return schema ?? null;
-}
-/**
-* Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
-*/
-function* collectRefs(schema) {
-	if (Array.isArray(schema)) {
-		for (const item of schema) yield* collectRefs(item);
-		return;
-	}
-	if (schema && typeof schema === "object") for (const key in schema) {
-		const value = schema[key];
-		if (!(key === "$ref" && typeof value === "string")) {
-			yield* collectRefs(value);
-			continue;
-		}
-		if (value.startsWith("#/components/schemas/")) {
-			const name = value.slice(21);
-			if (name) yield name;
-		}
-	}
-}
-/**
-* Returns a copy of `schemas` topologically sorted by `$ref` dependency.
-*
-* Referenced schemas appear before the schemas that depend on them, so code generators
-* can emit types in the correct order. Cycles are silently skipped.
-*
-* @example
-* ```ts
-* const sorted = sortSchemas({ Order: orderSchema, Pet: petSchema })
-* // Pet appears before Order when Order.$ref points at Pet
-* ```
-*/
-function sortSchemas(schemas) {
-	const deps = /* @__PURE__ */ new Map();
-	for (const [name, schema] of Object.entries(schemas)) deps.set(name, [...new Set(collectRefs(schema))]);
-	const sorted = [];
-	const visited = /* @__PURE__ */ new Set();
-	function visit(name, stack) {
-		if (visited.has(name) || stack.has(name)) return;
-		stack.add(name);
-		for (const child of deps.get(name) ?? []) if (deps.has(child)) visit(child, stack);
-		stack.delete(name);
-		visited.add(name);
-		sorted.push(name);
-	}
-	for (const name of Object.keys(schemas)) visit(name, /* @__PURE__ */ new Set());
-	const result = {};
-	for (const name of sorted) result[name] = schemas[name];
-	return result;
-}
-const semanticSuffixes = {
-	schemas: "Schema",
-	responses: "Response",
-	requestBodies: "Request"
-};
-function resolveSchemaRef(document, schema) {
-	if (!isReference(schema)) return schema;
-	const resolved = resolveRef(document, schema.$ref);
-	return resolved && !isReference(resolved) ? resolved : schema;
-}
-/**
-* Collects component schemas from one or more sources and resolves name collisions.
-*
-* Sources default to `['schemas', 'requestBodies', 'responses']`. Returned schemas are
-* topologically sorted by `$ref` dependency so generators emit types in the correct order.
-*
-* When two or more schemas normalize to the same PascalCase name:
-* - Same source → numeric suffix (`2`, `3`, …).
-* - Different sources → semantic suffix (`Schema`, `Response`, `Request`).
-*
-* @example
-* ```ts
-* const { schemas, renames } = getSchemas(document, { contentType: 'application/json' })
-* ```
-*/
-function getSchemas(document, { contentType }) {
-	const components = document.components;
-	const candidates = [...Object.entries(components?.schemas ?? {}).map(([name, schema]) => ({
-		schema: resolveSchemaRef(document, schema),
-		source: "schemas",
-		originalName: name
-	})), ...["responses", "requestBodies"].flatMap((source) => Object.entries(components?.[source] ?? {}).flatMap(([name, item]) => {
-		const schema = extractSchemaFromContent(item.content, contentType);
-		return schema ? [{
-			schema: resolveSchemaRef(document, schema),
-			source,
-			originalName: name
-		}] : [];
-	}))];
-	const normalizedNames = /* @__PURE__ */ new Map();
-	for (const item of candidates) {
-		const key = pascalCase(item.originalName);
-		const bucket = normalizedNames.get(key) ?? [];
-		bucket.push(item);
-		normalizedNames.set(key, bucket);
-	}
-	const schemas = {};
-	const renames = /* @__PURE__ */ new Map();
-	for (const [, items] of normalizedNames) {
-		const isSingle = items.length === 1;
-		let hasMultipleSources = false;
-		if (!isSingle) {
-			const firstSource = items[0].source;
-			for (const item of items) if (item.source !== firstSource) {
-				hasMultipleSources = true;
-				break;
-			}
-		}
-		items.forEach((item, index) => {
-			const suffix = isSingle ? "" : hasMultipleSources ? semanticSuffixes[item.source] : index === 0 ? "" : String(index + 1);
-			const uniqueName = item.originalName + suffix;
-			schemas[uniqueName] = item.schema;
-			if (suffix) renames.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
-		});
-	}
-	return {
-		schemas: sortSchemas(schemas),
-		renames
-	};
-}
-/**
-* Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
-* Returns `null` when `dateType: false`, so the format falls through to `string`.
-*/
-function getDateType(options, format) {
-	if (!options.dateType) return null;
-	if (format === "date-time") {
-		if (options.dateType === "date") return {
-			type: "date",
-			representation: "date"
-		};
-		if (options.dateType === "stringOffset") return {
-			type: "datetime",
-			offset: true
-		};
-		if (options.dateType === "stringLocal") return {
-			type: "datetime",
-			local: true
-		};
-		return {
-			type: "datetime",
-			offset: false
-		};
-	}
-	if (format === "date") return {
-		type: "date",
-		representation: options.dateType === "date" ? "date" : "string"
-	};
-	return {
-		type: "time",
-		representation: options.dateType === "date" ? "date" : "string"
-	};
-}
-/**
-* Collects the shared metadata fields passed to every `createSchema` call.
+* Builds a schema node from a converter's base context plus its type-specific fields. Every
+* converter needs the same metadata fields (`title`, `description`, `examples`, ...) alongside
+* whatever makes its node distinct; this folds both into one call.
 */
-/**
-* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
-* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
-* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
-*/
-function extractExamples(schema) {
-	if (Array.isArray(schema.examples)) return schema.examples;
-	return schema.example !== void 0 ? [schema.example] : void 0;
-}
-function buildSchemaNode(schema, name, nullable, defaultValue) {
-	return {
+function createNode({ schema, name, nullable, defaultValue }, extras) {
+	return ast.factory.createSchema({
 		name,
 		nullable,
 		title: schema.title,
@@ -1119,123 +953,164 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 		writeOnly: schema.writeOnly,
 		default: defaultValue,
 		examples: extractExamples(schema),
-		format: schema.format
-	};
+		format: schema.format,
+		...extras
+	});
 }
+//#endregion
+//#region src/emit/discriminator/preserve.ts
 /**
-* Returns all request body content type keys for an operation.
-*
-* The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
-* `getRequestSchema` already performs), so the returned list accurately reflects the
-* available content types even for referenced bodies.
+* Creates a single-property object schema used as a discriminator literal.
 *
 * @example
 * ```ts
-* getRequestBodyContentTypes(document, operation)
-* // ['application/json', 'multipart/form-data']
+* createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+* // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
 * ```
 */
-function getRequestBodyContentTypes(document, operation) {
-	if (operation.schema.requestBody) operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody);
-	const body = operation.schema.requestBody;
-	if (!body) return [];
-	return body.content ? Object.keys(body.content) : [];
+function createDiscriminantNode({ propertyName, value }) {
+	return ast.factory.createSchema({
+		type: "object",
+		primitive: "object",
+		properties: [ast.factory.createProperty({
+			name: propertyName,
+			schema: ast.factory.createSchema({
+				type: "enum",
+				primitive: "string",
+				enumValues: [value]
+			}),
+			required: true
+		})]
+	});
 }
 /**
-* Returns all response content type keys for an operation at a given status code.
-*
-* Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
-* so the returned list reflects the available content types even for referenced responses.
+* Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
 *
 * @example
 * ```ts
-* getResponseBodyContentTypes(document, operation, 200)
-* // ['application/json', 'application/xml']
+* findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
 * ```
 */
-function getResponseBodyContentTypes(document, operation, statusCode) {
-	resolveResponseRefs(document, operation);
-	const responseObj = getResponseByStatusCode({
-		document,
-		operation,
-		statusCode
-	});
-	if (!responseObj || typeof responseObj !== "object" || isReference(responseObj)) return [];
-	const body = responseObj;
-	return body.content ? Object.keys(body.content) : [];
-}
-//#endregion
-//#region src/converters.ts
-/**
-* Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
-*
-* This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
-* from the array to its items sub-schema, so they are valid for downstream processing.
-*
-* @note A defensive measure for non-compliant specs.
-*/
-function normalizeArrayEnum(schema) {
-	const normalizedItems = {
-		...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
-		enum: schema.enum
-	};
-	const { enum: _enum, ...schemaWithoutEnum } = schema;
-	return {
-		...schemaWithoutEnum,
-		items: normalizedItems
-	};
+function findDiscriminator(mapping, ref) {
+	if (!mapping || !ref) return null;
+	return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null;
 }
 /**
-* Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
-* and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+* Narrows each `oneOf`/`anyOf` member with its discriminant value, intersecting the member's own
+* node with either the shared-properties slice carrying that value, or a synthetic discriminant
+* literal. The referenced child schema's own definition is left untouched — narrowing happens only
+* at this union usage site, which is what makes this mode "preserve" (as opposed to `propagate`,
+* which additionally patches the child schema's own definition in a post-pass).
 */
-function createNullNode(schema, name, nullable) {
-	return ast.factory.createSchema({
-		type: "null",
-		primitive: "null",
-		name,
-		title: schema.title,
-		description: schema.description,
-		deprecated: schema.deprecated,
-		nullable,
-		format: schema.format
+function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parse, rawOptions, name, refs }) {
+	function pickDiscriminatorPropertyNode(node, propertyName) {
+		const discriminatorProperty = ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
+		if (!discriminatorProperty) return null;
+		return ast.factory.createSchema({
+			type: "object",
+			primitive: "object",
+			properties: [discriminatorProperty]
+		});
+	}
+	function implicitDiscriminantValue(member) {
+		if (!discriminator || discriminator.mapping || !isReference(member)) return null;
+		const value = extractRefName(member.$ref);
+		if (!value) return null;
+		const variant = refs.resolve(member.$ref, { report: false });
+		if (!variant) return null;
+		const propertyName = discriminator.propertyName;
+		const seen = /* @__PURE__ */ new Set([member.$ref]);
+		function constrains(v) {
+			const prop = v.properties?.[propertyName];
+			const resolved = prop && isReference(prop) ? refs.resolve(prop.$ref, { report: false }) : prop;
+			if (resolved && (Array.isArray(resolved.enum) || resolved.const !== void 0)) return true;
+			const composition = v.allOf ?? v.oneOf ?? v.anyOf;
+			if (!composition) return false;
+			return composition.some((m) => {
+				if (!isReference(m)) return constrains(m);
+				if (seen.has(m.$ref)) return false;
+				seen.add(m.$ref);
+				const r = refs.resolve(m.$ref, { report: false });
+				return r ? constrains(r) : false;
+			});
+		}
+		return constrains(variant) ? null : value;
+	}
+	return unionMembers.map((s) => {
+		const ref = isReference(s) ? s.$ref : void 0;
+		const discriminatorValue = findDiscriminator(discriminator?.mapping, ref) ?? implicitDiscriminantValue(s);
+		const memberNode = parse({
+			schema: s,
+			name
+		}, rawOptions);
+		if (!discriminatorValue || !discriminator) return memberNode;
+		const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({
+			propertyName: discriminator.propertyName,
+			values: [discriminatorValue]
+		})], { depth: "shallow" }), discriminator.propertyName) : void 0;
+		return ast.factory.createSchema({
+			type: "intersection",
+			members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({
+				propertyName: discriminator.propertyName,
+				value: discriminatorValue
+			})]
+		});
 	});
 }
 /**
-* Names the inline enums on a property's schema, and on each item when the property is a tuple, from
-* the parent and property name. Wraps `macroEnumName` at the property construction site.
+* Filters the discriminated members out of an `allOf` list: an `allOf` member that `$ref`s a
+* discriminated union's parent, where this schema is itself one of that union's children, is
+* dropped from `members` and its discriminant value collected instead — the same synthetic
+* literal `narrowUnionMembers` produces, so the emitted node stays a plain intersection rather
+* than nesting the whole parent union one level deeper.
 */
-function nameEnums(node, options) {
-	const macro = macroEnumName(options);
-	const named = ast.applyMacros(node, [macro], { depth: "shallow" });
-	const tupleNode = ast.narrowSchema(named, "tuple");
-	if (tupleNode?.items) {
-		const namedItems = tupleNode.items.map((item) => ast.applyMacros(item, [macro], { depth: "shallow" }));
-		if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
-			...tupleNode,
-			items: namedItems
-		};
-	}
-	return named;
+function extractDiscriminatedAllOfMembers({ allOfMembers, name, refs }) {
+	const discriminantValues = [];
+	return {
+		members: allOfMembers.filter((item) => {
+			if (!isReference(item) || !name) return true;
+			const deref = refs.resolve(item.$ref);
+			if (!deref || !isDiscriminator(deref)) return true;
+			const parentUnion = deref.oneOf ?? deref.anyOf;
+			if (!parentUnion) return true;
+			const childRef = `${SCHEMA_REF_PREFIX}${name}`;
+			const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef);
+			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
+			if (inOneOf || inMapping) {
+				const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef);
+				if (discriminatorValue) discriminantValues.push({
+					propertyName: deref.discriminator.propertyName,
+					value: discriminatorValue
+				});
+				return false;
+			}
+			return true;
+		}),
+		discriminantValues
+	};
 }
+//#endregion
+//#region src/emit/converters/composition.ts
 /**
 * Converts a `$ref` schema into a `RefSchemaNode`.
 *
 * The resolved schema is stored in `node.schema`. Usage-site sibling fields
 * (description, readOnly, nullable, etc.) are stored directly on the ref node.
 * Use `syncSchemaRef(node)` in printers to get a merged view of both.
-* Circular refs are detected in `resolveRefNode` and leave `schema` as `null`.
+* Circular refs are detected in `refs.resolveNode` and leave `schema` as `null`.
 */
-function convertRef({ schema, name, nullable, defaultValue, rawOptions, document, resolveRefNode, refExists, renames }) {
+function convertRef({ schema, name, nullable, defaultValue, rawOptions, document, parse, refs, renames }) {
 	const refPath = schema.$ref;
-	const resolvedSchema = refPath ? resolveRefNode(refPath, rawOptions) : null;
-	if (refPath && document.components && !refExists(refPath)) return ast.factory.createSchema({
-		...buildSchemaNode(schema, name, nullable, defaultValue),
-		type: "unknown"
-	});
+	const resolvedSchema = refPath ? refs.resolveNode(refPath, parse, rawOptions) : null;
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
+	if (refPath && document.components && !refs.exists(refPath)) return createNode(ctx, { type: "unknown" });
 	const targetName = renames?.get(schema.$ref);
-	return ast.factory.createSchema({
-		...buildSchemaNode(schema, name, nullable, defaultValue),
+	return createNode(ctx, {
 		type: "ref",
 		name: extractRefName(schema.$ref),
 		ref: schema.$ref,
@@ -1246,7 +1121,7 @@ function convertRef({ schema, name, nullable, defaultValue, rawOptions, document
 /**
 * Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
 */
-function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse, document }) {
+function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse, refs }) {
 	if (schema.allOf.length === 1 && !schema.properties && !(Array.isArray(schema.required) && schema.required.length) && schema.additionalProperties === void 0) {
 		const [memberSchema] = schema.allOf;
 		const memberNode = parse({
@@ -1271,26 +1146,12 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 			format: schema.format ?? memberNode.format
 		});
 	}
-	const filteredDiscriminantValues = [];
-	const allOfMembers = schema.allOf.filter((item) => {
-		if (!isReference(item) || !name) return true;
-		const deref = resolveRef(document, item.$ref);
-		if (!deref || !isDiscriminator(deref)) return true;
-		const parentUnion = deref.oneOf ?? deref.anyOf;
-		if (!parentUnion) return true;
-		const childRef = `${SCHEMA_REF_PREFIX}${name}`;
-		const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef);
-		const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
-		if (inOneOf || inMapping) {
-			const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef);
-			if (discriminatorValue) filteredDiscriminantValues.push({
-				propertyName: deref.discriminator.propertyName,
-				value: discriminatorValue
-			});
-			return false;
-		}
-		return true;
-	}).map((s) => parse({
+	const { members: discriminatedAllOf, discriminantValues } = extractDiscriminatedAllOfMembers({
+		allOfMembers: schema.allOf,
+		name,
+		refs
+	});
+	const allOfMembers = discriminatedAllOf.map((s) => parse({
 		schema: s,
 		name
 	}, rawOptions));
@@ -1301,7 +1162,7 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 		if (missingRequired.length) {
 			const resolvedMembers = schema.allOf.flatMap((item) => {
 				if (!isReference(item)) return [item];
-				const deref = resolveRef(document, item.$ref);
+				const deref = refs.resolve(item.$ref);
 				return deref && !isReference(deref) ? [deref] : [];
 			});
 			for (const key of missingRequired) for (const resolved of resolvedMembers) {
@@ -1324,61 +1185,33 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 		const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
 		allOfMembers.push(parse({ schema: schemaWithoutAllOf }, rawOptions));
 	}
-	for (const { propertyName, value } of filteredDiscriminantValues) allOfMembers.push(createDiscriminantNode({
+	for (const { propertyName, value } of discriminantValues) allOfMembers.push(createDiscriminantNode({
 		propertyName,
 		value
 	}));
-	return ast.factory.createSchema({
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
 		type: "intersection",
-		members: [...mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
-		...buildSchemaNode(schema, name, nullable, defaultValue)
+		members: [...mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))]
 	});
 }
 /**
 * Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
 */
-function convertUnion({ schema, name, nullable, defaultValue, rawOptions, parse, document }) {
-	function pickDiscriminatorPropertyNode(node, propertyName) {
-		const discriminatorProperty = ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
-		if (!discriminatorProperty) return null;
-		return ast.factory.createSchema({
-			type: "object",
-			primitive: "object",
-			properties: [discriminatorProperty]
-		});
-	}
-	function resolveRefSilent($ref) {
-		if (!$ref.startsWith("#")) return null;
-		return decodeURIComponent($ref.substring(1)).split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document) ?? null;
-	}
-	function implicitDiscriminantValue(member) {
-		if (!discriminator || discriminator.mapping || !isReference(member)) return null;
-		const value = extractRefName(member.$ref);
-		if (!value) return null;
-		const variant = resolveRefSilent(member.$ref);
-		if (!variant) return null;
-		const propertyName = discriminator.propertyName;
-		const seen = /* @__PURE__ */ new Set([member.$ref]);
-		function constrains(v) {
-			const prop = v.properties?.[propertyName];
-			const resolved = prop && isReference(prop) ? resolveRefSilent(prop.$ref) : prop;
-			if (resolved && (Array.isArray(resolved.enum) || resolved.const !== void 0)) return true;
-			const composition = v.allOf ?? v.oneOf ?? v.anyOf;
-			if (!composition) return false;
-			return composition.some((m) => {
-				if (!isReference(m)) return constrains(m);
-				if (seen.has(m.$ref)) return false;
-				seen.add(m.$ref);
-				const r = resolveRefSilent(m.$ref);
-				return r ? constrains(r) : false;
-			});
-		}
-		return constrains(variant) ? null : value;
-	}
+function convertUnion({ schema, name, nullable, defaultValue, rawOptions, parse, refs }) {
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
 	const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
 	const strategy = schema.oneOf ? "one" : "any";
-	const unionBase = {
-		...buildSchemaNode(schema, name, nullable, defaultValue),
+	const unionExtras = {
 		discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
 		strategy
 	};
@@ -1389,41 +1222,29 @@ function convertUnion({ schema, name, nullable, defaultValue, rawOptions, parse,
 		name
 	}, rawOptions) : void 0;
 	if (sharedPropertiesNode || discriminator) {
-		const members = unionMembers.map((s) => {
-			const ref = isReference(s) ? s.$ref : void 0;
-			const discriminatorValue = findDiscriminator(discriminator?.mapping, ref) ?? implicitDiscriminantValue(s);
-			const memberNode = parse({
-				schema: s,
-				name
-			}, rawOptions);
-			if (!discriminatorValue || !discriminator) return memberNode;
-			const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({
-				propertyName: discriminator.propertyName,
-				values: [discriminatorValue]
-			})], { depth: "shallow" }), discriminator.propertyName) : void 0;
-			return ast.factory.createSchema({
-				type: "intersection",
-				members: [memberNode, narrowedDiscriminatorNode ?? createDiscriminantNode({
-					propertyName: discriminator.propertyName,
-					value: discriminatorValue
-				})]
-			});
+		const members = narrowUnionMembers({
+			unionMembers,
+			discriminator,
+			sharedPropertiesNode,
+			parse,
+			rawOptions,
+			name,
+			refs
 		});
-		const unionNode = ast.factory.createSchema({
+		const unionNode = createNode(ctx, {
 			type: "union",
-			...unionBase,
+			...unionExtras,
 			members
 		});
 		if (!sharedPropertiesNode) return unionNode;
-		return ast.factory.createSchema({
+		return createNode(ctx, {
 			type: "intersection",
-			...buildSchemaNode(schema, name, nullable, defaultValue),
 			members: [unionNode, sharedPropertiesNode]
 		});
 	}
-	const unionNode = ast.factory.createSchema({
+	const unionNode = createNode(ctx, {
 		type: "union",
-		...unionBase,
+		...unionExtras,
 		members: unionMembers.map((s) => parse({
 			schema: s,
 			name
@@ -1432,60 +1253,125 @@ function convertUnion({ schema, name, nullable, defaultValue, rawOptions, parse,
 	return ast.applyMacros(unionNode, [macroSimplifyUnion], { depth: "shallow" });
 }
 /**
+* Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
+* Only called once the multi-type rule's `match` has confirmed more than one non-`null` type
+* remains; a single remaining type (e.g. `['string', 'null']`) is handled as that type instead,
+* with nullability already folded in.
+*/
+function convertMultiType({ schema, name, nullable, defaultValue, rawOptions, parse }) {
+	const types = schema.type;
+	const nonNullTypes = types.filter((t) => t !== "null");
+	return createNode({
+		schema,
+		name,
+		nullable: types.includes("null") || nullable || void 0,
+		defaultValue
+	}, {
+		type: "union",
+		members: nonNullTypes.map((t) => {
+			return parse({
+				schema: {
+					...schema,
+					type: t
+				},
+				name
+			}, rawOptions);
+		})
+	});
+}
+//#endregion
+//#region src/emit/converters/scalar.ts
+/**
+* Normalizes malformed `{ type: 'array', enum: [...] }` schemas by moving enum values into items.
+*
+* This pattern violates the OpenAPI spec but appears in real specs. The fix moves enum values
+* from the array to its items sub-schema, so they are valid for downstream processing.
+*
+* @note A defensive measure for non-compliant specs.
+*/
+function normalizeArrayEnum(schema) {
+	const normalizedItems = {
+		...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
+		enum: schema.enum
+	};
+	const { enum: _enum, ...schemaWithoutEnum } = schema;
+	return {
+		...schemaWithoutEnum,
+		items: normalizedItems
+	};
+}
+/**
+* Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+* and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+*/
+function createNullNode(schema, name, nullable) {
+	return ast.factory.createSchema({
+		type: "null",
+		primitive: "null",
+		name,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		nullable,
+		format: schema.format
+	});
+}
+/**
 * Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
 */
 function convertConst({ schema, name, nullable, defaultValue }) {
 	const constValue = schema.const;
 	if (constValue === null) return createNullNode(schema, name);
 	const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
-	return ast.factory.createSchema({
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
 		type: "enum",
 		primitive: constPrimitive,
-		enumValues: [constValue],
-		...buildSchemaNode(schema, name, nullable, defaultValue)
+		enumValues: [constValue]
 	});
 }
 /**
-* Converts a format-annotated schema into a special-type `SchemaNode`.
-* Returns `null` when the format should fall through to string handling (`dateType: false`).
+* Converts a format-annotated schema into a special-type `SchemaNode`. Only called once the
+* `format` rule's `match` has confirmed the format is handled (see `isHandledFormat`) and, for
+* a date-ish format, that `dateType` is not `false`.
 */
 function convertFormat({ schema, name, nullable, defaultValue, options }) {
-	const base = buildSchemaNode(schema, name, nullable, defaultValue);
-	if (schema.format === "int64") return ast.factory.createSchema({
+	const ctx = {
+		schema,
+		name,
+		nullable,
+		defaultValue
+	};
+	if (schema.format === "int64") return createNode(ctx, {
 		type: options.integerType === "bigint" ? "bigint" : "integer",
 		primitive: "integer",
-		...base,
 		min: schema.minimum,
 		max: schema.maximum,
-		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
+		...getExclusiveBounds(schema)
 	});
 	if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") {
 		const dateType = getDateType(options, schema.format);
-		if (!dateType) return null;
-		if (dateType.type === "datetime") return ast.factory.createSchema({
-			...base,
+		if (dateType.type === "datetime") return createNode(ctx, {
 			primitive: "string",
 			type: "datetime",
 			offset: dateType.offset,
 			local: dateType.local
 		});
-		return ast.factory.createSchema({
-			...base,
+		return createNode(ctx, {
 			primitive: "string",
 			type: dateType.type,
 			representation: dateType.representation
 		});
 	}
 	const specialType = getSchemaType(schema.format);
-	if (!specialType) return null;
-	const specialPrimitive = specialType === "number" || specialType === "integer" || specialType === "bigint" ? specialType : "string";
-	const hasLength = specialType === "url" || specialType === "uuid" || specialType === "email";
-	return ast.factory.createSchema({
-		...base,
-		primitive: specialPrimitive,
+	return createNode(ctx, {
+		primitive: specialType === "number" || specialType === "integer" || specialType === "bigint" ? specialType : "string",
 		type: specialType,
-		...hasLength ? {
+		...specialType === "url" || specialType === "uuid" || specialType === "email" ? {
 			min: schema.minLength,
 			max: schema.maxLength
 		} : {}
@@ -1505,21 +1391,28 @@ function convertEnum({ schema, name, nullable, type, rawOptions, parse }) {
 	const enumNullable = nullable || nullInEnum || void 0;
 	const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
 	const enumPrimitive = getPrimitiveType(type);
-	const enumBase = {
+	const ctx = {
+		schema,
+		name,
+		nullable: enumNullable,
+		defaultValue: enumDefault
+	};
+	const enumExtras = {
 		type: "enum",
-		primitive: enumPrimitive,
-		...buildSchemaNode(schema, name, enumNullable, enumDefault)
+		primitive: enumPrimitive
 	};
 	const extensionKey = enumExtensionKeys.find((key) => key in schema);
 	const descriptionKey = enumDescriptionKeys.find((key) => key in schema);
 	if (extensionKey || descriptionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
-		const enumPrimitiveType = enumPrimitive === "number" || enumPrimitive === "integer" ? "number" : enumPrimitive === "boolean" ? "boolean" : "string";
+		let enumPrimitiveType = "string";
+		if (enumPrimitive === "number" || enumPrimitive === "integer") enumPrimitiveType = "number";
+		else if (enumPrimitive === "boolean") enumPrimitiveType = "boolean";
 		const rawEnumNames = extensionKey ? schema[extensionKey] : void 0;
 		const rawEnumDescriptions = descriptionKey ? schema[descriptionKey] : void 0;
 		const uniqueValues = [...new Set(filteredValues)];
 		const seenNames = /* @__PURE__ */ new Set();
-		return ast.factory.createSchema({
-			...enumBase,
+		return createNode(ctx, {
+			...enumExtras,
 			primitive: enumPrimitiveType,
 			namedEnumValues: uniqueValues.map((value, index) => ({
 				name: String(rawEnumNames?.[index] ?? value),
@@ -1533,12 +1426,103 @@ function convertEnum({ schema, name, nullable, type, rawOptions, parse }) {
 			})
 		});
 	}
-	return ast.factory.createSchema({
-		...enumBase,
+	return createNode(ctx, {
+		...enumExtras,
 		enumValues: [...new Set(filteredValues)]
 	});
 }
 /**
+* Converts a `type: 'string'` schema into a `StringSchemaNode`.
+*/
+function convertString({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "string",
+		primitive: "string",
+		min: schema.minLength,
+		max: schema.maxLength,
+		pattern: schema.pattern
+	});
+}
+/**
+* Converts a `type: 'number'` or `type: 'integer'` schema.
+*/
+function convertNumeric({ schema, name, nullable, defaultValue }, type) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type,
+		primitive: type,
+		min: schema.minimum,
+		max: schema.maximum,
+		...getExclusiveBounds(schema),
+		multipleOf: schema.multipleOf
+	});
+}
+/**
+* Converts a `type: 'boolean'` schema.
+*/
+function convertBoolean({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "boolean",
+		primitive: "boolean"
+	});
+}
+/**
+* Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
+* into a `blob` node.
+*/
+function convertBinary({ schema, name, nullable, defaultValue }) {
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "blob",
+		primitive: "string"
+	});
+}
+//#endregion
+//#region src/emit/converters/structural.ts
+/**
+* Resolves a `true` or empty-object map schema (`additionalProperties`/`patternProperties`) to
+* `options.unknownType`, otherwise parses it as a regular schema.
+*/
+function resolveMapSchema(mapSchema, options, parse, rawOptions) {
+	if (mapSchema === true || typeof mapSchema === "object" && Object.keys(mapSchema).length === 0) return ast.factory.createSchema({ type: options.unknownType });
+	return parse({ schema: mapSchema }, rawOptions);
+}
+/**
+* Names the inline enums on a property's schema, and on each item when the property is a tuple, from
+* the parent and property name. Wraps `macroEnumName` at the property construction site.
+*/
+function nameEnums(node, options) {
+	const macro = macroEnumName(options);
+	const named = ast.applyMacros(node, [macro], { depth: "shallow" });
+	const tupleNode = ast.narrowSchema(named, "tuple");
+	if (tupleNode?.items) {
+		const namedItems = tupleNode.items.map((item) => ast.applyMacros(item, [macro], { depth: "shallow" }));
+		if (namedItems.some((item, i) => item !== tupleNode.items[i])) return {
+			...tupleNode,
+			items: namedItems
+		};
+	}
+	return named;
+}
+/**
 * Converts an object-like schema into an `ObjectSchemaNode`.
 */
 function convertObject({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
@@ -1564,146 +1548,84 @@ function convertObject({ schema, name, nullable, defaultValue, rawOptions, optio
 		});
 	}) : [];
 	const additionalProperties = schema.additionalProperties;
-	const additionalPropertiesNode = (() => {
-		if (additionalProperties === true) return true;
-		if (additionalProperties === false) return false;
-		if (additionalProperties && Object.keys(additionalProperties).length > 0) return parse({ schema: additionalProperties }, rawOptions);
-		if (additionalProperties) return ast.factory.createSchema({ type: options.unknownType });
-	})();
+	let additionalPropertiesNode;
+	if (additionalProperties === true) additionalPropertiesNode = true;
+	else if (additionalProperties) additionalPropertiesNode = resolveMapSchema(additionalProperties, options, parse, rawOptions);
+	else additionalPropertiesNode = additionalProperties;
 	const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
-	const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: patternSchema }, rawOptions)])) : void 0;
-	const objectNode = ast.factory.createSchema({
+	const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, resolveMapSchema(patternSchema, options, parse, rawOptions)])) : void 0;
+	const objectNode = createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
 		type: "object",
 		primitive: "object",
 		properties,
 		additionalProperties: additionalPropertiesNode,
 		patternProperties,
 		minProperties: schema.minProperties,
-		maxProperties: schema.maxProperties,
-		...buildSchemaNode(schema, name, nullable, defaultValue)
+		maxProperties: schema.maxProperties
 	});
 	if (isDiscriminator(schema) && schema.discriminator.mapping) {
 		const discPropName = schema.discriminator.propertyName;
 		const values = Object.keys(schema.discriminator.mapping);
 		const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : void 0;
-		return ast.applyMacros(objectNode, [macroDiscriminatorEnum({
-			propertyName: discPropName,
-			values,
-			enumName
-		})], { depth: "shallow" });
-	}
-	return objectNode;
-}
-/**
-* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
-*/
-function convertTuple({ schema, name, nullable, defaultValue, rawOptions, parse }) {
-	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }, rawOptions));
-	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? ast.factory.createSchema({ type: "any" }) : parse({ schema: schema.items }, rawOptions);
-	return ast.factory.createSchema({
-		type: "tuple",
-		primitive: "array",
-		items: tupleItems,
-		rest,
-		min: schema.minItems,
-		max: schema.maxItems,
-		...buildSchemaNode(schema, name, nullable, defaultValue)
-	});
-}
-/**
-* Converts a `type: 'array'` schema into an `ArraySchemaNode`.
-*/
-function convertArray({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
-	const rawItems = schema.items;
-	const itemName = rawItems?.enum?.length && name ? enumPropName(null, name, options.enumSuffix) : name;
-	const items = rawItems ? [parse({
-		schema: rawItems,
-		name: itemName
-	}, rawOptions)] : [];
-	return ast.factory.createSchema({
-		type: "array",
-		primitive: "array",
-		items,
-		min: schema.minItems,
-		max: schema.maxItems,
-		unique: schema.uniqueItems ?? void 0,
-		...buildSchemaNode(schema, name, nullable, defaultValue)
-	});
-}
-/**
-* Converts a `type: 'string'` schema into a `StringSchemaNode`.
-*/
-function convertString({ schema, name, nullable, defaultValue }) {
-	return ast.factory.createSchema({
-		type: "string",
-		primitive: "string",
-		min: schema.minLength,
-		max: schema.maxLength,
-		pattern: schema.pattern,
-		...buildSchemaNode(schema, name, nullable, defaultValue)
-	});
-}
-/**
-* Converts a `type: 'number'` or `type: 'integer'` schema.
-*/
-function convertNumeric({ schema, name, nullable, defaultValue }, type) {
-	return ast.factory.createSchema({
-		type,
-		primitive: type,
-		min: schema.minimum,
-		max: schema.maximum,
-		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0,
-		multipleOf: schema.multipleOf,
-		...buildSchemaNode(schema, name, nullable, defaultValue)
-	});
-}
-/**
-* Converts a `type: 'boolean'` schema.
-*/
-function convertBoolean({ schema, name, nullable, defaultValue }) {
-	return ast.factory.createSchema({
-		type: "boolean",
-		primitive: "boolean",
-		...buildSchemaNode(schema, name, nullable, defaultValue)
-	});
+		return ast.applyMacros(objectNode, [macroDiscriminatorEnum({
+			propertyName: discPropName,
+			values,
+			enumName
+		})], { depth: "shallow" });
+	}
+	return objectNode;
 }
 /**
-* Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
-* into a `blob` node.
+* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
 */
-function convertBinary({ schema, name, nullable, defaultValue }) {
-	return ast.factory.createSchema({
-		type: "blob",
-		primitive: "string",
-		...buildSchemaNode(schema, name, nullable, defaultValue)
+function convertTuple({ schema, name, nullable, defaultValue, rawOptions, parse }) {
+	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }, rawOptions));
+	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? ast.factory.createSchema({ type: "any" }) : parse({ schema: schema.items }, rawOptions);
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "tuple",
+		primitive: "array",
+		items: tupleItems,
+		rest,
+		min: schema.minItems,
+		max: schema.maxItems
 	});
 }
 /**
-* Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
-*
-* Returns `null` when only one non-`null` type remains (e.g. `['string', 'null']`), so `parse`
-* falls through and handles it as that single type with nullability already folded in.
+* Converts a `type: 'array'` schema into an `ArraySchemaNode`.
 */
-function convertMultiType({ schema, name, nullable, defaultValue, rawOptions, parse }) {
-	const types = schema.type;
-	const nonNullTypes = types.filter((t) => t !== "null");
-	if (nonNullTypes.length <= 1) return null;
-	const arrayNullable = types.includes("null") || nullable || void 0;
-	return ast.factory.createSchema({
-		type: "union",
-		members: nonNullTypes.map((t) => {
-			return parse({
-				schema: {
-					...schema,
-					type: t
-				},
-				name
-			}, rawOptions);
-		}),
-		...buildSchemaNode(schema, name, arrayNullable, defaultValue)
+function convertArray({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+	const rawItems = schema.items;
+	const itemName = rawItems?.enum?.length && name ? enumPropName(null, name, options.enumSuffix) : name;
+	const items = rawItems ? [parse({
+		schema: rawItems,
+		name: itemName
+	}, rawOptions)] : [];
+	return createNode({
+		schema,
+		name,
+		nullable,
+		defaultValue
+	}, {
+		type: "array",
+		primitive: "array",
+		items,
+		min: schema.minItems,
+		max: schema.maxItems,
+		unique: schema.uniqueItems ?? void 0
 	});
 }
+//#endregion
+//#region src/emit/parseSchema.ts
 /**
 * Ordered schema rule table. Order is significant: composition keywords (`$ref`, `allOf`,
 * `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
@@ -1728,7 +1650,11 @@ const schemaRules = [
 		convert: convertConst
 	},
 	{
-		match: ({ schema }) => !!schema.format,
+		match: ({ schema, options }) => {
+			if (!schema.format) return false;
+			if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") return options.dateType !== false;
+			return isHandledFormat(schema.format);
+		},
 		convert: convertFormat
 	},
 	{
@@ -1736,7 +1662,7 @@ const schemaRules = [
 		convert: convertBinary
 	},
 	{
-		match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1,
+		match: ({ schema }) => Array.isArray(schema.type) && schema.type.filter((t) => t !== "null").length > 1,
 		convert: convertMultiType
 	},
 	{
@@ -1785,72 +1711,306 @@ const schemaRules = [
 	}
 ];
 //#endregion
-//#region src/parser.ts
+//#region src/refs.ts
+const _refCache = /* @__PURE__ */ new WeakMap();
 /**
-* Creates the schema and operation converters bound to one OpenAPI document.
+* Walks a local `#/...` JSON pointer against `document`, memoized per document. `applicable` is
+* `false` for an empty or non-local ref (the caller should not treat that as a failed lookup).
+* Shared by `resolveRef`'s reporting walk and `createRefs().resolve`'s silent walk, so both use
+* the same trimming and caching instead of two separate implementations.
+*/
+function walkPointer(document, $ref) {
+	const trimmed = $ref.trim();
+	if (trimmed === "" || !trimmed.startsWith("#")) return {
+		applicable: false,
+		value: null
+	};
+	const pointer = globalThis.decodeURIComponent(trimmed.substring(1));
+	let docCache = _refCache.get(document);
+	if (!docCache) {
+		docCache = /* @__PURE__ */ new Map();
+		_refCache.set(document, docCache);
+	}
+	if (docCache.has(pointer)) return {
+		applicable: true,
+		value: docCache.get(pointer)
+	};
+	const current = pointer.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
+	if (current) docCache.set(pointer, current);
+	return {
+		applicable: true,
+		value: current ?? null
+	};
+}
+/**
+* Resolves a local JSON pointer reference from a document.
 *
-* Owns the per-instance `$ref` state (cycle detection, resolved-node cache, existence cache) and
-* the `parseSchema` recursion seam, then dispatches each schema through the ordered `schemaRules`
-* table from `converters.ts`. Every converter is a standalone function that recurses through the
-* `parse` function passed to it, so this file only wires state to the converters.
+* Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
+* resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
+* build there is no sink to collect it, so it throws instead.
 *
-* @internal
+* @example
+* ```ts
+* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
+* ```
 */
-function createSchemaParser(ctx) {
-	const document = ctx.document;
-	/**
-	* Tracks `$ref` paths that are currently being resolved to prevent infinite
-	* recursion when schemas contain circular references (e.g. `Pet → parent → Pet`).
-	*/
+function resolveRef(document, $ref) {
+	const { applicable, value } = walkPointer(document, $ref);
+	if (!applicable) return null;
+	if (value) return value;
+	const diagnostic = {
+		code: Diagnostics.code.refNotFound,
+		severity: "error",
+		message: `Could not find a definition for ${$ref}.`,
+		help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+		location: {
+			kind: "schema",
+			pointer: $ref,
+			ref: $ref
+		}
+	};
+	if (!Diagnostics.report(diagnostic)) throw new Diagnostics.Error(diagnostic);
+	return null;
+}
+/**
+* Resolves a `$ref` object while preserving the original `$ref` field on the result.
+*
+* Useful for parser flows that need both dereferenced fields and pointer
+* identity (for naming/import purposes). Non-reference values are returned as-is.
+*
+* @example
+* ```ts
+* dereferenceWithRef(document, { $ref: '#/components/schemas/Pet' })
+* // { $ref: '#/components/schemas/Pet', type: 'object', properties: { ... } }
+* ```
+*/
+function dereferenceWithRef(document, schema) {
+	if (isReference(schema)) return {
+		...schema,
+		...resolveRef(document, schema.$ref),
+		$ref: schema.$ref
+	};
+	return schema;
+}
+/**
+* Creates the `$ref` resolution service for one document.
+*
+* Replaces what used to be six overlapping resolvers (a reporting walk, a silent walk, an
+* existence check, and a resolve-then-parse-into-a-node step, each with its own cache) with one
+* pointer walk and one explicit `report` contract for a missing ref: `report: true` (the default)
+* reports a `refNotFound` diagnostic (or throws outside a build), `report: false` resolves to
+* `null` silently for a speculative lookup.
+*
+* @example
+* ```ts
+* const refs = createRefs(document)
+* refs.resolve<SchemaObject>('#/components/schemas/Pet')
+* refs.resolve<SchemaObject>('#/components/schemas/Pet', { report: false })
+* refs.exists('#/components/schemas/Pet')
+* refs.resolveNode('#/components/schemas/Pet', parseSchema)
+* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+* ```
+*/
+function createRefs(document) {
+	const resolvedNodeCache = /* @__PURE__ */ new Map();
+	const existenceCache = /* @__PURE__ */ new Map();
 	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
-	* Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
-	*
-	* Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
-	* it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
-	* since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
-	* Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
+	* Resolves a local `#/...` JSON pointer. Returns `null` for an empty or non-local ref.
+	* `report: true` (default) reports a `refNotFound` diagnostic into the active build (or throws
+	* outside one) when the pointer cannot be resolved. `report: false` resolves to `null` silently,
+	* for a speculative lookup where a missing ref is not an error.
 	*/
-	const resolvedRefCache = /* @__PURE__ */ new Map();
+	function resolve(refPath, options) {
+		if (options?.report === false) {
+			const { applicable, value } = walkPointer(document, refPath);
+			return applicable ? value : null;
+		}
+		return resolveRef(document, refPath);
+	}
 	/**
-	* Memoized record of whether a `$ref` path resolves to a node the document actually defines.
+	* Returns `true` when a `$ref` path resolves to a component the document actually defines.
 	* A circular ref still resolves to an existing target, so this stays `true` for cycles and only
-	* goes `false` for a `$ref` that points at a component the spec never declares.
+	* goes `false` for a `$ref` that points at a component the spec never declares. Memoized.
 	*/
-	const refExistence = /* @__PURE__ */ new Map();
-	function refExists(refPath) {
-		if (!refExistence.has(refPath)) {
-			let exists = false;
-			try {
-				exists = !!resolveRef(document, refPath);
-			} catch {
-				exists = false;
-			}
-			refExistence.set(refPath, exists);
-		}
-		return refExistence.get(refPath) ?? false;
+	function exists(refPath) {
+		if (!existenceCache.has(refPath)) existenceCache.set(refPath, !!resolve(refPath, { report: false }));
+		return existenceCache.get(refPath) ?? false;
 	}
 	/**
-	* Resolves a `$ref` to its parsed node, guarding against cycles and memoizing per instance.
-	* Returns `null` when the ref is currently being resolved (a cycle) or cannot be resolved
-	* (e.g. a minimal document in a unit test).
+	* Resolves a `$ref` to its parsed node via `parse`, guarding against cycles and memoizing per
+	* instance. Returns `null` when the ref is currently being resolved (a cycle) or cannot be
+	* resolved (e.g. a minimal document in a unit test).
 	*/
-	function resolveRefNode(refPath, rawOptions) {
+	function resolveNode(refPath, parse, rawOptions) {
 		if (resolvingRefs.has(refPath)) return null;
-		if (!resolvedRefCache.has(refPath)) {
+		if (!resolvedNodeCache.has(refPath)) {
 			let resolved = null;
 			try {
-				const referenced = resolveRef(document, refPath);
+				const referenced = resolve(refPath);
 				if (referenced) {
 					resolvingRefs.add(refPath);
-					resolved = parseSchema({ schema: referenced }, rawOptions);
+					resolved = parse({ schema: referenced }, rawOptions);
 					resolvingRefs.delete(refPath);
 				}
 			} catch {}
-			resolvedRefCache.set(refPath, resolved);
+			resolvedNodeCache.set(refPath, resolved);
 		}
-		return resolvedRefCache.get(refPath) ?? null;
+		return resolvedNodeCache.get(refPath) ?? null;
+	}
+	/**
+	* Resolves a `$ref` value without mutating anything: when `value` holds a `$ref`, returns the
+	* resolved target. Returns `null` when the value is empty, cannot be resolved, or is still a
+	* `$ref` after resolving (e.g. a document with no component registry). A non-`$ref` value is
+	* returned as-is.
+	*
+	* @example
+	* ```ts
+	* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+	* ```
+	*/
+	function deref(value) {
+		if (!isReference(value)) return value ? value : null;
+		const resolved = resolve(value.$ref);
+		return resolved && !isReference(resolved) ? resolved : null;
 	}
+	return {
+		resolve,
+		exists,
+		resolveNode,
+		deref
+	};
+}
+//#endregion
+//#region src/model/operations.ts
+/**
+* Returns all parameters for an operation, merging path-level and operation-level entries.
+* Operation-level parameters override path-level ones with the same `in:name` key.
+* Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
+*
+* @example
+* ```ts
+* getParameters({ document, operation })
+* // [{ name: 'petId', in: 'path', required: true, schema: { type: 'integer' } }]
+* ```
+*/
+function getParameters({ document, operation }) {
+	const resolveParams = (params) => params.map((p) => dereferenceWithRef(document, p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
+	const operationParams = resolveParams(operation.schema?.parameters || []);
+	const pathLevelParams = resolveParams(operation.pathItem.parameters ?? []);
+	const paramMap = /* @__PURE__ */ new Map();
+	for (const p of pathLevelParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	for (const p of operationParams) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	return Array.from(paramMap.values());
+}
+function getResponseBody(responseBody, contentType) {
+	if (!responseBody) return false;
+	if (isReference(responseBody)) return false;
+	const body = responseBody;
+	if (!body.content) return false;
+	if (contentType) return contentType in body.content ? body.content[contentType] : false;
+	const picked = pickContentEntry(body.content);
+	return picked ? picked[1] : false;
+}
+/**
+* Returns the response schema for a given operation and HTTP status code.
+*
+* Returns an empty object `{}` when no response body schema is available.
+*
+* @example
+* ```ts
+* getResponseSchema({ document, operation, refs, statusCode: 200 })   // SchemaObject
+* getResponseSchema({ document, operation, refs, statusCode: '4XX' }) // {}
+* ```
+*/
+function getResponseSchema({ document, operation, refs, statusCode, options = {} }) {
+	const responseBody = getResponseBody(getResponseByStatusCode({
+		operation,
+		refs,
+		statusCode
+	}), options.contentType);
+	if (responseBody === false) return {};
+	const schema = responseBody.schema;
+	if (!schema) return {};
+	return dereferenceWithRef(document, schema);
+}
+/**
+* Returns the request body schema for an operation, or `null` when absent.
+*
+* @example
+* ```ts
+* getRequestSchema({ document, operation, refs }) // SchemaObject | null
+* ```
+*/
+function getRequestSchema({ document, operation, refs, options = {} }) {
+	const requestBody = getRequestContent({
+		operation,
+		refs,
+		mediaType: options.contentType
+	});
+	if (requestBody === false) return null;
+	const mediaType = Array.isArray(requestBody) ? requestBody[0] : options.contentType;
+	const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
+	if (mediaType === "application/octet-stream" && (!schema || Object.keys(schema).length === 0)) return {
+		type: "string",
+		contentMediaType: "application/octet-stream"
+	};
+	if (!schema) return null;
+	return dereferenceWithRef(document, schema);
+}
+/**
+* Returns all request body content type keys for an operation, resolving a `$ref` requestBody
+* through `refs`.
+*
+* @example
+* ```ts
+* getRequestBodyContentTypes(operation, refs)
+* // ['application/json', 'multipart/form-data']
+* ```
+*/
+function getRequestBodyContentTypes(operation, refs) {
+	const body = getRequestBody({
+		operation,
+		refs
+	});
+	return body?.content ? Object.keys(body.content) : [];
+}
+/**
+* Returns all response content type keys for an operation at a given status code, resolving the
+* response `$ref` through `refs`.
+*
+* @example
+* ```ts
+* getResponseBodyContentTypes(operation, refs, 200)
+* // ['application/json', 'application/xml']
+* ```
+*/
+function getResponseBodyContentTypes(operation, refs, statusCode) {
+	const responseObj = getResponseByStatusCode({
+		operation,
+		refs,
+		statusCode
+	});
+	if (!responseObj || typeof responseObj !== "object" || isReference(responseObj)) return [];
+	const body = responseObj;
+	return body.content ? Object.keys(body.content) : [];
+}
+//#endregion
+//#region src/parser.ts
+/**
+* Creates the schema and operation converters bound to one OpenAPI document.
+*
+* Takes the `$ref` service for this document (shared with the rest of the pipeline, see
+* `adapter.ts`) and owns the `parseSchema` recursion seam, then dispatches each schema through
+* the ordered `schemaRules` table from `emit/parseSchema.ts`. Every converter is a standalone
+* function that recurses through the `parse` function passed to it, so this file only wires
+* state to the converters.
+*
+* @internal
+*/
+function createSchemaParser(ctx) {
+	const document = ctx.document;
+	const refs = ctx.refs;
 	/**
 	* Converts an OAS `SchemaObject` into a `SchemaNode`.
 	*
@@ -1879,15 +2039,10 @@ function createSchemaParser(ctx) {
 			options,
 			parse: parseSchema,
 			document,
-			resolveRefNode,
-			refExists,
+			refs,
 			renames: ctx.renames
 		};
-		for (const rule of schemaRules) {
-			if (!rule.match(context)) continue;
-			const node = rule.convert(context);
-			if (node) return node;
-		}
+		for (const rule of schemaRules) if (rule.match(context)) return rule.convert(context);
 		const emptyType = options.emptySchemaType;
 		return ast.factory.createSchema({
 			type: emptyType,
@@ -1924,10 +2079,14 @@ function createSchemaParser(ctx) {
 	}
 	/**
 	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
-	* outside the schema itself. Returns an empty object when the request body is missing or a `$ref`.
+	* outside the schema itself, resolving a `$ref` requestBody through `refs`. Returns an
+	* empty object when the request body is missing or cannot be resolved.
 	*/
 	function getRequestBodyMeta(operation) {
-		const body = operation.schema.requestBody;
+		const body = getRequestBody({
+			operation,
+			refs
+		});
 		if (!body) return { required: false };
 		return {
 			description: body.description,
@@ -1953,12 +2112,20 @@ function createSchemaParser(ctx) {
 	function parseOperation(options, operation) {
 		const operationId = getOperationId(operation);
 		const operationName = operationId ? pascalCase(operationId) : void 0;
-		const parameters = getParameters(document, operation).map((param) => parseParameter(options, param, operationName));
-		const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(document, operation);
+		const parameters = getParameters({
+			document,
+			operation
+		}).map((param) => parseParameter(options, param, operationName));
+		const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(operation, refs);
 		const requestBodyMeta = getRequestBodyMeta(operation);
 		const requestBodyName = operationName ? `${operationName}Request` : void 0;
 		const content = allContentTypes.flatMap((ct) => {
-			const schema = getRequestSchema(document, operation, { contentType: ct });
+			const schema = getRequestSchema({
+				document,
+				operation,
+				refs,
+				options: { contentType: ct }
+			});
 			if (!schema) return [];
 			return [ast.factory.createContent({
 				contentType: ct,
@@ -1976,14 +2143,20 @@ function createSchemaParser(ctx) {
 		} : void 0;
 		const responses = getResponseStatusCodes(operation).map((statusCode) => {
 			const responseObj = getResponseByStatusCode({
-				document,
 				operation,
+				refs,
 				statusCode
 			});
 			const responseName = operationName ? `${operationName}Status${statusCode}` : void 0;
 			const description = typeof responseObj === "object" && responseObj !== null ? responseObj.description : void 0;
 			const parseEntrySchema = (contentType) => {
-				const raw = getResponseSchema(document, operation, statusCode, { contentType });
+				const raw = getResponseSchema({
+					document,
+					operation,
+					refs,
+					statusCode,
+					options: { contentType }
+				});
 				return {
 					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
 						schema: raw,
@@ -1992,14 +2165,14 @@ function createSchemaParser(ctx) {
 					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 				};
 			};
-			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ast.factory.createContent({
+			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(operation, refs, statusCode)).map((contentType) => ast.factory.createContent({
 				contentType,
 				...parseEntrySchema(contentType)
 			}));
 			if (content.length === 0) content.push(ast.factory.createContent({
 				contentType: getRequestContentType({
-					document,
-					operation
+					operation,
+					refs
 				}) || "application/json",
 				...parseEntrySchema(ctx.contentType)
 			}));
@@ -2009,12 +2182,10 @@ function createSchemaParser(ctx) {
 				content
 			});
 		});
-		const pathItem = document.paths?.[operation.path];
-		const pathItemDoc = pathItem && !isReference(pathItem) ? pathItem : void 0;
 		const pickDoc = (key) => {
 			const own = operation.schema[key];
 			if (typeof own === "string") return own;
-			const fallback = pathItemDoc?.[key];
+			const fallback = operation.pathItem[key];
 			return typeof fallback === "string" ? fallback : void 0;
 		};
 		return ast.factory.createOperation({
@@ -2183,40 +2354,8 @@ const adapterOas = createAdapter((options) => {
 		enumSuffix
 	};
 	let parsedDocument = null;
-	const documentCache = /* @__PURE__ */ new WeakMap();
-	const schemasCache = /* @__PURE__ */ new WeakMap();
-	const schemaParserCache = /* @__PURE__ */ new WeakMap();
-	function ensureDocument(source) {
-		const cached = documentCache.get(source);
-		if (cached) return cached;
-		const promise = (async () => {
-			const fresh = await parseFromConfig(source);
-			if (validate) await validateDocument(fresh);
-			parsedDocument = fresh;
-			return fresh;
-		})();
-		documentCache.set(source, promise);
-		return promise;
-	}
-	function ensureSchemas(document) {
-		const cached = schemasCache.get(document);
-		if (cached) return cached;
-		const result = getSchemas(document, { contentType });
-		schemasCache.set(document, result);
-		return result;
-	}
-	function ensureSchemaParser({ document, renames }) {
-		const cached = schemaParserCache.get(document);
-		if (cached) return cached;
-		const parser = createSchemaParser({
-			document,
-			contentType,
-			renames
-		});
-		schemaParserCache.set(document, parser);
-		return parser;
-	}
-	function parseInput({ document, schemas, parser }) {
+	const inputCache = /* @__PURE__ */ new WeakMap();
+	function parseInput({ document, refs, schemas, parser }) {
 		const { parseSchema, parseOperation } = parser;
 		const parsedByName = /* @__PURE__ */ new Map();
 		const refAliasMap = /* @__PURE__ */ new Map();
@@ -2239,7 +2378,7 @@ const adapterOas = createAdapter((options) => {
 		const circularNames = [...findCircularSchemas([...parsedByName.values()])];
 		const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null;
 		const operationNodes = [];
-		for (const operation of getOperations(document)) {
+		for (const operation of getOperations(document, refs)) {
 			const operationNode = parseOperation(parserOptions, operation);
 			if (operationNode) operationNodes.push(operationNode);
 		}
@@ -2304,16 +2443,28 @@ const adapterOas = createAdapter((options) => {
 			await validateDocument(await parseDocument(input), options);
 		},
 		async parse(source) {
-			const document = await ensureDocument(source);
-			const { schemas, renames } = ensureSchemas(document);
-			return parseInput({
-				document,
-				schemas,
-				parser: ensureSchemaParser({
+			const cached = inputCache.get(source);
+			if (cached) return cached;
+			const promise = (async () => {
+				const document = await parseFromConfig(source);
+				if (validate) await validateDocument(document);
+				parsedDocument = document;
+				const refs = createRefs(document);
+				const { schemas, renames } = getSchemas(document, { contentType }, refs);
+				return parseInput({
 					document,
-					renames
-				})
-			});
+					refs,
+					schemas,
+					parser: createSchemaParser({
+						document,
+						refs,
+						contentType,
+						renames
+					})
+				});
+			})();
+			inputCache.set(source, promise);
+			return promise;
 		}
 	};
 });