@kubb/adapter-oas 5.5.5 → 5.6.0

package/dist/index.js

@@ -1,12 +1,9 @@
 import "./rolldown-runtime-C0LytTxp.js";
-import { ast, findCircularSchemasFromGraph, narrowSchema, resolveRefName } from "@kubb/ast";
-import { Diagnostics, createAdapter } from "@kubb/core";
+import { Diagnostics, ast, childName, createAdapter, enumPropName, extractRefName, macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion, mergeAdjacentObjectsLazy } from "@kubb/kit";
 import { access, readFile } from "node:fs/promises";
-import path from "node:path";
 import { parse } from "yaml";
 import { upgrade } from "@scalar/openapi-upgrader";
 import { bundle } from "api-ref-bundler";
-import { childName, enumPropName, extractRefName, macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion, mergeAdjacentObjectsLazy } from "@kubb/kit";
 //#region src/constants.ts
 /**
 * Default parser options applied when no explicit options are provided.
@@ -507,7 +504,7 @@ async function parseDocument(pathOrApi) {
 /**
 * Creates a `Document` from an `AdapterSource`.
 *
-* - `{ type: 'path' }` resolves and bundles a local file path or remote URL.
+* - `{ type: 'path' }` bundles an absolute file path (core resolves `input`) or remote URL.
 * - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
 *
 * @example
@@ -518,10 +515,8 @@ async function parseDocument(pathOrApi) {
 */
 async function parseFromConfig(source) {
 	if (source.type === "data") return parseDocument(typeof source.data === "string" ? parse(source.data) : structuredClone(source.data));
-	if (urlRegExp.test(source.path)) return parseDocument(source.path);
-	const resolved = path.resolve(path.dirname(source.path), source.path);
-	await assertInputExists(resolved);
-	return parseDocument(resolved);
+	await assertInputExists(source.path);
+	return parseDocument(source.path);
 }
 /**
 * Asserts the parsed input is an OpenAPI or Swagger document.
@@ -650,21 +645,6 @@ const jsonMimeFragments = [
 function isJsonMimeType(mimeType) {
 	return jsonMimeFragments.some((fragment) => mimeType.includes(fragment));
 }
-/**
-* 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
-* pickContentEntry({ 'application/xml': xmlEntry, 'application/json': jsonEntry })
-* // ['application/json', jsonEntry]
-* ```
-*/
-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
 /**
@@ -870,10 +850,6 @@ function resolveServerUrl(server, overrides) {
 }
 //#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, "");
 }
@@ -894,12 +870,12 @@ function getResponseStatusCodes({ schema }) {
 	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.
+* Returns the response object for a status code, resolving a `$ref` through `refs`. `null` when absent.
 */
 function getResponseByStatusCode({ operation, refs, statusCode }) {
 	const responses = operation.schema.responses;
-	if (!responses || isReference(responses)) return false;
-	return refs.deref(responses[statusCode]) ?? false;
+	if (!responses || isReference(responses)) return null;
+	return refs.deref(responses[statusCode]);
 }
 /**
 * Resolves the operation's request body, dereferencing a `$ref` through `refs`. Returns `null`
@@ -909,51 +885,37 @@ 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({ operation, refs }) {
-	return getRequestBody({
-		operation,
-		refs
-	})?.content;
-}
-/**
-* Returns the request body media type. With `mediaType` set, returns that entry or `false`.
-* Otherwise picks the first JSON-like media type, then the first declared one, as a
-* `[mediaType, object]` tuple.
-*/
-function getRequestContent({ operation, refs, mediaType }) {
-	const content = getRequestBodyContent({
-		operation,
-		refs
-	});
-	if (!content) return false;
-	if (mediaType) return mediaType in content ? content[mediaType] : 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({ operation, refs }) {
-	const content = getRequestBodyContent({
+	const content = getRequestBody({
 		operation,
 		refs
-	});
+	})?.content;
 	const mediaTypes = content ? Object.keys(content) : [];
 	return mediaTypes.findLast(isJsonMimeType) ?? mediaTypes[0] ?? "application/json";
 }
+/** Merges path-level and operation-level parameters; operation-level wins per `in:name`. */
+function getParameters({ operation, refs }) {
+	const resolveParams = (params) => params.map((p) => refs.derefKeepingRef(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, ...operationParams]) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	return Array.from(paramMap.values());
+}
+/** Schema for one media type of a `content` map, with the binary fallback for an emptied non-JSON entry. */
+function getBodySchema({ content, contentType, refs }) {
+	const entry = contentType ? content?.[contentType] : void 0;
+	if (!entry) return null;
+	const binary = getBinaryFallbackSchema(contentType, entry.schema);
+	if (binary) return binary;
+	return entry.schema ? refs.derefKeepingRef(entry.schema) : null;
+}
 /**
 * Builds an `Operation` for every supported HTTP method on every path, in document order.
 * `x-` path keys and unresolvable path-item `$ref`s are skipped.
-*
-* @example
-* ```ts
-* for (const operation of getOperations(document, refs)) {
-*   parseOperation(options, operation)
-* }
-* ```
 */
 function getOperations(document, refs) {
 	const operations = [];
@@ -978,32 +940,144 @@ function getOperations(document, refs) {
 	}
 	return operations;
 }
-//#endregion
-//#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`, `uint64`, `date-time`) are handled separately by parser options.
-*/
-function getSchemaType(format) {
-	return formatMap[format] ?? null;
+/** Property names whose schema has a truthy `readOnly` or `writeOnly` flag; `$ref` entries are skipped. */
+function collectPropertyKeysByFlag(schema, flag) {
+	if (!schema?.properties) return null;
+	const keys = [];
+	for (const key in schema.properties) {
+		const prop = schema.properties[key];
+		if (prop && !isReference(prop) && prop[flag]) keys.push(key);
+	}
+	return keys.length ? keys : null;
+}
+function parseParameter({ param, parentName, options, parseSchema }) {
+	const schemaName = parentName && param.name ? pascalCase(`${parentName} ${param.name}`) : void 0;
+	const schema = param.schema ? parseSchema({
+		schema: param.schema,
+		name: schemaName
+	}) : ast.factory.createSchema({ type: options.unknownType });
+	const style = param.style;
+	const explode = param.explode;
+	return ast.factory.createParameter({
+		name: param.name,
+		in: param.in,
+		schema: {
+			...schema,
+			description: param.description ?? schema.description
+		},
+		required: param.required ?? false,
+		...style !== void 0 ? { style } : {},
+		...explode !== void 0 ? { explode } : {}
+	});
 }
 /**
-* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
-* `specialCasedFormats` that `convertFormat` handles directly (int64, uint64, date-time, date, time). False means the format falls back to
-* the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
-* diagnostic in step with the parser as `formatMap` grows.
+* Converts an OAS `Operation` into an `OperationNode`.
 */
-function isHandledFormat(format) {
-	return getSchemaType(format) !== null || specialCasedFormats.has(format);
+function parseOperation({ operation, ...ctx }) {
+	const { refs, contentType, options, parseSchema } = ctx;
+	const operationId = getOperationId(operation);
+	const operationName = operationId ? pascalCase(operationId) : void 0;
+	const parameters = getParameters({
+		operation,
+		refs
+	}).map((param) => parseParameter({
+		options,
+		parseSchema,
+		param,
+		parentName: operationName
+	}));
+	const body = getRequestBody({
+		operation,
+		refs
+	});
+	const bodyRequired = body?.required === true;
+	const requestBodyName = operationName ? `${operationName}Request` : void 0;
+	const content = (contentType ? [contentType] : Object.keys(body?.content ?? {})).flatMap((ct) => {
+		const schema = getBodySchema({
+			content: body?.content,
+			contentType: ct,
+			refs
+		});
+		if (!schema) return [];
+		return [ast.factory.createContent({
+			contentType: ct,
+			schema: ast.optionality(parseSchema({
+				schema,
+				name: requestBodyName
+			}), bodyRequired),
+			keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
+		})];
+	});
+	const requestBody = content.length > 0 || body?.description ? {
+		description: body?.description,
+		required: bodyRequired || void 0,
+		content: content.length > 0 ? content : void 0
+	} : void 0;
+	const responses = getResponseStatusCodes(operation).map((statusCode) => {
+		const response = getResponseByStatusCode({
+			operation,
+			refs,
+			statusCode
+		});
+		const responseName = operationName ? `${operationName}Status${statusCode}` : void 0;
+		const parseEntrySchema = (ct) => {
+			const raw = getBodySchema({
+				content: response?.content,
+				contentType: ct,
+				refs
+			});
+			return {
+				schema: raw && Object.keys(raw).length > 0 ? parseSchema({
+					schema: raw,
+					name: responseName
+				}) : ast.factory.createSchema({ type: options.emptySchemaType }),
+				keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
+			};
+		};
+		const responseContent = (contentType ? [contentType] : Object.keys(response?.content ?? {})).map((ct) => ast.factory.createContent({
+			contentType: ct,
+			...parseEntrySchema(ct)
+		}));
+		if (responseContent.length === 0) responseContent.push(ast.factory.createContent({
+			contentType: getRequestContentType({
+				operation,
+				refs
+			}),
+			...parseEntrySchema(contentType)
+		}));
+		return ast.factory.createResponse({
+			statusCode,
+			description: response?.description,
+			content: responseContent
+		});
+	});
+	const pickDoc = (key) => {
+		const own = operation.schema[key];
+		if (typeof own === "string") return own;
+		const fallback = operation.pathItem[key];
+		return typeof fallback === "string" ? fallback : void 0;
+	};
+	return ast.factory.createOperation({
+		operationId,
+		protocol: "http",
+		method: operation.method.toUpperCase(),
+		path: operation.path,
+		tags: Array.isArray(operation.schema.tags) ? operation.schema.tags.map(String) : [],
+		summary: pickDoc("summary") || void 0,
+		description: pickDoc("description") || void 0,
+		deprecated: operation.schema.deprecated || void 0,
+		parameters,
+		requestBody,
+		responses
+	});
 }
+//#endregion
+//#region src/emit/schemaShape.ts
 /**
-* Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
-* Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
+* Whether `format` maps to a dedicated type; `false` is what `KUBB_UNSUPPORTED_FORMAT` flags.
 */
-function getPrimitiveType(type) {
-	if (type === "number" || type === "integer" || type === "bigint") return type;
-	if (type === "boolean") return "boolean";
-	return "string";
+function isHandledFormat(format) {
+	return formatMap[format] !== void 0 || specialCasedFormats.has(format);
 }
 /**
 * Resolves the `dateType` option down to the value for one format. The scalar form of
@@ -1015,51 +1089,6 @@ function resolveDateTypeValue(dateType, format) {
 	return dateType[format === "date-time" ? "dateTime" : format] ?? "string";
 }
 /**
-* Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
-* Returns `null` when the resolved value is `false`, so the format falls through to `string`.
-*/
-function getDateType(options, format) {
-	const value = resolveDateTypeValue(options.dateType, format);
-	if (!value) return null;
-	if (format === "date-time") {
-		if (value === "date") return {
-			type: "date",
-			representation: "date"
-		};
-		if (value === "stringOffset") return {
-			type: "datetime",
-			offset: true
-		};
-		if (value === "stringLocal") return {
-			type: "datetime",
-			local: true
-		};
-		return {
-			type: "datetime",
-			offset: false
-		};
-	}
-	if (format === "date") return {
-		type: "date",
-		representation: value === "date" ? "date" : "string"
-	};
-	return {
-		type: "time",
-		representation: value === "date" ? "date" : "string"
-	};
-}
-/**
-* 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 getExclusiveBounds(schema) {
-	return {
-		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
-	};
-}
-/**
 * 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`.
@@ -1068,12 +1097,6 @@ 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
-* structurally significant on its own (see `structuralKeys`).
-*
-* A fragment with a structural keyword can't be safely merged into a parent schema.
-*/
 function hasStructuralKeywords(fragment) {
 	return Object.keys(fragment).some((key) => structuralKeys.has(key));
 }
@@ -1081,23 +1104,19 @@ function hasStructuralKeywords(fragment) {
 * Flattens a keyword-only `allOf` into its parent schema.
 *
 * Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
-* (see `structuralKeys`). Outer schema values take precedence over fragment values.
-* Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
+* (see `structuralKeys`). Outer schema values take precedence over fragment values. Returns the
+* original schema unchanged when flattening is unsafe.
 *
 * @example
 * ```ts
 * flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
 * // { type: 'object', properties: {}, description: 'A pet' }
-* ```
-*
-* @example
-* ```ts
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
 * // returned unchanged, contains a $ref
 * ```
 */
 function flattenSchema(schema) {
-	if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null;
+	if (!schema.allOf?.length) return schema;
 	const allOfFragments = schema.allOf;
 	if (allOfFragments.some((item) => isReference(item))) return schema;
 	if (allOfFragments.some(hasStructuralKeywords)) return schema;
@@ -1176,7 +1195,7 @@ function findDiscriminators(mapping, ref) {
 * 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 narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parse, rawOptions, name, refs }) {
+function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parse, name, refs }) {
 	function pickDiscriminatorPropertyNode(node, propertyName) {
 		const discriminatorProperty = ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
 		if (!discriminatorProperty) return null;
@@ -1218,7 +1237,7 @@ function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode,
 		const memberNode = parse({
 			schema: s,
 			name
-		}, rawOptions);
+		});
 		if (!discriminatorValues.length || !discriminator) return memberNode;
 		const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({
 			propertyName: discriminator.propertyName,
@@ -1335,6 +1354,68 @@ function convertAnnotatedEnum(context) {
 //#endregion
 //#region src/emit/converters/composition.ts
 /**
+* Collects property schemas from all `allOf` members and outer schema properties,
+* recursively resolving `$ref` pointers.
+*/
+function collectSiblingProperties(allOfMembers, refs, outerProperties) {
+	const properties = { ...outerProperties };
+	const visited = /* @__PURE__ */ new Set();
+	function collectFrom(item) {
+		if (!item) return;
+		if (isReference(item)) {
+			if (visited.has(item.$ref)) return;
+			visited.add(item.$ref);
+			const resolved = refs.resolve(item.$ref, { report: false });
+			if (resolved && !isReference(resolved)) collectFrom(resolved);
+			return;
+		}
+		if (item.properties) Object.assign(properties, item.properties);
+		if (Array.isArray(item.allOf)) for (const member of item.allOf) collectFrom(member);
+	}
+	for (const item of allOfMembers) collectFrom(item);
+	return properties;
+}
+/**
+* Enriches union members that declare `required` properties without declaring corresponding
+* property schemas, populating the missing property definitions from available sibling schemas
+* (or an empty schema falling back to the configured emptySchemaType).
+*/
+function resolveUnionMembers(members, siblingProperties) {
+	return members.map((member) => {
+		if (!member || typeof member !== "object" || isReference(member)) return member;
+		const obj = member;
+		if (!Array.isArray(obj.required) || obj.required.length === 0) return member;
+		const existingProps = obj.properties ?? {};
+		const missingKeys = obj.required.filter((key) => !Object.prototype.hasOwnProperty.call(existingProps, key));
+		if (missingKeys.length === 0) return member;
+		const newProperties = { ...existingProps };
+		for (const key of missingKeys) {
+			const value = Object.prototype.hasOwnProperty.call(siblingProperties, key) ? siblingProperties[key] : {};
+			Object.defineProperty(newProperties, key, {
+				value,
+				enumerable: true,
+				writable: true,
+				configurable: true
+			});
+		}
+		return {
+			type: obj.type ?? "object",
+			...obj,
+			properties: newProperties
+		};
+	});
+}
+/**
+* Enriches any `oneOf` or `anyOf` branches on a schema object with properties from sibling schemas.
+*/
+function resolveUnionSchema(schema, siblingProperties) {
+	if (!schema.oneOf && !schema.anyOf) return schema;
+	const next = { ...resolveUnionMembers([schema], siblingProperties)[0] ?? schema };
+	if (schema.oneOf) next.oneOf = resolveUnionMembers(schema.oneOf, siblingProperties);
+	if (schema.anyOf) next.anyOf = resolveUnionMembers(schema.anyOf, siblingProperties);
+	return next;
+}
+/**
 * Converts a `$ref` schema into a `RefSchemaNode`.
 *
 * The resolved schema is stored in `node.schema`. Usage-site sibling fields
@@ -1342,9 +1423,9 @@ function convertAnnotatedEnum(context) {
 * Use `syncSchemaRef(node)` in printers to get a merged view of both.
 * Circular refs are detected in `refs.resolveNode` and leave `schema` as `null`.
 */
-function convertRef({ schema, name, nullable, defaultValue, rawOptions, document, parse, refs, renames }) {
+function convertRef({ schema, name, nullable, defaultValue, document, parse, refs, renames }) {
 	const refPath = schema.$ref;
-	const resolvedSchema = refPath ? refs.resolveNode(refPath, parse, rawOptions) : null;
+	const resolvedSchema = refPath ? refs.resolveNode(refPath, parse) : null;
 	const ctx = {
 		schema,
 		name,
@@ -1364,13 +1445,13 @@ 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, refs }) {
+function convertAllOf({ schema, name, nullable, defaultValue, 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({
 			schema: memberSchema,
 			name
-		}, rawOptions);
+		});
 		const { kind: _kind, ...memberNodeProps } = memberNode;
 		const mergedNullable = nullable || memberNode.nullable || void 0;
 		const mergedDefault = schema.default === null && mergedNullable ? void 0 : schema.default ?? memberNode.default;
@@ -1394,10 +1475,11 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 		name,
 		refs
 	});
-	const allOfMembers = discriminatedAllOf.map((s) => parse({
+	const siblingProperties = collectSiblingProperties(schema.allOf, refs, schema.properties);
+	const allOfMembers = discriminatedAllOf.map((s) => isReference(s) ? s : resolveUnionSchema(s, siblingProperties)).map((s) => parse({
 		schema: s,
 		name
-	}, rawOptions));
+	}));
 	const syntheticStart = allOfMembers.length;
 	if (Array.isArray(schema.required) && schema.required.length) {
 		const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : /* @__PURE__ */ new Set();
@@ -1418,7 +1500,7 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 					allOfMembers.push(parse({
 						schema: memberSchema,
 						name
-					}, rawOptions));
+					}));
 					break;
 				}
 			}
@@ -1426,7 +1508,7 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 	}
 	if (schema.properties) {
 		const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
-		allOfMembers.push(parse({ schema: schemaWithoutAllOf }, rawOptions));
+		allOfMembers.push(parse({ schema: schemaWithoutAllOf }));
 	}
 	for (const { propertyName, values } of discriminantValues) allOfMembers.push(createDiscriminantNode({
 		propertyName,
@@ -1448,14 +1530,14 @@ function convertAllOf({ schema, name, nullable, defaultValue, rawOptions, parse,
 function convertUnion(context) {
 	const annotatedEnum = convertAnnotatedEnum(context);
 	if (annotatedEnum) return annotatedEnum;
-	const { schema, name, nullable, defaultValue, rawOptions, parse, refs } = context;
+	const { schema, name, nullable, defaultValue, parse, refs } = context;
 	const ctx = {
 		schema,
 		name,
 		nullable,
 		defaultValue
 	};
-	const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
+	const unionMembers = resolveUnionMembers([...schema.oneOf ?? [], ...schema.anyOf ?? []], schema.properties ?? {});
 	const strategy = schema.oneOf ? "one" : "any";
 	const explicitDiscriminatorPropertyName = isDiscriminator(schema) ? schema.discriminator.propertyName : void 0;
 	const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
@@ -1463,14 +1545,13 @@ function convertUnion(context) {
 	const sharedPropertiesNode = schema.properties ? parse({
 		schema: memberBaseSchema,
 		name
-	}, rawOptions) : void 0;
+	}) : void 0;
 	if (sharedPropertiesNode || discriminator) {
 		const members = narrowUnionMembers({
 			unionMembers,
 			discriminator,
 			sharedPropertiesNode,
 			parse,
-			rawOptions,
 			name,
 			refs
 		});
@@ -1489,7 +1570,7 @@ function convertUnion(context) {
 	const members = unionMembers.map((s) => parse({
 		schema: s,
 		name
-	}, rawOptions));
+	}));
 	const unionNode = createNode(ctx, {
 		type: "union",
 		strategy,
@@ -1504,7 +1585,7 @@ function convertUnion(context) {
 * 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 }) {
+function convertMultiType({ schema, name, nullable, defaultValue, parse }) {
 	const types = schema.type;
 	const nonNullTypes = types.filter((t) => t !== "null");
 	return createNode({
@@ -1521,7 +1602,7 @@ function convertMultiType({ schema, name, nullable, defaultValue, rawOptions, pa
 					type: t
 				},
 				name
-			}, rawOptions);
+			});
 		})
 	});
 }
@@ -1546,6 +1627,44 @@ function normalizeArrayEnum(schema) {
 		items: normalizedItems
 	};
 }
+function getPrimitiveType(type) {
+	if (type === "number" || type === "integer" || type === "bigint") return type;
+	if (type === "boolean") return "boolean";
+	return "string";
+}
+/** Shared by number, integer and bigint nodes; the exclusive bounds keep only the OAS 3.1 numeric form. */
+function getNumericConstraints(schema) {
+	return {
+		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
+	};
+}
+function getDateType(options, format) {
+	const value = resolveDateTypeValue(options.dateType, format);
+	if (format !== "date-time") return {
+		type: format,
+		representation: value === "date" ? "date" : "string"
+	};
+	if (value === "date") return {
+		type: "date",
+		representation: "date"
+	};
+	if (value === "stringOffset") return {
+		type: "datetime",
+		offset: true
+	};
+	if (value === "stringLocal") return {
+		type: "datetime",
+		local: true
+	};
+	return {
+		type: "datetime",
+		offset: false
+	};
+}
 /**
 * 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.
@@ -1565,22 +1684,13 @@ function createNullNode(schema, name, nullable) {
 /**
 * Converts an OAS 3.1 `const` schema into a null scalar or a single-value `EnumSchemaNode`.
 */
-function convertConst({ schema, name, nullable, defaultValue }) {
+function convertConst(context) {
+	const { schema, name } = context;
 	const constValue = schema.const;
 	if (constValue === null) return createNullNode(schema, name);
-	const constPrimitive = getPrimitiveType((() => {
-		if (typeof constValue === "number") return "number";
-		if (typeof constValue === "boolean") return "boolean";
-		return "string";
-	})());
-	return createNode({
-		schema,
-		name,
-		nullable,
-		defaultValue
-	}, {
+	return createNode(context, {
 		type: "enum",
-		primitive: constPrimitive,
+		primitive: getPrimitiveType(typeof constValue),
 		enumValues: [constValue]
 	});
 }
@@ -1590,36 +1700,30 @@ function convertConst({ schema, name, nullable, defaultValue }) {
 * a date-ish format, that `dateType` is not `false`.
 */
 function convertFormat(context) {
-	const { schema, name, nullable, defaultValue, options, type } = context;
-	const ctx = {
-		schema,
-		name,
-		nullable,
-		defaultValue
-	};
+	const { schema, options, type } = context;
 	if (type === "string" && numericFormats.has(schema.format)) return convertString(context);
-	if (schema.format === "int64" || schema.format === "uint64") return createNode(ctx, {
+	if (schema.format === "int64" || schema.format === "uint64") return createNode(context, {
 		type: options.integerType === "bigint" ? "bigint" : "integer",
 		primitive: "integer",
 		...getNumericConstraints(schema)
 	});
 	if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") {
 		const dateType = getDateType(options, schema.format);
-		if (dateType.type === "datetime") return createNode(ctx, {
+		if (dateType.type === "datetime") return createNode(context, {
 			primitive: "string",
 			type: "datetime",
 			offset: dateType.offset,
 			local: dateType.local
 		});
-		return createNode(ctx, {
+		return createNode(context, {
 			primitive: "string",
 			type: dateType.type,
 			representation: dateType.representation
 		});
 	}
-	const specialType = getSchemaType(schema.format);
-	const isNumeric = specialType === "number" || specialType === "integer" || specialType === "bigint";
-	return createNode(ctx, {
+	const specialType = formatMap[schema.format];
+	const isNumeric = specialType === "number" || specialType === "integer";
+	return createNode(context, {
 		primitive: isNumeric ? specialType : "string",
 		type: specialType,
 		...specialType === "url" || specialType === "uuid" || specialType === "email" ? {
@@ -1632,11 +1736,11 @@ function convertFormat(context) {
 /**
 * Converts an `enum` schema into an `EnumSchemaNode`.
 */
-function convertEnum({ schema, name, nullable, type, rawOptions, parse }) {
+function convertEnum({ schema, name, nullable, type, parse }) {
 	if (type === "array") return parse({
 		schema: normalizeArrayEnum(schema),
 		name
-	}, rawOptions);
+	});
 	const nullInEnum = schema.enum.includes(null);
 	const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
 	if (nullInEnum && filteredValues.length === 0) return createNullNode(schema, name);
@@ -1688,13 +1792,9 @@ function convertEnum({ schema, name, nullable, type, rawOptions, parse }) {
 /**
 * Converts a `type: 'string'` schema into a `StringSchemaNode`.
 */
-function convertString({ schema, name, nullable, defaultValue }) {
-	return createNode({
-		schema,
-		name,
-		nullable,
-		defaultValue
-	}, {
+function convertString(context) {
+	const { schema } = context;
+	return createNode(context, {
 		type: "string",
 		primitive: "string",
 		min: schema.minLength,
@@ -1703,58 +1803,13 @@ function convertString({ schema, name, nullable, defaultValue }) {
 	});
 }
 /**
-* Reads the numeric constraints shared by every `number`, `integer` and `bigint` node. A `format`
-* such as `double` or `int32` only narrows the type, so formatted numbers keep these too.
-*/
-function getNumericConstraints(schema) {
-	return {
-		min: schema.minimum,
-		max: schema.maximum,
-		...getExclusiveBounds(schema),
-		multipleOf: schema.multipleOf
-	};
-}
-/**
 * Converts a `type: 'number'` or `type: 'integer'` schema.
 */
-function convertNumeric({ schema, name, nullable, defaultValue }, type) {
-	return createNode({
-		schema,
-		name,
-		nullable,
-		defaultValue
-	}, {
+function convertNumeric(context, type) {
+	return createNode(context, {
 		type,
 		primitive: type,
-		...getNumericConstraints(schema)
-	});
-}
-/**
-* Converts a `type: 'boolean'` schema.
-*/
-function convertBoolean({ schema, name, nullable, defaultValue }) {
-	return createNode({
-		schema,
-		name,
-		nullable,
-		defaultValue
-	}, {
-		type: "boolean",
-		primitive: "boolean"
-	});
-}
-/**
-* Converts a raw binary schema into a `blob` node.
-*/
-function convertBinary({ schema, name, nullable, defaultValue }) {
-	return createNode({
-		schema,
-		name,
-		nullable,
-		defaultValue
-	}, {
-		type: "blob",
-		primitive: "string"
+		...getNumericConstraints(context.schema)
 	});
 }
 //#endregion
@@ -1763,9 +1818,9 @@ function convertBinary({ schema, name, nullable, defaultValue }) {
 * 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) {
+function resolveMapSchema(mapSchema, { options, parse }) {
 	if (mapSchema === true || typeof mapSchema === "object" && Object.keys(mapSchema).length === 0) return ast.factory.createSchema({ type: options.unknownType });
-	return parse({ schema: mapSchema }, rawOptions);
+	return parse({ schema: mapSchema });
 }
 /**
 * Names the inline enums on a property's schema, and on each item when the property is a tuple, from
@@ -1787,7 +1842,7 @@ function nameEnums(node, options) {
 /**
 * Converts an object-like schema into an `ObjectSchemaNode`.
 */
-function convertObject({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+function convertObject({ schema, name, nullable, defaultValue, options, parse }) {
 	const properties = schema.properties ? Object.entries(schema.properties).map(([propName, propSchema]) => {
 		const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required;
 		const resolvedPropSchema = propSchema;
@@ -1795,7 +1850,7 @@ function convertObject({ schema, name, nullable, defaultValue, rawOptions, optio
 		const schemaNode = nameEnums(parse({
 			schema: resolvedPropSchema,
 			name: childName(name, propName)
-		}, rawOptions), {
+		}), {
 			parentName: name,
 			propName,
 			enumSuffix: options.enumSuffix
@@ -1812,11 +1867,17 @@ function convertObject({ schema, name, nullable, defaultValue, rawOptions, optio
 	const additionalProperties = schema.additionalProperties;
 	const additionalPropertiesNode = (() => {
 		if (additionalProperties === true) return true;
-		if (additionalProperties) return resolveMapSchema(additionalProperties, options, parse, rawOptions);
+		if (additionalProperties) return resolveMapSchema(additionalProperties, {
+			options,
+			parse
+		});
 		return additionalProperties;
 	})();
 	const rawPatternProperties = "patternProperties" in schema ? schema.patternProperties : void 0;
-	const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, resolveMapSchema(patternSchema, options, parse, rawOptions)])) : void 0;
+	const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, resolveMapSchema(patternSchema, {
+		options,
+		parse
+	})])) : void 0;
 	const objectNode = createNode({
 		schema,
 		name,
@@ -1846,9 +1907,9 @@ function convertObject({ schema, name, nullable, defaultValue, rawOptions, optio
 /**
 * Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
 */
-function convertTuple({ schema, name, nullable, defaultValue, rawOptions, options, 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: options.unknownType }) : parse({ schema: schema.items }, rawOptions);
+function convertTuple({ schema, name, nullable, defaultValue, options, parse }) {
+	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }));
+	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: schema.items });
 	return createNode({
 		schema,
 		name,
@@ -1866,13 +1927,13 @@ function convertTuple({ schema, name, nullable, defaultValue, rawOptions, option
 /**
 * Converts a `type: 'array'` schema into an `ArraySchemaNode`.
 */
-function convertArray({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
+function convertArray({ schema, name, nullable, defaultValue, 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,
@@ -1931,7 +1992,10 @@ const schemaRules = [
 	},
 	{
 		match: ({ schema }) => isBinary(schema),
-		convert: convertBinary
+		convert: (ctx) => createNode(ctx, {
+			type: "blob",
+			primitive: "string"
+		})
 	},
 	{
 		match: ({ schema, type }) => !type && (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0),
@@ -1971,7 +2035,10 @@ const schemaRules = [
 	},
 	{
 		match: ({ type }) => type === "boolean",
-		convert: convertBoolean
+		convert: (ctx) => createNode(ctx, {
+			type: "boolean",
+			primitive: "boolean"
+		})
 	},
 	{
 		match: ({ type }) => type === "null",
@@ -1979,95 +2046,94 @@ const schemaRules = [
 	}
 ];
 //#endregion
-//#region src/refs.ts
-const _refCache = /* @__PURE__ */ new WeakMap();
-/**
-* 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
+//#region src/parser.ts
+/**
+* Creates the schema converter bound to one OpenAPI document: `parseSchema` dispatches each
+* schema through the ordered `schemaRules` table, with the parser options merged once.
+*
+* @internal
+*/
+function createSchemaParser(ctx) {
+	const { document, refs, renames } = ctx;
+	const options = {
+		...DEFAULT_PARSER_OPTIONS,
+		...ctx.options
 	};
-	const pointer = trimmed.substring(1);
-	let docCache = _refCache.get(document);
-	if (!docCache) {
-		docCache = /* @__PURE__ */ new Map();
-		_refCache.set(document, docCache);
+	function parseSchema({ schema, name }) {
+		const flattenedSchema = flattenSchema(schema);
+		if (flattenedSchema !== schema) return parseSchema({
+			schema: flattenedSchema,
+			name
+		});
+		const nullable = isNullable(schema) || void 0;
+		const context = {
+			schema,
+			name,
+			nullable,
+			defaultValue: schema.default === null && nullable ? void 0 : schema.default,
+			type: Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") ?? schema.type[0] : schema.type,
+			options,
+			parse: parseSchema,
+			document,
+			refs,
+			renames
+		};
+		for (const rule of schemaRules) if (rule.match(context)) return rule.convert(context);
+		return createNode(context, { type: options.emptySchemaType });
 	}
-	if (docCache.has(pointer)) return {
-		applicable: true,
-		value: docCache.get(pointer)
-	};
-	const current = pointer.split("/").filter(Boolean).map((token) => globalThis.decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")).reduce((obj, key) => obj?.[key], document);
-	if (current) docCache.set(pointer, current);
-	return {
-		applicable: true,
-		value: current ?? null
-	};
+	return { parseSchema };
 }
+//#endregion
+//#region src/promoteEnums.ts
 /**
-* 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.
-*
-* @example
-* ```ts
-* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
-* ```
+* Collects inline enums to lift to the top level, keyed by the name the parser derived for them
+* (e.g. `PetStatusEnum`). An enum already defined as a top-level component is left as-is, and a
+* name that recurs maps to the first definition so each name yields one shared type.
 */
-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
+function collectInlineEnums(roots, topLevelNames) {
+	const promoted = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		const isSchemaRoot = root.kind === "Schema";
+		for (const node of ast.collect(root, { schema: (schemaNode) => schemaNode })) {
+			if (node.type !== "enum" || !node.name) continue;
+			if (isSchemaRoot && node === root) continue;
+			if (topLevelNames.has(node.name)) continue;
+			if (!promoted.has(node.name)) promoted.set(node.name, {
+				...node,
+				optional: void 0,
+				nullish: void 0
+			});
 		}
-	};
-	if (!Diagnostics.report(diagnostic)) throw new Diagnostics.Error(diagnostic);
-	return null;
+	}
+	return promoted;
 }
 /**
-* 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: { ... } }
-* ```
+* Replaces every promoted inline enum in `node` with a `ref` to its lifted definition, keeping the
+* occurrence's usage-slot and documentation fields.
 */
-function dereferenceWithRef(document, schema) {
-	if (isReference(schema)) return {
-		...schema,
-		...resolveRef(document, schema.$ref),
-		$ref: schema.$ref
-	};
-	return schema;
+function refPromotedEnums(node, promoted) {
+	if (promoted.size === 0) return node;
+	return ast.transform(node, { schema(schemaNode) {
+		if (schemaNode.type !== "enum" || !schemaNode.name || !promoted.has(schemaNode.name)) return void 0;
+		return ast.factory.createSchema({
+			type: "ref",
+			name: schemaNode.name,
+			ref: `${SCHEMA_REF_PREFIX}${schemaNode.name}`,
+			optional: schemaNode.optional,
+			nullish: schemaNode.nullish,
+			readOnly: schemaNode.readOnly,
+			writeOnly: schemaNode.writeOnly,
+			deprecated: schemaNode.deprecated,
+			description: schemaNode.description,
+			default: schemaNode.default,
+			examples: schemaNode.examples
+		});
+	} });
 }
+//#endregion
+//#region src/refs.ts
 /**
-* 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.
+* Creates the `$ref` resolution service for one document. One pointer walk backs every method.
 *
 * @example
 * ```ts
@@ -2077,12 +2143,31 @@ function dereferenceWithRef(document, schema) {
 * refs.exists('#/components/schemas/Pet')
 * refs.resolveNode('#/components/schemas/Pet', parseSchema)
 * refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+* refs.derefKeepingRef(parameter)
 * ```
 */
 function createRefs(document) {
+	const pointerCache = /* @__PURE__ */ new Map();
 	const resolvedNodeCache = /* @__PURE__ */ new Map();
-	const existenceCache = /* @__PURE__ */ new Map();
 	const resolvingRefs = /* @__PURE__ */ new Set();
+	function walkPointer($ref) {
+		const trimmed = $ref.trim();
+		if (trimmed === "" || !trimmed.startsWith("#")) return {
+			applicable: false,
+			value: null
+		};
+		const pointer = trimmed.substring(1);
+		if (pointerCache.has(pointer)) return {
+			applicable: true,
+			value: pointerCache.get(pointer)
+		};
+		const current = pointer.split("/").filter(Boolean).map((token) => globalThis.decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")).reduce((obj, key) => obj?.[key], document);
+		if (current) pointerCache.set(pointer, current);
+		return {
+			applicable: true,
+			value: current ?? null
+		};
+	}
 	/**
 	* 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
@@ -2090,27 +2175,36 @@ function createRefs(document) {
 	* for a speculative lookup where a missing ref is not an error.
 	*/
 	function resolve(refPath, options) {
-		if (options?.report === false) {
-			const { applicable, value } = walkPointer(document, refPath);
-			return applicable ? value : null;
-		}
-		return resolveRef(document, refPath);
+		const { applicable, value } = walkPointer(refPath);
+		if (!applicable || value || options?.report === false) return value;
+		const diagnostic = {
+			code: Diagnostics.code.refNotFound,
+			severity: "error",
+			message: `Could not find a definition for ${refPath}.`,
+			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+			location: {
+				kind: "schema",
+				pointer: refPath,
+				ref: refPath
+			}
+		};
+		if (!Diagnostics.report(diagnostic)) throw new Diagnostics.Error(diagnostic);
+		return null;
 	}
 	/**
 	* 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. Memoized.
+	* goes `false` for a `$ref` that points at a component the spec never declares.
 	*/
 	function exists(refPath) {
-		if (!existenceCache.has(refPath)) existenceCache.set(refPath, !!resolve(refPath, { report: false }));
-		return existenceCache.get(refPath) ?? false;
+		return !!resolve(refPath, { report: false });
 	}
 	/**
 	* 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 resolveNode(refPath, parse, rawOptions) {
+	function resolveNode(refPath, parse) {
 		if (resolvingRefs.has(refPath)) return null;
 		if (!resolvedNodeCache.has(refPath)) {
 			let resolved = null;
@@ -2118,7 +2212,7 @@ function createRefs(document) {
 				const referenced = resolve(refPath);
 				if (referenced) {
 					resolvingRefs.add(refPath);
-					resolved = parse({ schema: referenced }, rawOptions);
+					resolved = parse({ schema: referenced });
 					resolvingRefs.delete(refPath);
 				}
 			} catch {}
@@ -2131,399 +2225,30 @@ function createRefs(document) {
 	* 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;
 	}
+	/** Resolves a `$ref` object but keeps the `$ref` field on the result; other values pass through. */
+	function derefKeepingRef(value) {
+		if (isReference(value)) return {
+			...value,
+			...resolve(value.$ref),
+			$ref: value.$ref
+		};
+		return value;
+	}
 	return {
 		resolve,
 		exists,
 		resolveNode,
-		deref
+		deref,
+		derefKeepingRef
 	};
 }
 //#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 ? [contentType, body.content[contentType]] : false;
-	return pickContentEntry(body.content);
-}
-/**
-* 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 [mediaType, entry] = responseBody;
-	const schema = entry.schema;
-	const binary = getBinaryFallbackSchema(mediaType, schema);
-	if (binary) return binary;
-	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;
-	const binary = getBinaryFallbackSchema(mediaType, schema);
-	if (binary) return binary;
-	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`.
-	*
-	* Builds the per-schema context, then walks the ordered {@link schemaRules} table and returns
-	* the first converter that produces a node. When none match, falls back to the configured
-	* `emptySchemaType`.
-	*/
-	function parseSchema({ schema, name }, rawOptions) {
-		const options = {
-			...DEFAULT_PARSER_OPTIONS,
-			...rawOptions
-		};
-		const flattenedSchema = flattenSchema(schema);
-		if (flattenedSchema && flattenedSchema !== schema) return parseSchema({
-			schema: flattenedSchema,
-			name
-		}, rawOptions);
-		const nullable = isNullable(schema) || void 0;
-		const context = {
-			schema,
-			name,
-			nullable,
-			defaultValue: schema.default === null && nullable ? void 0 : schema.default,
-			type: Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") ?? schema.type[0] : schema.type,
-			rawOptions,
-			options,
-			parse: parseSchema,
-			document,
-			refs,
-			renames: ctx.renames
-		};
-		for (const rule of schemaRules) if (rule.match(context)) return rule.convert(context);
-		const emptyType = options.emptySchemaType;
-		return ast.factory.createSchema({
-			type: emptyType,
-			name,
-			title: schema.title,
-			description: schema.description,
-			format: schema.format
-		});
-	}
-	/**
-	* Converts a dereferenced OAS parameter object into a `ParameterNode`.
-	*/
-	function parseParameter(options, param, parentName) {
-		const required = param["required"] ?? false;
-		const paramName = param["name"];
-		const schemaName = parentName && paramName ? pascalCase(`${parentName} ${paramName}`) : void 0;
-		const schema = param["schema"] ? parseSchema({
-			schema: param["schema"],
-			name: schemaName
-		}, options) : ast.factory.createSchema({ type: options.unknownType });
-		const style = param["style"];
-		const explode = param["explode"];
-		return ast.factory.createParameter({
-			name: paramName,
-			in: param["in"],
-			schema: {
-				...schema,
-				description: param["description"] ?? schema.description
-			},
-			required,
-			...style !== void 0 ? { style } : {},
-			...explode !== void 0 ? { explode } : {}
-		});
-	}
-	/**
-	* Reads the inline `requestBody` metadata (description / required) that OAS exposes
-	* 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 = getRequestBody({
-			operation,
-			refs
-		});
-		if (!body) return { required: false };
-		return {
-			description: body.description,
-			required: body.required === true
-		};
-	}
-	/**
-	* Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
-	* `$ref` entries are skipped since their flags live on the dereferenced target.
-	*/
-	function collectPropertyKeysByFlag(schema, flag) {
-		if (!schema?.properties) return null;
-		const keys = [];
-		for (const key in schema.properties) {
-			const prop = schema.properties[key];
-			if (prop && !isReference(prop) && prop[flag]) keys.push(key);
-		}
-		return keys.length ? keys : null;
-	}
-	/**
-	* Converts an OAS `Operation` into an `OperationNode`.
-	*/
-	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(operation, refs);
-		const requestBodyMeta = getRequestBodyMeta(operation);
-		const requestBodyName = operationName ? `${operationName}Request` : void 0;
-		const content = allContentTypes.flatMap((ct) => {
-			const schema = getRequestSchema({
-				document,
-				operation,
-				refs,
-				options: { contentType: ct }
-			});
-			if (!schema) return [];
-			return [ast.factory.createContent({
-				contentType: ct,
-				schema: ast.optionality(parseSchema({
-					schema,
-					name: requestBodyName
-				}, options), requestBodyMeta.required),
-				keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
-			})];
-		});
-		const requestBody = content.length > 0 || requestBodyMeta.description ? {
-			description: requestBodyMeta.description,
-			required: requestBodyMeta.required || void 0,
-			content: content.length > 0 ? content : void 0
-		} : void 0;
-		const responses = getResponseStatusCodes(operation).map((statusCode) => {
-			const responseObj = getResponseByStatusCode({
-				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,
-					refs,
-					statusCode,
-					options: { contentType }
-				});
-				return {
-					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
-						schema: raw,
-						name: responseName
-					}, options) : ast.factory.createSchema({ type: options.emptySchemaType }),
-					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
-				};
-			};
-			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({
-					operation,
-					refs
-				}) || "application/json",
-				...parseEntrySchema(ctx.contentType)
-			}));
-			return ast.factory.createResponse({
-				statusCode,
-				description,
-				content
-			});
-		});
-		const pickDoc = (key) => {
-			const own = operation.schema[key];
-			if (typeof own === "string") return own;
-			const fallback = operation.pathItem[key];
-			return typeof fallback === "string" ? fallback : void 0;
-		};
-		return ast.factory.createOperation({
-			operationId,
-			protocol: "http",
-			method: operation.method.toUpperCase(),
-			path: operation.path,
-			tags: Array.isArray(operation.schema.tags) ? operation.schema.tags.map(String) : [],
-			summary: pickDoc("summary") || void 0,
-			description: pickDoc("description") || void 0,
-			deprecated: operation.schema.deprecated || void 0,
-			parameters,
-			requestBody,
-			responses
-		});
-	}
-	return {
-		parseSchema,
-		parseOperation,
-		parseParameter
-	};
-}
-//#endregion
-//#region src/promoteEnums.ts
-/**
-* Collects inline enums to lift to the top level, keyed by the name the parser derived for them
-* (e.g. `PetStatusEnum`). An enum already defined as a top-level component is left as-is, and a
-* name that recurs maps to the first definition so each name yields one shared type.
-*/
-function collectInlineEnums(roots, topLevelNames) {
-	const promoted = /* @__PURE__ */ new Map();
-	for (const root of roots) {
-		const isSchemaRoot = root.kind === "Schema";
-		for (const node of ast.collect(root, { schema: (schemaNode) => schemaNode })) {
-			if (node.type !== "enum" || !node.name) continue;
-			if (isSchemaRoot && node === root) continue;
-			if (topLevelNames.has(node.name)) continue;
-			if (!promoted.has(node.name)) promoted.set(node.name, {
-				...node,
-				optional: void 0,
-				nullish: void 0
-			});
-		}
-	}
-	return promoted;
-}
-/**
-* Replaces every promoted inline enum in `node` with a `ref` to its lifted definition, keeping the
-* occurrence's usage-slot and documentation fields.
-*/
-function refPromotedEnums(node, promoted) {
-	if (promoted.size === 0) return node;
-	return ast.transform(node, { schema(schemaNode) {
-		if (schemaNode.type !== "enum" || !schemaNode.name || !promoted.has(schemaNode.name)) return void 0;
-		return ast.factory.createSchema({
-			type: "ref",
-			name: schemaNode.name,
-			ref: `${SCHEMA_REF_PREFIX}${schemaNode.name}`,
-			optional: schemaNode.optional,
-			nullish: schemaNode.nullish,
-			readOnly: schemaNode.readOnly,
-			writeOnly: schemaNode.writeOnly,
-			deprecated: schemaNode.deprecated,
-			description: schemaNode.description,
-			default: schemaNode.default,
-			examples: schemaNode.examples
-		});
-	} });
-}
-//#endregion
 //#region src/schemaDiagnostics.ts
 /**
 * Scans one freshly converted top-level schema in a single walk, so the post-convert pass never
@@ -2550,7 +2275,7 @@ function escapePointerToken(token) {
 }
 function visit(node, pointer, refs) {
 	if (node.type === "ref") {
-		const refName = resolveRefName(node);
+		const refName = ast.resolveRefName(node);
 		if (refName) refs.add(refName);
 	}
 	if (node.deprecated) Diagnostics.report({
@@ -2623,17 +2348,24 @@ const adapterOasName = "oas";
 const adapterOas = createAdapter((options) => {
 	const { validate = true, contentType, server, discriminator = "preserve", enums = "inline", dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
 	const parserOptions = {
-		...DEFAULT_PARSER_OPTIONS,
 		dateType,
 		integerType,
 		unknownType,
 		emptySchemaType,
 		enumSuffix
 	};
+	const resolvedOptions = {
+		validate,
+		contentType,
+		server,
+		discriminator,
+		enums,
+		...parserOptions
+	};
 	let parsedDocument = null;
 	const inputCache = /* @__PURE__ */ new WeakMap();
 	function parseInput({ document, refs, schemas, parser }) {
-		const { parseSchema, parseOperation } = parser;
+		const { parseSchema } = parser;
 		const parsedByName = /* @__PURE__ */ new Map();
 		const refAliasMap = /* @__PURE__ */ new Map();
 		const enumNames = [];
@@ -2643,7 +2375,7 @@ const adapterOas = createAdapter((options) => {
 			const node = parseSchema({
 				schema,
 				name
-			}, parserOptions);
+			});
 			parsedByName.set(name, node);
 			const refs = scanSchema({
 				node,
@@ -2651,29 +2383,31 @@ const adapterOas = createAdapter((options) => {
 			});
 			if (node.name) refGraph.set(node.name, refs);
 			if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
-			if (narrowSchema(node, "enum") && node.name) enumNames.push(node.name);
+			if (ast.narrowSchema(node, "enum") && node.name) enumNames.push(node.name);
 			if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
 		}
-		const circularNames = [...findCircularSchemasFromGraph(refGraph)];
+		const circularNames = [...ast.findCircularSchemasFromGraph(refGraph)];
 		const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null;
-		const operationNodes = [];
-		for (const operation of getOperations(document, refs)) {
-			const operationNode = parseOperation(parserOptions, operation);
-			if (operationNode) operationNodes.push(operationNode);
-		}
+		const operationNodes = getOperations(document, refs).map((operation) => parseOperation({
+			operation,
+			refs,
+			contentType,
+			options: parserOptions,
+			parseSchema
+		}));
 		const promotedEnums = enums === "root" ? collectInlineEnums([...parsedByName.values(), ...operationNodes], new Set(Object.keys(schemas))) : null;
 		if (promotedEnums) for (const name of promotedEnums.keys()) enumNames.push(name);
 		const schemaNodes = promotedEnums ? [...promotedEnums.values()] : [];
 		for (const name of Object.keys(schemas)) {
-			const alias = refAliasMap.get(name);
-			const node = alias?.name && parsedByName.has(alias.name) ? {
-				...parsedByName.get(alias.name),
+			const aliasTarget = refAliasMap.get(name)?.name;
+			const aliased = aliasTarget ? parsedByName.get(aliasTarget) : void 0;
+			const parsed = parsedByName.get(name);
+			const child = discriminatorChildMap?.get(name);
+			const base = child ? patchDiscriminatorNode(parsed, child) : parsed;
+			const node = aliased ? {
+				...aliased,
 				name
-			} : (() => {
-				const parsed = parsedByName.get(name);
-				const child = discriminatorChildMap?.get(name);
-				return child ? patchDiscriminatorNode(parsed, child) : parsed;
-			})();
+			} : base;
 			schemaNodes.push(promotedEnums ? refPromotedEnums(node, promotedEnums) : node);
 		}
 		const operations = promotedEnums ? operationNodes.map((node) => refPromotedEnums(node, promotedEnums)) : operationNodes;
@@ -2695,20 +2429,7 @@ const adapterOas = createAdapter((options) => {
 	}
 	return {
 		name: "oas",
-		get options() {
-			return {
-				validate,
-				contentType,
-				server,
-				discriminator,
-				enums,
-				dateType,
-				integerType,
-				unknownType,
-				emptySchemaType,
-				enumSuffix
-			};
-		},
+		options: resolvedOptions,
 		get document() {
 			return parsedDocument;
 		},
@@ -2737,8 +2458,8 @@ const adapterOas = createAdapter((options) => {
 					parser: createSchemaParser({
 						document,
 						refs,
-						contentType,
-						renames
+						renames,
+						options: parserOptions
 					})
 				});
 			})();