@kubb/adapter-oas 5.0.0-alpha.5 → 5.0.0-alpha.50

package/dist/index.js

@@ -1,37 +1,211 @@
 import "./chunk--u3MIqq1.js";
+import { ast, createAdapter } from "@kubb/core";
 import path from "node:path";
-import { collect, createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from "@kubb/ast";
-import { defineAdapter } from "@kubb/core";
 import { bundle, loadConfig } from "@redocly/openapi-core";
-import yaml from "@stoplight/yaml";
-import { isRef } from "oas/types";
 import OASNormalize from "oas-normalize";
-import { isPlainObject, mergeDeep } from "remeda";
 import swagger2openapi from "swagger2openapi";
-import jsonpointer from "jsonpointer";
 import BaseOas from "oas";
+import { isRef } from "oas/types";
 import { matchesMimeType } from "oas/utils";
-//#region src/oas/resolveServerUrl.ts
+//#region src/constants.ts
 /**
-* Resolves an OpenAPI server URL by substituting `{variable}` placeholders.
+* Default parser options applied when no explicit options are provided.
 *
-* Resolution priority per variable:
-* 1. `overrides[key]` — caller-supplied value.
-* 2. `variable.default` — spec-defined default, coerced to `string`.
-* 3. Variable is left unreplaced when neither is available.
+* @example
+* ```ts
+* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
 *
-* Throws when an `overrides` value is not present in the variable's `enum` list.
+* const parser = createOasParser(oas)
+* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+* ```
 */
-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 Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`);
-		url = url.replaceAll(`{${key}}`, value);
+const DEFAULT_PARSER_OPTIONS = {
+	dateType: "string",
+	integerType: "number",
+	unknownType: "any",
+	emptySchemaType: "any",
+	enumSuffix: "enum"
+};
+/**
+* JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+*
+* Used when building or parsing `$ref` strings.
+*
+* @example
+* ```ts
+* `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+* ```
+*/
+const SCHEMA_REF_PREFIX = "#/components/schemas/";
+/**
+* OpenAPI version string written into the stub document created during multi-spec merges.
+*/
+const MERGE_OPENAPI_VERSION = "3.0.0";
+/**
+* Fallback `info.title` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_TITLE = "Merged API";
+/**
+* Fallback `info.version` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_VERSION = "1.0.0";
+/**
+* Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
+*
+* A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
+* intersection member rather than being merged into the parent.
+*
+* @example
+* ```ts
+* import { structuralKeys } from '@kubb/adapter-oas'
+*
+* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
+* // true when fragment has e.g. 'properties' or 'oneOf'
+* ```
+*/
+const structuralKeys = new Set([
+	"properties",
+	"items",
+	"additionalProperties",
+	"oneOf",
+	"anyOf",
+	"allOf",
+	"not"
+]);
+/**
+* Static map from OAS `format` strings to Kubb `SchemaType` values.
+*
+* Only formats whose AST type differs from the OAS `type` field appear here.
+* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
+* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
+* `idn-hostname` map to `'url'` as the closest generic string-format type.
+*
+* @example
+* ```ts
+* import { formatMap } from '@kubb/adapter-oas'
+*
+* formatMap['uuid']   // 'uuid'
+* formatMap['binary'] // 'blob'
+* formatMap['float']  // 'number'
+* ```
+*/
+const formatMap = {
+	uuid: "uuid",
+	email: "email",
+	"idn-email": "email",
+	uri: "url",
+	"uri-reference": "url",
+	url: "url",
+	ipv4: "ipv4",
+	ipv6: "ipv6",
+	hostname: "url",
+	"idn-hostname": "url",
+	binary: "blob",
+	byte: "blob",
+	int32: "integer",
+	float: "number",
+	double: "number"
+};
+/**
+* Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
+*
+* @example
+* ```ts
+* import { enumExtensionKeys } from '@kubb/adapter-oas'
+*
+* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
+* ```
+*/
+const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
+/**
+* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
+* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+*/
+const typeOptionMap = new Map([
+	["any", ast.schemaTypes.any],
+	["unknown", ast.schemaTypes.unknown],
+	["void", ast.schemaTypes.void]
+]);
+//#endregion
+//#region src/discriminator.ts
+/**
+* Injects discriminator enum values into child schemas so they know which value identifies them.
+*
+* Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
+* enum value each union member is mapped to, then adds (or replaces) that property on the matching
+* child object schema.
+*
+* Returns a new `InputNode` — the original is never mutated.
+*
+* @example
+* ```ts
+* const { root } = parseOas(document, options)
+* const next = applyDiscriminatorInheritance(root)
+* ```
+*/
+function applyDiscriminatorInheritance(root) {
+	const childMap = /* @__PURE__ */ new Map();
+	for (const schema of root.schemas) {
+		let unionNode = ast.narrowSchema(schema, "union");
+		if (!unionNode) {
+			const intersectionMembers = ast.narrowSchema(schema, "intersection")?.members;
+			if (intersectionMembers) for (const m of intersectionMembers) {
+				const u = ast.narrowSchema(m, "union");
+				if (u) {
+					unionNode = u;
+					break;
+				}
+			}
+		}
+		if (!unionNode?.discriminatorPropertyName || !unionNode.members) continue;
+		const { discriminatorPropertyName, members } = unionNode;
+		for (const member of members) {
+			const intersectionNode = ast.narrowSchema(member, "intersection");
+			if (!intersectionNode?.members) continue;
+			let refNode;
+			let objNode;
+			for (const m of intersectionNode.members) {
+				refNode ??= ast.narrowSchema(m, "ref");
+				objNode ??= ast.narrowSchema(m, "object");
+			}
+			if (!refNode?.name || !objNode) continue;
+			const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName);
+			const enumNode = prop ? ast.narrowSchema(prop.schema, "enum") : void 0;
+			if (!enumNode?.enumValues?.length) continue;
+			const enumValues = enumNode.enumValues.filter((v) => v !== null);
+			if (!enumValues.length) continue;
+			const existing = childMap.get(refNode.name);
+			if (existing) existing.enumValues.push(...enumValues);
+			else childMap.set(refNode.name, {
+				propertyName: discriminatorPropertyName,
+				enumValues: [...enumValues]
+			});
+		}
 	}
-	return url;
+	if (childMap.size === 0) return root;
+	return ast.transform(root, { schema(node, { parent }) {
+		if (parent?.kind !== "Input" || !node.name) return;
+		const entry = childMap.get(node.name);
+		if (!entry) return;
+		const objectNode = ast.narrowSchema(node, "object");
+		if (!objectNode) return;
+		const { propertyName, enumValues } = entry;
+		const enumSchema = ast.createSchema({
+			type: "enum",
+			enumValues
+		});
+		const newProp = ast.createProperty({
+			name: propertyName,
+			required: true,
+			schema: enumSchema
+		});
+		const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName);
+		const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => i === existingIdx ? newProp : p) : [...objectNode.properties, newProp];
+		return {
+			...objectNode,
+			properties: newProperties
+		};
+	} });
 }
 //#endregion
 //#region ../../internals/utils/src/casing.ts
@@ -53,10 +227,19 @@ function toCamelOrPascal(text, pascal) {
 * Splits `text` on `.` and applies `transformPart` to each segment.
 * The last segment receives `isLast = true`, all earlier segments receive `false`.
 * Segments are joined with `/` to form a file path.
+*
+* Only splits on dots followed by a letter so that version numbers
+* embedded in operationIds (e.g. `v2025.0`) are kept intact.
+*
+* Empty segments are filtered before joining. They arise when the text starts with
+* a dot followed immediately by a letter (e.g. `..Schema` splits into `['..', 'Schema']`
+* and `'..'` transforms to an empty string). Without this filter the join would produce
+* a leading `/`, which `path.resolve` would interpret as an absolute path, allowing
+* generated files to escape the configured output directory.
 */
 function applyToFileParts(text, transformPart) {
-	const parts = text.split(".");
-	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).join("/");
+	const parts = text.split(/\.(?=[a-zA-Z])/);
+	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).filter(Boolean).join("/");
 }
 /**
 * Converts `text` to camelCase.
@@ -89,9 +272,50 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/object.ts
+/**
+* Returns `true` when `value` is a plain (non-null, non-array) object.
+*
+* @example
+* ```ts
+* isPlainObject({})          // true
+* isPlainObject([])          // false
+* isPlainObject(null)        // false
+* ```
+*/
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype;
+}
+/**
+* Recursively merges `source` into `target`, combining nested plain objects.
+* Arrays and non-object values from `source` override the corresponding values in `target`.
+*
+* @example
+* ```ts
+* mergeDeep({ a: { x: 1 } }, { a: { y: 2 } })
+* // { a: { x: 1, y: 2 } }
+* ```
+*/
+function mergeDeep(target, source) {
+	const result = { ...target };
+	for (const key of Object.keys(source)) {
+		const sv = source[key];
+		const tv = result[key];
+		result[key] = sv !== null && typeof sv === "object" && !Array.isArray(sv) && tv !== null && typeof tv === "object" && !Array.isArray(tv) ? mergeDeep(tv, sv) : sv;
+	}
+	return result;
+}
+//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * Returns `true` when `name` is a syntactically valid JavaScript variable name.
+*
+* @example
+* ```ts
+* isValidVarName('status')  // true
+* isValidVarName('class')   // false (reserved word)
+* isValidVarName('42foo')   // false (starts with digit)
+* ```
 */
 function isValidVarName(name) {
 	try {
@@ -112,18 +336,33 @@ function isValidVarName(name) {
 * p.template // '`/pet/${petId}`'
 */
 var URLPath = class {
-	/** The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`. */
+	/**
+	* The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
+	*/
 	path;
 	#options;
 	constructor(path, options = {}) {
 		this.path = path;
 		this.#options = options;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
+	* ```
+	*/
 	get URL() {
 		return this.toURLPath();
 	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`). */
+	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
+	*
+	* @example
+	* ```ts
+	* new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
+	* new URLPath('/pet/{petId}').isURL                       // false
+	* ```
+	*/
 	get isURL() {
 		try {
 			return !!new URL(this.path).href;
@@ -141,11 +380,25 @@ var URLPath = class {
 	get template() {
 		return this.toTemplateString();
 	}
-	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set. */
+	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').object
+	* // { url: '/pet/:petId', params: { petId: 'petId' } }
+	* ```
+	*/
 	get object() {
 		return this.toObject();
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters. */
+	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
+	* new URLPath('/pet').params         // undefined
+	* ```
+	*/
 	get params() {
 		return this.getParams();
 	}
@@ -153,7 +406,9 @@ var URLPath = class {
 		const param = isValidVarName(raw) ? raw : camelCase(raw);
 		return this.#options.casing === "camelcase" ? camelCase(param) : param;
 	}
-	/** Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name. */
+	/**
+	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	*/
 	#eachParam(fn) {
 		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
 			const raw = match[1];
@@ -190,6 +445,12 @@ var URLPath = class {
 	* Extracts all `{param}` segments from the path and returns them as a key-value map.
 	* An optional `replacer` transforms each parameter name in both key and value positions.
 	* Returns `undefined` when no path parameters are found.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}/tag/{tagId}').getParams()
+	* // { petId: 'petId', tagId: 'tagId' }
+	* ```
 	*/
 	getParams(replacer) {
 		const params = {};
@@ -199,439 +460,28 @@ var URLPath = class {
 		});
 		return Object.keys(params).length > 0 ? params : void 0;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+	/** Converts the OpenAPI path to Express-style colon syntax.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
+	* ```
+	*/
 	toURLPath() {
 		return this.path.replace(/\{([^}]+)\}/g, ":$1");
 	}
 };
 //#endregion
-//#region src/constants.ts
-/**
-* OpenAPI version string written into merged document stubs.
-*/
-const MERGE_OPENAPI_VERSION = "3.0.0";
-/**
-* Fallback `info.title` used when merging multiple API documents.
-*/
-const MERGE_DEFAULT_TITLE = "Merged API";
-/**
-* Fallback `info.version` used when merging multiple API documents.
-*/
-const MERGE_DEFAULT_VERSION = "1.0.0";
-/**
-* JSON Schema keywords that indicate structural composition.
-* A schema fragment containing any of these keys must not be inlined into its
-* parent during `allOf` flattening — it carries semantic meaning of its own.
-*/
-const structuralKeys = new Set([
-	"properties",
-	"items",
-	"additionalProperties",
-	"oneOf",
-	"anyOf",
-	"allOf",
-	"not"
-]);
+//#region src/guards.ts
 /**
-* Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
-*
-* Only formats that need a type different from the raw OAS `type` are listed.
-* `int64`, `date-time`, `date`, and `time` are handled separately because their
-* mapping depends on runtime parser options.
+* Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
 *
-* Note: `ipv4`, `ipv6`, and `hostname` map to `'url'` — the closest supported
-* scalar type in the Kubb AST, even though these are not strictly URLs.
-*/
-const formatMap = {
-	uuid: "uuid",
-	email: "email",
-	"idn-email": "email",
-	uri: "url",
-	"uri-reference": "url",
-	url: "url",
-	ipv4: "url",
-	ipv6: "url",
-	hostname: "url",
-	"idn-hostname": "url",
-	binary: "blob",
-	byte: "blob",
-	int32: "integer",
-	float: "number",
-	double: "number"
-};
-/**
-* Exhaustive list of media types that Kubb recognizes.
-* Kept as a module-level constant to avoid re-allocating the array on every call.
-*/
-const knownMediaTypes = [
-	"application/json",
-	"application/xml",
-	"application/x-www-form-urlencoded",
-	"application/octet-stream",
-	"application/pdf",
-	"application/zip",
-	"application/graphql",
-	"multipart/form-data",
-	"text/plain",
-	"text/html",
-	"text/csv",
-	"text/xml",
-	"image/png",
-	"image/jpeg",
-	"image/gif",
-	"image/webp",
-	"image/svg+xml",
-	"audio/mpeg",
-	"video/mp4"
-];
-/**
-* Vendor extension keys used to attach human-readable labels to enum values.
-* Checked in priority order: the first key found wins.
-*/
-const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
-//#endregion
-//#region src/oas/Oas.ts
-/**
-* Prefix used to create synthetic `$ref` values for anonymous (inline) discriminator schemas.
-* The suffix is the schema index within the discriminator's `oneOf`/`anyOf` array.
-* @example `#kubb-inline-0`
-*/
-const KUBB_INLINE_REF_PREFIX = "#kubb-inline-";
-var Oas = class extends BaseOas {
-	#options = { discriminator: "strict" };
-	document;
-	constructor(document) {
-		super(document, void 0);
-		this.document = document;
-	}
-	setOptions(options) {
-		this.#options = {
-			...this.#options,
-			...options
-		};
-		if (this.#options.discriminator === "inherit") this.#applyDiscriminatorInheritance();
-	}
-	get options() {
-		return this.#options;
-	}
-	get($ref) {
-		const origRef = $ref;
-		$ref = $ref.trim();
-		if ($ref === "") return null;
-		if ($ref.startsWith("#")) $ref = globalThis.decodeURIComponent($ref.substring(1));
-		else return null;
-		const current = jsonpointer.get(this.api, $ref);
-		if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
-		return current;
-	}
-	getKey($ref) {
-		const key = $ref.split("/").pop();
-		return key === "" ? void 0 : key;
-	}
-	set($ref, value) {
-		$ref = $ref.trim();
-		if ($ref === "") return false;
-		if ($ref.startsWith("#")) {
-			$ref = globalThis.decodeURIComponent($ref.substring(1));
-			jsonpointer.set(this.api, $ref, value);
-		}
-	}
-	#setDiscriminator(schema) {
-		const { mapping = {}, propertyName } = schema.discriminator;
-		if (this.#options.discriminator === "inherit") Object.entries(mapping).forEach(([mappingKey, mappingValue]) => {
-			if (mappingValue) {
-				const childSchema = this.get(mappingValue);
-				if (!childSchema) return;
-				if (!childSchema.properties) childSchema.properties = {};
-				const property = childSchema.properties[propertyName];
-				if (childSchema.properties) {
-					childSchema.properties[propertyName] = {
-						...childSchema.properties ? childSchema.properties[propertyName] : {},
-						enum: [...property?.enum?.filter((value) => value !== mappingKey) ?? [], mappingKey]
-					};
-					childSchema.required = typeof childSchema.required === "boolean" ? childSchema.required : [...new Set([...childSchema.required ?? [], propertyName])];
-					this.set(mappingValue, childSchema);
-				}
-			}
-		});
-	}
-	getDiscriminator(schema) {
-		if (!isDiscriminator(schema) || !schema) return null;
-		const { mapping = {}, propertyName } = schema.discriminator;
-		/**
-		* Helper to extract discriminator value from a schema.
-		* Checks in order:
-		* 1. Extension property matching propertyName (e.g., x-linode-ref-name)
-		* 2. Property with const value
-		* 3. Property with single enum value
-		* 4. Title as fallback
-		*/
-		const getDiscriminatorValue = (schema) => {
-			if (!schema) return null;
-			if (propertyName.startsWith("x-")) {
-				const extensionValue = schema[propertyName];
-				if (extensionValue && typeof extensionValue === "string") return extensionValue;
-			}
-			const propertySchema = schema.properties?.[propertyName];
-			if (propertySchema && "const" in propertySchema && propertySchema.const !== void 0) return String(propertySchema.const);
-			if (propertySchema && propertySchema.enum?.length === 1) return String(propertySchema.enum[0]);
-			return schema.title || null;
-		};
-		/**
-		* Process oneOf/anyOf items to build mapping.
-		* Handles both $ref and inline schemas.
-		*/
-		const processSchemas = (schemas, existingMapping) => {
-			schemas.forEach((schemaItem, index) => {
-				if (isReference(schemaItem)) {
-					const key = this.getKey(schemaItem.$ref);
-					try {
-						const discriminatorValue = getDiscriminatorValue(this.get(schemaItem.$ref));
-						const canAdd = key && !Object.values(existingMapping).includes(schemaItem.$ref);
-						if (canAdd && discriminatorValue) existingMapping[discriminatorValue] = schemaItem.$ref;
-						else if (canAdd) existingMapping[key] = schemaItem.$ref;
-					} catch (_error) {
-						if (key && !Object.values(existingMapping).includes(schemaItem.$ref)) existingMapping[key] = schemaItem.$ref;
-					}
-				} else {
-					const discriminatorValue = getDiscriminatorValue(schemaItem);
-					if (discriminatorValue) existingMapping[discriminatorValue] = `${KUBB_INLINE_REF_PREFIX}${index}`;
-				}
-			});
-		};
-		if (schema.oneOf) processSchemas(schema.oneOf, mapping);
-		if (schema.anyOf) processSchemas(schema.anyOf, mapping);
-		return {
-			...schema.discriminator,
-			mapping
-		};
-	}
-	dereferenceWithRef(schema) {
-		if (isReference(schema)) return {
-			...schema,
-			...this.get(schema.$ref),
-			$ref: schema.$ref
-		};
-		return schema;
-	}
-	#applyDiscriminatorInheritance() {
-		const components = this.api.components;
-		if (!components?.schemas) return;
-		const visited = /* @__PURE__ */ new WeakSet();
-		const enqueue = (value) => {
-			if (!value) return;
-			if (Array.isArray(value)) {
-				for (const item of value) enqueue(item);
-				return;
-			}
-			if (typeof value === "object") visit(value);
-		};
-		const visit = (schema) => {
-			if (!schema || typeof schema !== "object") return;
-			if (isReference(schema)) {
-				visit(this.get(schema.$ref));
-				return;
-			}
-			const schemaObject = schema;
-			if (visited.has(schemaObject)) return;
-			visited.add(schemaObject);
-			if (isDiscriminator(schemaObject)) this.#setDiscriminator(schemaObject);
-			if ("allOf" in schemaObject) enqueue(schemaObject.allOf);
-			if ("oneOf" in schemaObject) enqueue(schemaObject.oneOf);
-			if ("anyOf" in schemaObject) enqueue(schemaObject.anyOf);
-			if ("not" in schemaObject) enqueue(schemaObject.not);
-			if ("items" in schemaObject) enqueue(schemaObject.items);
-			if ("prefixItems" in schemaObject) enqueue(schemaObject.prefixItems);
-			if (schemaObject.properties) enqueue(Object.values(schemaObject.properties));
-			if (schemaObject.additionalProperties && typeof schemaObject.additionalProperties === "object") enqueue(schemaObject.additionalProperties);
-		};
-		for (const schema of Object.values(components.schemas)) visit(schema);
-	}
-	/**
-	* Oas does not have a getResponseBody(contentType)
-	*/
-	#getResponseBodyFactory(responseBody) {
-		function hasResponseBody(res = responseBody) {
-			return !!res;
-		}
-		return (contentType) => {
-			if (!hasResponseBody(responseBody)) return false;
-			if (isReference(responseBody)) return false;
-			if (!responseBody.content) return false;
-			if (contentType) {
-				if (!(contentType in responseBody.content)) return false;
-				return responseBody.content[contentType];
-			}
-			let availableContentType;
-			const contentTypes = Object.keys(responseBody.content);
-			contentTypes.forEach((mt) => {
-				if (!availableContentType && matchesMimeType.json(mt)) availableContentType = mt;
-			});
-			if (!availableContentType) contentTypes.forEach((mt) => {
-				if (!availableContentType) availableContentType = mt;
-			});
-			if (availableContentType) return [
-				availableContentType,
-				responseBody.content[availableContentType],
-				...responseBody.description ? [responseBody.description] : []
-			];
-			return false;
-		};
-	}
-	getResponseSchema(operation, statusCode) {
-		if (operation.schema.responses) Object.keys(operation.schema.responses).forEach((key) => {
-			const schema = operation.schema.responses[key];
-			const $ref = isReference(schema) ? schema.$ref : void 0;
-			if (schema && $ref) operation.schema.responses[key] = this.get($ref);
-		});
-		const getResponseBody = this.#getResponseBodyFactory(operation.getResponseByStatusCode(statusCode));
-		const { contentType } = this.#options;
-		const responseBody = getResponseBody(contentType);
-		if (responseBody === false) return {};
-		const schema = Array.isArray(responseBody) ? responseBody[1].schema : responseBody.schema;
-		if (!schema) return {};
-		return this.dereferenceWithRef(schema);
-	}
-	getRequestSchema(operation) {
-		const { contentType } = this.#options;
-		if (operation.schema.requestBody) operation.schema.requestBody = this.dereferenceWithRef(operation.schema.requestBody);
-		const requestBody = operation.getRequestBody(contentType);
-		if (requestBody === false) return;
-		const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
-		if (!schema) return;
-		return this.dereferenceWithRef(schema);
-	}
-	getParametersSchema(operation, inKey) {
-		const { contentType = operation.getContentType() } = this.#options;
-		const resolveParams = (params) => params.map((p) => this.dereferenceWithRef(p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
-		const operationParams = resolveParams(operation.schema?.parameters || []);
-		const pathItem = this.api?.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);
-		const params = Array.from(paramMap.values()).filter((v) => v.in === inKey);
-		if (!params.length) return null;
-		return params.reduce((schema, pathParameters) => {
-			const property = pathParameters.content?.[contentType]?.schema ?? pathParameters.schema;
-			const required = typeof schema.required === "boolean" ? schema.required : [...schema.required || [], pathParameters.required ? pathParameters.name : void 0].filter(Boolean);
-			const getDefaultStyle = (location) => {
-				if (location === "query") return "form";
-				if (location === "path") return "simple";
-				return "simple";
-			};
-			const style = pathParameters.style || getDefaultStyle(inKey);
-			const explode = pathParameters.explode !== void 0 ? pathParameters.explode : style === "form";
-			if (inKey === "query" && style === "form" && explode === true && property?.type === "object" && property?.additionalProperties && !property?.properties) return {
-				...schema,
-				description: pathParameters.description || schema.description,
-				deprecated: schema.deprecated,
-				example: property.example || schema.example,
-				additionalProperties: property.additionalProperties
-			};
-			return {
-				...schema,
-				description: schema.description,
-				deprecated: schema.deprecated,
-				example: schema.example,
-				required,
-				properties: {
-					...schema.properties,
-					[pathParameters.name]: {
-						description: pathParameters.description,
-						...property
-					}
-				}
-			};
-		}, {
-			type: "object",
-			required: [],
-			properties: {}
-		});
-	}
-	async validate() {
-		return validate(this.api);
-	}
-	flattenSchema(schema) {
-		return flattenSchema(schema);
-	}
-	/**
-	* Get schemas from OpenAPI components (schemas, responses, requestBodies).
-	* Returns schemas in dependency order along with name mapping for collision resolution.
-	*/
-	getSchemas(options = {}) {
-		const contentType = options.contentType ?? this.#options.contentType;
-		const includes = options.includes ?? [
-			"schemas",
-			"requestBodies",
-			"responses"
-		];
-		const shouldResolveCollisions = options.collisionDetection ?? this.#options.collisionDetection ?? false;
-		const components = this.getDefinition().components;
-		const schemasWithMeta = [];
-		if (includes.includes("schemas")) {
-			const componentSchemas = components?.schemas || {};
-			for (const [name, schemaObject] of Object.entries(componentSchemas)) {
-				let schema = schemaObject;
-				if (isReference(schemaObject)) {
-					const resolved = this.get(schemaObject.$ref);
-					if (resolved && !isReference(resolved)) schema = resolved;
-				}
-				schemasWithMeta.push({
-					schema,
-					source: "schemas",
-					originalName: name
-				});
-			}
-		}
-		if (includes.includes("responses")) {
-			const responses = components?.responses || {};
-			for (const [name, response] of Object.entries(responses)) {
-				const schema = extractSchemaFromContent(response.content, contentType);
-				if (schema) {
-					let resolvedSchema = schema;
-					if (isReference(schema)) {
-						const resolved = this.get(schema.$ref);
-						if (resolved && !isReference(resolved)) resolvedSchema = resolved;
-					}
-					schemasWithMeta.push({
-						schema: resolvedSchema,
-						source: "responses",
-						originalName: name
-					});
-				}
-			}
-		}
-		if (includes.includes("requestBodies")) {
-			const requestBodies = components?.requestBodies || {};
-			for (const [name, request] of Object.entries(requestBodies)) {
-				const schema = extractSchemaFromContent(request.content, contentType);
-				if (schema) {
-					let resolvedSchema = schema;
-					if (isReference(schema)) {
-						const resolved = this.get(schema.$ref);
-						if (resolved && !isReference(resolved)) resolvedSchema = resolved;
-					}
-					schemasWithMeta.push({
-						schema: resolvedSchema,
-						source: "requestBodies",
-						originalName: name
-					});
-				}
-			}
-		}
-		const { schemas, nameMapping } = shouldResolveCollisions ? resolveCollisions(schemasWithMeta) : legacyResolve(schemasWithMeta);
-		return {
-			schemas: sortSchemas(schemas),
-			nameMapping
-		};
-	}
-};
-//#endregion
-//#region src/oas/utils.ts
-/**
-* Narrows `doc` to a Swagger 2.0 document.
-* Swagger 2.0 documents do not have an `openapi` version key.
+* @example
+* ```ts
+* if (isOpenApiV2Document(doc)) {
+*   // doc is OpenAPIV2.Document
+* }
+* ```
 */
 function isOpenApiV2Document(doc) {
 	return !!doc && isPlainObject(doc) && !("openapi" in doc);
@@ -639,9 +489,15 @@ function isOpenApiV2Document(doc) {
 /**
 * Returns `true` when a schema should be treated as nullable.
 *
-* Covers three nullable signals across OAS versions:
-* - OAS 3.0: `nullable: true` or the vendor extension `x-nullable: true`.
-* - OAS 3.1 / JSON Schema: `type: 'null'` or `type: ['null', ...]` (multi-type array).
+* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+*
+* @example
+* ```ts
+* isNullable({ type: 'string', nullable: true }) // true
+* isNullable({ type: ['string', 'null'] })       // true
+* isNullable({ type: 'string' })                 // false
+* ```
 */
 function isNullable(schema) {
 	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
@@ -651,34 +507,51 @@ function isNullable(schema) {
 	return false;
 }
 /**
-* Narrows `obj` to an OpenAPI `$ref` pointer object.
-* Delegates to the `oas` package's own `isRef` helper.
+* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+*
+* @example
+* ```ts
+* isReference({ $ref: '#/components/schemas/Pet' }) // true
+* isReference({ type: 'string' })                   // false
+* ```
 */
 function isReference(obj) {
-	return !!obj && isRef(obj);
+	return !!obj && typeof obj === "object" && "$ref" in obj;
 }
 /**
-* Returns `true` when `obj` is a schema that carries a structured OAS 3.x `discriminator`
-* object — as opposed to a plain-string discriminator found in some Swagger 2 specs.
+* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object.
+*
+* @example
+* ```ts
+* isDiscriminator({ discriminator: { propertyName: 'type', mapping: {} } }) // true
+* isDiscriminator({ discriminator: 'type' })                                 // false (Swagger 2 string form)
+* ```
 */
 function isDiscriminator(obj) {
 	const record = obj;
 	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
 }
+//#endregion
+//#region src/factory.ts
 /**
-* Loads, dereferences, and wraps a raw OpenAPI document into an `Oas` instance.
+* Loads and dereferences an OpenAPI document, returning the raw `Document`.
+*
+* Accepts a file path string or an already-parsed document object. File paths are bundled via
+* Redocly to resolve external `$ref`s. Swagger 2.0 documents are automatically up-converted
+* to OpenAPI 3.0 via `swagger2openapi`.
 *
-* When given a file path string with `canBundle: true` (the default), Redocly's
-* bundler resolves all external `$ref`s first. Swagger 2.0 documents are
-* automatically up-converted to OpenAPI 3.0 via `swagger2openapi`.
+* @example
+* ```ts
+* const document = await parseDocument('./openapi.yaml')
+* const document = await parse(rawDocumentObject, { canBundle: false })
+* ```
 */
-async function parse(pathOrApi, { oasClass = Oas, canBundle = true, enablePaths = true } = {}) {
-	if (typeof pathOrApi === "string" && canBundle) return parse((await bundle({
+async function parseDocument(pathOrApi, { canBundle = true, enablePaths = true } = {}) {
+	if (typeof pathOrApi === "string" && canBundle) return parseDocument((await bundle({
 		ref: pathOrApi,
 		config: await loadConfig(),
 		base: pathOrApi
 	})).bundle.parsed, {
-		oasClass,
 		canBundle,
 		enablePaths
 	});
@@ -688,26 +561,28 @@ async function parse(pathOrApi, { oasClass = Oas, canBundle = true, enablePaths
 	}).load();
 	if (isOpenApiV2Document(document)) {
 		const { openapi } = await swagger2openapi.convertObj(document, { anchors: true });
-		return new oasClass(openapi);
+		return openapi;
 	}
-	return new oasClass(document);
+	return document;
 }
 /**
-* Deep-merges multiple OpenAPI documents into a single `Oas` instance.
+* Deep-merges multiple OpenAPI documents into a single `Document`.
 *
-* Each document is parsed independently (without path dereferencing) and then
-* recursively merged using `remeda`'s `mergeDeep`. The result is re-parsed so
-* the returned `Oas` instance is fully initialized.
+* Each document is parsed independently then recursively merged via `mergeDeep` from `@internals/utils`.
+* Throws when the input array is empty.
 *
-* Throws when the input array is empty — at least one document is required.
+* @example
+* ```ts
+* const document = await mergeDocuments(['./pets.yaml', './orders.yaml'])
+* ```
 */
-async function merge(pathOrApi, { oasClass = Oas } = {}) {
-	const instances = await Promise.all(pathOrApi.map((p) => parse(p, {
-		oasClass,
+async function mergeDocuments(pathOrApi) {
+	const documents = [];
+	for (const p of pathOrApi) documents.push(await parseDocument(p, {
 		enablePaths: false,
 		canBundle: false
-	})));
-	if (instances.length === 0) throw new Error("No OAS instances provided for merging.");
+	}));
+	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
 	const seed = {
 		openapi: MERGE_OPENAPI_VERSION,
 		info: {
@@ -717,82 +592,317 @@ async function merge(pathOrApi, { oasClass = Oas } = {}) {
 		paths: {},
 		components: { schemas: {} }
 	};
-	return parse(instances.reduce((acc, current) => mergeDeep(acc, current.document), seed), { oasClass });
+	return parseDocument(documents.reduce((acc, current) => mergeDeep(acc, current), seed));
 }
 /**
-* Constructs an `Oas` instance from a Kubb `Config` object.
+* Creates a `Document` from an `AdapterSource`.
+*
+* Handles all three source types:
+* - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
+* - `{ type: 'paths' }` — merges multiple file paths into a single document.
+* - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
 *
-* Handles all three input forms supported by `Config`:
-* - `data` — an inline YAML string, JSON string, or pre-parsed object.
-* - Array — multiple file paths that are deep-merged via {@link merge}.
-* - `path` — a local file path or a remote URL.
+* @example
+* ```ts
+* const document = await parseFromConfig({ type: 'path', path: './openapi.yaml' })
+* const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
+* ```
 */
-function parseFromConfig(config, oasClass = Oas) {
-	if ("data" in config.input) {
-		if (typeof config.input.data === "object") return parse(structuredClone(config.input.data), { oasClass });
-		try {
-			return parse(yaml.parse(config.input.data), { oasClass });
-		} catch {
-			return parse(config.input.data, { oasClass });
+function parseFromConfig(source) {
+	if (source.type === "data") {
+		if (typeof source.data === "object") return parseDocument(structuredClone(source.data));
+		return parseDocument(source.data, { canBundle: false });
+	}
+	if (source.type === "paths") return mergeDocuments(source.paths);
+	if (new URLPath(source.path).isURL) return parseDocument(source.path);
+	return parseDocument(path.resolve(path.dirname(source.path), source.path));
+}
+/**
+* Validates an OpenAPI document using `oas-normalize` with colorized error output.
+*
+* @example
+* ```ts
+* await validateDocument(document)
+* ```
+*/
+async function validateDocument(document, { throwOnError = false } = {}) {
+	try {
+		await new OASNormalize(document, {
+			enablePaths: true,
+			colorizeErrors: true
+		}).validate({ parser: { validate: { errors: { colorize: true } } } });
+	} catch (error) {
+		if (throwOnError) throw error;
+	}
+}
+//#endregion
+//#region src/refs.ts
+/**
+* Resolves a local JSON pointer reference from a document.
+*
+* Accepts `#/...` refs. Returns `null` for empty or non-local refs.
+* Throws when the pointer cannot be resolved.
+*
+* @example
+* ```ts
+* resolveRef<SchemaObject>(document, '#/components/schemas/Pet') // SchemaObject | null
+* ```
+*/
+function resolveRef(document, $ref) {
+	const origRef = $ref;
+	$ref = $ref.trim();
+	if ($ref === "") return null;
+	if ($ref.startsWith("#")) $ref = globalThis.decodeURIComponent($ref.substring(1));
+	else return null;
+	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
+	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
+	return current;
+}
+/**
+* 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;
+}
+//#endregion
+//#region src/resolvers.ts
+/**
+* Resolves `{variable}` placeholders in an OpenAPI server URL.
+*
+* Resolution order per variable: `overrides[key]` → `variable.default` → left unreplaced.
+* Throws when an override value is not in the variable's allowed `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 Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`);
+		url = url.replaceAll(`{${key}}`, value);
+	}
+	return url;
+}
+/**
+* Looks up the Kubb `SchemaType` for a given OAS `format` string.
+* Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
+* which are handled separately because their output depends on parser options.
+*/
+function getSchemaType(format) {
+	return formatMap[format] ?? null;
+}
+/**
+* Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
+* Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
+* `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
+*/
+function getPrimitiveType(type) {
+	if (type === "number" || type === "integer" || type === "bigint") return type;
+	if (type === "boolean") return "boolean";
+	return "string";
+}
+/**
+* Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
+* Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
+*/
+function getMediaType(contentType) {
+	return Object.values(ast.mediaTypes).includes(contentType) ? contentType : null;
+}
+/**
+* Returns all resolved parameters for an operation, merging path-level and operation-level entries.
+*
+* Operation-level parameters take precedence over path-level ones with the same `in:name` key.
+* `$ref` parameters are resolved via `dereferenceWithRef` to restore backward compatibility
+* with `oas` v31+ which otherwise filters them out.
+*
+* @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 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];
+	}
+	let availableContentType;
+	const contentTypes = Object.keys(body.content);
+	for (const mt of contentTypes) if (matchesMimeType.json(mt)) {
+		availableContentType = mt;
+		break;
+	}
+	if (!availableContentType) availableContentType = contentTypes[0];
+	if (availableContentType) return [
+		availableContentType,
+		body.content[availableContentType],
+		...body.description ? [body.description] : []
+	];
+	return 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, 200)         // SchemaObject
+* getResponseSchema(document, operation, '4XX')       // {}
+* ```
+*/
+function getResponseSchema(document, operation, statusCode, options = {}) {
+	if (operation.schema.responses) {
+		const responses = operation.schema.responses;
+		for (const key in responses) {
+			const schema = responses[key];
+			if (schema && isReference(schema)) responses[key] = resolveRef(document, schema.$ref);
 		}
 	}
-	if (Array.isArray(config.input)) return merge(config.input.map((input) => path.resolve(config.root, input.path)), { oasClass });
-	if (new URLPath(config.input.path).isURL) return parse(config.input.path, { oasClass });
-	return parse(path.resolve(config.root, config.input.path), { oasClass });
+	const responseBody = getResponseBody(operation.getResponseByStatusCode(statusCode), options.contentType);
+	if (responseBody === false) return {};
+	const schema = Array.isArray(responseBody) ? responseBody[1].schema : responseBody.schema;
+	if (!schema) return {};
+	return dereferenceWithRef(document, schema);
+}
+/**
+* Returns the request body schema for an operation, or `undefined` when absent.
+*
+* @example
+* ```ts
+* getRequestSchema(document, operation) // SchemaObject | null
+* ```
+*/
+function getRequestSchema(document, operation, options = {}) {
+	if (operation.schema.requestBody) operation.schema.requestBody = dereferenceWithRef(document, operation.schema.requestBody);
+	const requestBody = operation.getRequestBody(options.contentType);
+	if (requestBody === false) return null;
+	const schema = Array.isArray(requestBody) ? requestBody[1].schema : requestBody.schema;
+	if (!schema) return null;
+	return dereferenceWithRef(document, schema);
 }
 /**
-* Flattens a single-member or keyword-only `allOf` into its parent schema.
+* Flattens a keyword-only `allOf` into its parent schema.
+*
+* Only flattens when every member is a plain fragment — 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.
+*
+* @example
+* ```ts
+* flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
+* // { type: 'object', properties: {}, description: 'A pet' }
 *
-* Flattening is only performed when every `allOf` member is a "plain fragment" —
-* i.e. contains no structural composition keywords (see `structuralKeys`) and no
-* `$ref`. When any member carries structural meaning, the schema is returned unchanged.
+* flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
+* // returned unchanged — contains a $ref
+* ```
+*/
+/**
+* Returns `true` when `fragment` carries any JSON Schema keyword that makes it
+* structurally significant on its own (see `structuralKeys`).
 *
-* Keyword values from allOf members are merged into the parent on a first-write basis:
-* outer schema values always win over fragment values.
+* 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;
+}
 function flattenSchema(schema) {
 	if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null;
-	if (schema.allOf.some((item) => isRef(item))) return schema;
-	const isPlainFragment = (item) => !Object.keys(item).some((key) => structuralKeys.has(key));
-	if (!schema.allOf.every((item) => isPlainFragment(item))) return schema;
+	const allOfFragments = schema.allOf;
+	if (allOfFragments.some((item) => isRef(item))) return schema;
+	if (allOfFragments.some(hasStructuralKeywords)) return schema;
 	const merged = { ...schema };
 	delete merged.allOf;
-	for (const fragment of schema.allOf) for (const [key, value] of Object.entries(fragment)) if (merged[key] === void 0) merged[key] = value;
+	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) if (merged[key] === void 0) merged[key] = value;
 	return merged;
 }
 /**
-* Validates an OpenAPI document using `oas-normalize`.
-* Enables path validation and colorized error output.
+* 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
+* ```
 */
-async function validate(document) {
-	return new OASNormalize(document, {
-		enablePaths: true,
-		colorizeErrors: true
-	}).validate({ parser: { validate: { errors: { colorize: true } } } });
+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>` refs.
-* Used by `sortSchemas` to build the dependency graph.
+* Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
 */
 function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
 	if (Array.isArray(schema)) {
 		for (const item of schema) collectRefs(item, refs);
 		return refs;
 	}
-	if (schema && typeof schema === "object") for (const [key, value] of Object.entries(schema)) if (key === "$ref" && typeof value === "string") {
-		const match = value.match(/^#\/components\/schemas\/(.+)$/);
-		if (match) refs.add(match[1]);
-	} else collectRefs(value, refs);
+	if (schema && typeof schema === "object") for (const key in schema) {
+		const value = schema[key];
+		if (key === "$ref" && typeof value === "string") {
+			if (value.startsWith("#/components/schemas/")) {
+				const name = value.slice(21);
+				if (name) refs.add(name);
+			}
+		} else collectRefs(value, refs);
+	}
 	return refs;
 }
 /**
 * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
 *
-* Schemas with no references come first; schemas that are referenced by others
-* come before those that reference them. This ensures code generators emit
-* referenced types before the types that depend on them.
+* Referenced schemas appear before the schemas that depend on them, so code generators
+* can emit types in the correct order. Cycles are silently skipped.
 *
-* Cycles are silently skipped via the `stack` guard inside `visit`.
+* @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();
@@ -812,389 +922,200 @@ function sortSchemas(schemas) {
 	for (const name of sorted) result[name] = schemas[name];
 	return result;
 }
+const semanticSuffixes = {
+	schemas: "Schema",
+	responses: "Response",
+	requestBodies: "Request"
+};
+function getSemanticSuffix(source) {
+	return semanticSuffixes[source];
+}
+function resolveSchemaRef(document, schema) {
+	if (!isReference(schema)) return schema;
+	const resolved = resolveRef(document, schema.$ref);
+	return resolved && !isReference(resolved) ? resolved : schema;
+}
 /**
-* Extracts the inline schema from a media-type `content` map.
-*
-* Prefers `preferredContentType` when provided; otherwise falls back to the
-* first key in the map. Returns `null` when:
-* - `content` is absent.
-* - The target content-type has no `schema` entry.
-* - The schema is a `$ref` (callers resolve refs separately).
-*/
-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;
-}
-/**
-* Returns the PascalCase suffix appended to a component name when resolving
-* cross-source name collisions (schemas vs. responses vs. requestBodies).
-*/
-function getSemanticSuffix(source) {
-	switch (source) {
-		case "schemas": return "Schema";
-		case "responses": return "Response";
-		case "requestBodies": return "Request";
-	}
-}
-/**
-* Builds `GetSchemasResult` without any collision detection.
-* Each schema is registered under its original component name and its full
-* `#/components/<source>/<name>` ref path.
-*/
-function legacyResolve(schemasWithMeta) {
-	const schemas = {};
-	const nameMapping = /* @__PURE__ */ new Map();
-	for (const item of schemasWithMeta) {
-		schemas[item.originalName] = item.schema;
-		nameMapping.set(`#/components/${item.source}/${item.originalName}`, item.originalName);
-	}
-	return {
-		schemas,
-		nameMapping
-	};
-}
-/**
-* Builds `GetSchemasResult` with automatic name-collision resolution.
+* 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:
-* - If they share the same source, a numeric suffix (`2`, `3`, …) is appended.
-* - If they come from different sources (schemas / responses / requestBodies),
-*   a semantic suffix (`Schema`, `Response`, `Request`) is appended.
+* - Same source → numeric suffix (`2`, `3`, …).
+* - Different sources → semantic suffix (`Schema`, `Response`, `Request`).
 *
-* Non-colliding schemas are left unchanged.
+* @example
+* ```ts
+* const { schemas, nameMapping } = getSchemas(document, { contentType: 'application/json' })
+* ```
 */
-function resolveCollisions(schemasWithMeta) {
-	const schemas = {};
-	const nameMapping = /* @__PURE__ */ new Map();
+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 schemasWithMeta) {
-		const normalized = pascalCase(item.originalName);
-		const bucket = normalizedNames.get(normalized) ?? [];
+	for (const item of candidates) {
+		const key = pascalCase(item.originalName);
+		const bucket = normalizedNames.get(key) ?? [];
 		bucket.push(item);
-		normalizedNames.set(normalized, bucket);
+		normalizedNames.set(key, bucket);
 	}
+	const schemas = {};
+	const nameMapping = /* @__PURE__ */ new Map();
 	for (const [, items] of normalizedNames) {
-		if (items.length === 1) {
-			const item = items[0];
-			schemas[item.originalName] = item.schema;
-			nameMapping.set(`#/components/${item.source}/${item.originalName}`, item.originalName);
-			continue;
+		const isSingle = items.length === 1;
+		let hasMultipleSources = false;
+		if (!isSingle) {
+			const firstSource = items[0].source;
+			for (let i = 1; i < items.length; i++) if (items[i].source !== firstSource) {
+				hasMultipleSources = true;
+				break;
+			}
 		}
-		if (new Set(items.map((item) => item.source)).size === 1) items.forEach((item, index) => {
-			const uniqueName = item.originalName + (index === 0 ? "" : (index + 1).toString());
-			schemas[uniqueName] = item.schema;
-			nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
-		});
-		else items.forEach((item) => {
-			const uniqueName = item.originalName + getSemanticSuffix(item.source);
+		items.forEach((item, index) => {
+			const suffix = isSingle ? "" : hasMultipleSources ? getSemanticSuffix(item.source) : index === 0 ? "" : String(index + 1);
+			const uniqueName = item.originalName + suffix;
 			schemas[uniqueName] = item.schema;
 			nameMapping.set(`#/components/${item.source}/${item.originalName}`, uniqueName);
 		});
 	}
 	return {
-		schemas,
+		schemas: sortSchemas(schemas),
 		nameMapping
 	};
 }
-//#endregion
-//#region src/utils.ts
-/**
-* Extracts the schema name from a `$ref` string.
-* For `#/components/schemas/Order` this returns `'Order'`.
-* Falls back to the full ref string when no slash is present.
-*/
-function extractRefName($ref) {
-	return $ref.split("/").at(-1) ?? $ref;
-}
-/**
-* Replaces the discriminator property's schema inside an `ObjectSchemaNode`
-* with an enum of the given `values`.
-*
-* - When `enumName` is provided the enum is named, which lets printers emit a
-*   standalone enum declaration + type reference (e.g. `PetTypeEnum`).
-* - When `enumName` is omitted the enum stays anonymous, so printers inline it
-*   as a literal union (e.g. `'dog'`).
-*
-* Returns the node unchanged when it is not an object or lacks the target property.
-*/
-function applyDiscriminatorEnum({ node, propertyName, values, enumName }) {
-	if (node.type !== "object" || !node.properties?.length) return node;
-	if (!node.properties.some((prop) => prop.name === propertyName)) return node;
-	return createSchema({
-		...node,
-		properties: node.properties.map((prop) => {
-			if (prop.name !== propertyName) return prop;
-			const enumSchema = createSchema({
-				type: "enum",
-				primitive: "string",
-				enumValues: values,
-				name: enumName,
-				readOnly: prop.schema.readOnly,
-				writeOnly: prop.schema.writeOnly
-			});
-			return createProperty({
-				...prop,
-				schema: enumSchema
-			});
-		})
-	});
-}
-/**
-* Merges consecutive anonymous (`name`-less) `ObjectSchemaNode`s in `members` into a
-* single object by combining their `properties` arrays.
-*
-* Only adjacent pairs are merged — non-object or named nodes act as boundaries.
-* This collapses patterns like `Address & { streetNumber } & { streetName }` into
-* `Address & { streetNumber; streetName }`.
-*/
-function mergeAdjacentAnonymousObjects(members) {
-	return members.reduce((acc, member) => {
-		const obj = narrowSchema(member, "object");
-		if (obj && !obj.name) {
-			const prev = acc[acc.length - 1];
-			const prevObj = prev ? narrowSchema(prev, "object") : null;
-			if (prevObj && !prevObj.name) {
-				acc[acc.length - 1] = createSchema({
-					...prevObj,
-					properties: [...prevObj.properties ?? [], ...obj.properties ?? []]
-				});
-				return acc;
-			}
-		}
-		acc.push(member);
-		return acc;
-	}, []);
-}
-/**
-* Simplifies a union member list by removing `enum` nodes whose `primitive` type is
-* already represented by a broader scalar node in the same union.
-*
-* For example `['placed', 'approved'] | string` collapses to `string` because
-* `string` subsumes all string literals.  `'' | string` similarly becomes `string`.
-*
-* Only scalar primitives (`string`, `number`, `integer`, `bigint`, `boolean`) are
-* considered — object, array, and ref members are left untouched.
-*/
-function simplifyUnionMembers(members) {
-	const scalarPrimitives = new Set(members.filter((m) => [
-		"string",
-		"number",
-		"integer",
-		"bigint",
-		"boolean"
-	].includes(m.type)).map((m) => m.type));
-	if (!scalarPrimitives.size) return members;
-	return members.filter((m) => {
-		if (m.type !== "enum") return true;
-		const prim = m.primitive;
-		if (!prim) return true;
-		if (scalarPrimitives.has(prim)) return false;
-		if ((prim === "integer" || prim === "number") && (scalarPrimitives.has("integer") || scalarPrimitives.has("number"))) return false;
-		return true;
-	});
-}
 /**
-* `nameMapping`, and calls `resolve` to obtain the `{ name, path }` pair for
-* each import. When `oas` is supplied, only `$ref`s that are resolvable in the
-* spec are included; omit it to skip the existence check.
-*
-* This function is the pure, state-free alternative to `OasParser.getImports`.
-* Because it receives `nameMapping` explicitly it can be called without holding
-* a reference to the parser or the OAS instance.
-*
-* @example
-* ```ts
-* // Use adapter state directly — no parser reference needed
-* const imports = getImports({
-*   node: schemaNode,
-*   nameMapping: adapter.options.nameMapping,
-*   resolve: (schemaName) => ({
-*     name: schemaManager.getName(schemaName, { type: 'type' }),
-*     path: schemaManager.getFile(schemaName).path,
-*   }),
-* })
-* ```
+* Resolves the AST type descriptor for a date/time format, honoring the `dateType` option.
+* Returns `null` when `dateType: false`, signalling the format should fall through to `string`.
 */
-function getImports({ node, nameMapping, resolve }) {
-	return collect(node, { schema(schemaNode) {
-		if (schemaNode.type !== "ref" || !schemaNode.ref) return;
-		const rawName = extractRefName(schemaNode.ref);
-		const result = resolve(nameMapping.get(rawName) ?? rawName);
-		if (!result) return;
+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 {
-			name: [result.name],
-			path: result.path
+			type: "datetime",
+			offset: false
 		};
-	} });
-}
-//#endregion
-//#region src/parser.ts
-/**
-* Default values for all `Options` fields.
-*/
-const DEFAULT_OPTIONS = {
-	dateType: "string",
-	integerType: "number",
-	unknownType: "any",
-	emptySchemaType: "any",
-	enumSuffix: "enum"
-};
-/**
-* Looks up the Kubb `SchemaType` for a given OAS `format` string.
-* Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
-* which are handled separately because their output depends on parser options.
-*/
-function formatToSchemaType(format) {
-	return formatMap[format];
+	}
+	if (format === "date") return {
+		type: "date",
+		representation: options.dateType === "date" ? "date" : "string"
+	};
+	return {
+		type: "time",
+		representation: options.dateType === "date" ? "date" : "string"
+	};
 }
 /**
-* Maps an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
-* Numeric types (`number`, `integer`, `bigint`) are returned unchanged;
-* `boolean` maps to `'boolean'`; everything else defaults to `'string'`.
+* Collects the shared metadata fields passed to every `createSchema` call.
 */
-function getPrimitiveType(type) {
-	if (type === "number" || type === "integer" || type === "bigint") return type;
-	if (type === "boolean") return "boolean";
-	return "string";
+function buildSchemaNode(schema, name, nullable, defaultValue) {
+	return {
+		name,
+		nullable,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		readOnly: schema.readOnly,
+		writeOnly: schema.writeOnly,
+		default: defaultValue,
+		example: schema.example
+	};
 }
+//#endregion
+//#region src/parser.ts
 /**
-* Narrows a raw content-type string to the `MediaType` union recognized by Kubb.
-* Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
+* Normalize a malformed `{ type: 'array', enum: [...] }` schema by moving the
+* enum values into the items sub-schema. This pattern is technically invalid OAS
+* but appears in the wild and must be handled gracefully.
 */
-function toMediaType(contentType) {
-	return knownMediaTypes.includes(contentType) ? contentType : void 0;
+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
+	};
 }
 /**
-* Creates an OAS parser that converts an OpenAPI/Swagger spec into
-* the `@kubb/ast` tree.
-*
-* Options are passed per-call to `parse` or `convertSchema` rather than
-* at construction time, keeping the factory lightweight.
-*
-* This is the **kubb-parser** stage of the compilation lifecycle:
-*   OpenAPI / Swagger  →  Kubb AST
-*
-* No code is generated here; the resulting tree is spec-agnostic and can
-* be consumed by any downstream plugin (plugin-ts, plugin-zod, …).
+* Builds the internal converter functions for a given `OasParserContext`.
 *
-* @example
-* ```ts
-* const parser = createOasParser(oas)
-* const root = parser.parse({ emptySchemaType: 'unknown' })
-* ```
+* All `convert*` functions are defined as function declarations so they can freely
+* reference each other and `parseSchema` via JS hoisting (mutual recursion).
 */
-function createOasParser(oas, { contentType, collisionDetection } = {}) {
-	const { schemas: schemaObjects, nameMapping } = oas.getSchemas({
-		contentType,
-		collisionDetection
-	});
-	/**
-	* Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
-	* Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
-	*/
-	function resolveTypeOption(value) {
-		if (value === "any") return schemaTypes.any;
-		if (value === "void") return schemaTypes.void;
-		return schemaTypes.unknown;
-	}
-	/**
-	* Resolves the AST type and datetime modifiers for a date/time format, honoring the `dateType` option.
-	* Returns `undefined` when `dateType` is `false`, meaning the format should fall through to `string`.
-	*/
-	function getDateType(options, format) {
-		if (!options.dateType) return;
-		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"
-		};
-	}
+function createSchemaParser(ctx) {
+	const document = ctx.document;
 	/**
-	* Shared metadata fields included in every `createSchema` call.
-	* Centralizes the common properties so sub-handlers don't repeat them.
+	* Tracks `$ref` paths that are currently being resolved to prevent infinite
+	* recursion when schemas contain circular references (e.g. `Pet → parent → Pet`).
 	*/
-	function buildSchemaBase(schema, name, nullable, defaultValue) {
-		return {
-			name,
-			nullable,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			readOnly: schema.readOnly,
-			writeOnly: schema.writeOnly,
-			default: defaultValue,
-			example: schema.example
-		};
-	}
+	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
-	* Converts a `$ref` schema pointer into a `RefSchemaNode`.
+	* Converts a `$ref` schema into a `RefSchemaNode`.
 	*
-	* In OAS 3.0 siblings of `$ref` are technically ignored by the spec, but Kubb intentionally
-	* preserves them so that annotations like `pattern`, `description`, and `nullable` are
-	* reflected in generated JSDoc and type modifiers.
+	* 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 via `resolvingRefs` and leave `schema` as `undefined`.
 	*/
-	function convertRef({ schema, nullable, defaultValue }) {
-		return createSchema({
+	function convertRef({ schema, name, nullable, defaultValue, rawOptions }) {
+		let resolvedSchema;
+		const refPath = schema.$ref;
+		if (refPath && !resolvingRefs.has(refPath)) try {
+			const referenced = resolveRef(document, refPath);
+			if (referenced) {
+				resolvingRefs.add(refPath);
+				resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
+				resolvingRefs.delete(refPath);
+			}
+		} catch {}
+		return ast.createSchema({
+			...buildSchemaNode(schema, name, nullable, defaultValue),
 			type: "ref",
-			name: extractRefName(schema.$ref),
+			name: ast.extractRefName(schema.$ref),
 			ref: schema.$ref,
-			nullable,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			readOnly: schema.readOnly,
-			writeOnly: schema.writeOnly,
-			pattern: schema.type === "string" ? schema.pattern : void 0,
-			example: schema.example,
-			default: defaultValue
+			schema: resolvedSchema
 		});
 	}
 	/**
-	* Converts a `allOf` schema into either a flattened member node (single-member `allOf`)
-	* or an `IntersectionSchemaNode` (multi-member `allOf`).
-	*
-	* Single-member `allOf` without sibling structural keys is the common OAS 3.0 pattern for
-	* annotating a `$ref` or primitive with extra constraints; it is flattened to avoid
-	* producing needless intersection wrappers.
-	*
-	* The flatten path is skipped when the outer schema carries structural keys that cannot be
-	* merged into annotation fields: `properties`, `required`, or `additionalProperties`.
-	* Those cases must become an intersection so the constraints are preserved.
-	*
-	* Circular references through discriminator parents are detected and skipped to prevent
-	* infinite recursion during code generation.
+	* Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
 	*/
-	function convertAllOf({ schema, name, nullable, defaultValue, options }) {
+	function convertAllOf({ schema, name, nullable, defaultValue, rawOptions }) {
 		if (schema.allOf.length === 1 && !schema.properties && !(Array.isArray(schema.required) && schema.required.length) && schema.additionalProperties === void 0) {
 			const [memberSchema] = schema.allOf;
-			const memberNode = convertSchema({ schema: memberSchema }, options);
+			const memberNode = parseSchema({
+				schema: memberSchema,
+				name: null
+			}, 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;
-			return createSchema({
+			return ast.createSchema({
 				...memberNodeProps,
 				name,
 				title: schema.title ?? memberNode.title,
@@ -1208,17 +1129,26 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0)
 			});
 		}
+		const filteredDiscriminantValues = [];
 		const allOfMembers = schema.allOf.filter((item) => {
 			if (!isReference(item) || !name) return true;
-			const deref = oas.get(item.$ref);
+			const deref = resolveRef(document, item.$ref);
 			if (!deref || !isDiscriminator(deref)) return true;
 			const parentUnion = deref.oneOf ?? deref.anyOf;
 			if (!parentUnion) return true;
-			const childRef = `#/components/schemas/${name}`;
+			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);
-			return !inOneOf && !inMapping;
-		}).map((s) => convertSchema({ schema: s }, options));
+			if (inOneOf || inMapping) {
+				const discriminatorValue = ast.findDiscriminator(deref.discriminator.mapping, childRef);
+				if (discriminatorValue) filteredDiscriminantValues.push({
+					propertyName: deref.discriminator.propertyName,
+					value: discriminatorValue
+				});
+				return false;
+			}
+			return true;
+		}).map((s) => parseSchema({ schema: s }, 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();
@@ -1226,106 +1156,124 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			if (missingRequired.length) {
 				const resolvedMembers = schema.allOf.flatMap((item) => {
 					if (!isReference(item)) return [item];
-					const deref = oas.get(item.$ref);
+					const deref = resolveRef(document, item.$ref);
 					return deref && !isReference(deref) ? [deref] : [];
 				});
 				for (const key of missingRequired) for (const resolved of resolvedMembers) if (resolved.properties?.[key]) {
-					allOfMembers.push(convertSchema({ schema: {
+					allOfMembers.push(parseSchema({ schema: {
 						properties: { [key]: resolved.properties[key] },
 						required: [key]
-					} }, options));
+					} }, rawOptions));
 					break;
 				}
 			}
 		}
 		if (schema.properties) {
 			const { allOf: _allOf, ...schemaWithoutAllOf } = schema;
-			allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options));
+			allOfMembers.push(parseSchema({ schema: schemaWithoutAllOf }, rawOptions));
 		}
-		return createSchema({
+		for (const { propertyName, value } of filteredDiscriminantValues) allOfMembers.push(ast.createDiscriminantNode({
+			propertyName,
+			value
+		}));
+		return ast.createSchema({
 			type: "intersection",
-			members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
 	* Converts a `oneOf` / `anyOf` schema into a `UnionSchemaNode`.
-	*
-	* Both keywords are treated identically — their members are concatenated into a single union.
-	* When sibling `properties` are present alongside `oneOf`/`anyOf`, each union member is
-	* individually intersected with the shared properties node to match the OAS pattern of
-	* adding common fields next to a discriminated union.
 	*/
-	function convertUnion({ schema, name, nullable, defaultValue, options }) {
+	function convertUnion({ schema, name, nullable, defaultValue, rawOptions }) {
+		function pickDiscriminatorPropertyNode(node, propertyName) {
+			const discriminatorProperty = ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
+			if (!discriminatorProperty) return null;
+			return ast.createSchema({
+				type: "object",
+				primitive: "object",
+				properties: [discriminatorProperty]
+			});
+		}
 		const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
 		const unionBase = {
-			...buildSchemaBase(schema, name, nullable, defaultValue),
+			...buildSchemaNode(schema, name, nullable, defaultValue),
 			discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0
 		};
-		if (schema.properties) {
+		const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
+		const sharedPropertiesNode = schema.properties ? (() => {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
-			const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
-			const memberBaseSchema = discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion;
-			return createSchema({
+			return parseSchema({
+				schema: discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion,
+				name
+			}, rawOptions);
+		})() : void 0;
+		if (sharedPropertiesNode || discriminator?.mapping) {
+			const members = unionMembers.map((s) => {
+				const ref = isReference(s) ? s.$ref : void 0;
+				const discriminatorValue = ast.findDiscriminator(discriminator?.mapping, ref);
+				const memberNode = parseSchema({ schema: s }, rawOptions);
+				if (!discriminatorValue || !discriminator) return memberNode;
+				const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.setDiscriminatorEnum({
+					node: sharedPropertiesNode,
+					propertyName: discriminator.propertyName,
+					values: [discriminatorValue]
+				}), discriminator.propertyName) : void 0;
+				return ast.createSchema({
+					type: "intersection",
+					members: [memberNode, narrowedDiscriminatorNode ?? ast.createDiscriminantNode({
+						propertyName: discriminator.propertyName,
+						value: discriminatorValue
+					})]
+				});
+			});
+			const unionNode = ast.createSchema({
 				type: "union",
 				...unionBase,
-				members: unionMembers.map((s) => {
-					const ref = isReference(s) ? s.$ref : void 0;
-					const discriminatorValue = discriminator?.mapping && ref ? Object.entries(discriminator.mapping).find(([, v]) => v === ref)?.[0] : void 0;
-					let propertiesNode = convertSchema({
-						schema: memberBaseSchema,
-						name
-					}, options);
-					if (discriminatorValue && discriminator) propertiesNode = applyDiscriminatorEnum({
-						node: propertiesNode,
-						propertyName: discriminator.propertyName,
-						values: [discriminatorValue]
-					});
-					return createSchema({
-						type: "intersection",
-						members: [convertSchema({ schema: s }, options), propertiesNode]
-					});
-				})
+				members
+			});
+			if (!sharedPropertiesNode) return unionNode;
+			return ast.createSchema({
+				type: "intersection",
+				...buildSchemaNode(schema, name, nullable, defaultValue),
+				members: [unionNode, sharedPropertiesNode]
 			});
 		}
-		return createSchema({
+		return ast.createSchema({
 			type: "union",
 			...unionBase,
-			members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s }, options)))
+			members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s }, rawOptions)))
 		});
 	}
 	/**
-	* Converts an OAS 3.1 `const` schema into either a null scalar or a single-value `EnumSchemaNode`.
-	* `const: null` maps to a null scalar; any other value becomes a one-item enum so that generators
-	* can produce a precise literal type.
+	* 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 createSchema({
+		if (constValue === null) return ast.createSchema({
 			type: "null",
 			primitive: "null",
 			name,
 			title: schema.title,
 			description: schema.description,
-			deprecated: schema.deprecated,
-			nullable
+			deprecated: schema.deprecated
 		});
-		return createSchema({
+		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
+		return ast.createSchema({
 			type: "enum",
-			primitive: getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string"),
+			primitive: constPrimitive,
 			enumValues: [constValue],
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
-	* Handles `format`-based special types (date/time, uuid, email, blob, etc.).
-	* Returns `undefined` when the format should fall through to string handling
-	* (i.e. `format: 'date-time'` with `dateType: false`).
+	* Converts a format-annotated schema into a special-type `SchemaNode`.
+	* Returns `null` when the format should fall through to string handling (`dateType: false`).
 	*/
-	function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }) {
-		const base = buildSchemaBase(schema, name, nullable, defaultValue);
-		if (schema.format === "int64") return createSchema({
-			type: mergedOptions.integerType === "bigint" ? "bigint" : "integer",
+	function convertFormat({ schema, name, nullable, defaultValue, options }) {
+		const base = buildSchemaNode(schema, name, nullable, defaultValue);
+		if (schema.format === "int64") return ast.createSchema({
+			type: options.integerType === "bigint" ? "bigint" : "integer",
 			primitive: "integer",
 			...base,
 			min: schema.minimum,
@@ -1334,36 +1282,55 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0
 		});
 		if (schema.format === "date-time" || schema.format === "date" || schema.format === "time") {
-			const dateType = getDateType(mergedOptions, schema.format);
-			if (!dateType) return void 0;
-			if (dateType.type === "datetime") return createSchema({
+			const dateType = getDateType(options, schema.format);
+			if (!dateType) return null;
+			if (dateType.type === "datetime") return ast.createSchema({
 				...base,
 				primitive: "string",
 				type: "datetime",
 				offset: dateType.offset,
 				local: dateType.local
 			});
-			return createSchema({
+			return ast.createSchema({
 				...base,
 				primitive: "string",
 				type: dateType.type,
 				representation: dateType.representation
 			});
 		}
-		const specialType = formatToSchemaType(schema.format);
-		if (!specialType) return void 0;
+		const specialType = getSchemaType(schema.format);
+		if (!specialType) return null;
 		const specialPrimitive = specialType === "number" || specialType === "integer" || specialType === "bigint" ? specialType : "string";
-		if (specialType === "number" || specialType === "integer" || specialType === "bigint") return createSchema({
+		if (specialType === "number" || specialType === "integer" || specialType === "bigint") return ast.createSchema({
 			...base,
 			primitive: specialPrimitive,
 			type: specialType
 		});
-		if (specialType === "url") return createSchema({
+		if (specialType === "url") return ast.createSchema({
+			...base,
+			primitive: "string",
+			type: "url",
+			min: schema.minLength,
+			max: schema.maxLength
+		});
+		if (specialType === "ipv4") return ast.createSchema({
+			...base,
+			primitive: "string",
+			type: "ipv4"
+		});
+		if (specialType === "ipv6") return ast.createSchema({
 			...base,
 			primitive: "string",
-			type: "url"
+			type: "ipv6"
 		});
-		return createSchema({
+		if (specialType === "uuid" || specialType === "email") return ast.createSchema({
+			...base,
+			primitive: "string",
+			type: specialType,
+			min: schema.minLength,
+			max: schema.maxLength
+		});
+		return ast.createSchema({
 			...base,
 			primitive: specialPrimitive,
 			type: specialType
@@ -1371,36 +1338,20 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	}
 	/**
 	* Converts an `enum` schema into an `EnumSchemaNode`.
-	*
-	* Handles several edge cases:
-	* - `{ type: 'array', enum }` (technically invalid OAS) — the enum is normalized into `items`.
-	* - `null` in enum values (OAS 3.0 nullable enum convention) — stripped and reflected as `nullable`.
-	* - `x-enumNames` / `x-enum-varnames` vendor extensions — produce named enum variants with explicit labels.
-	* - Numeric and boolean enums require a const-map representation because most generators cannot
-	*   use string-enum syntax for non-string values.
 	*/
-	function convertEnum({ schema, name, nullable, type, options }) {
-		if (type === "array") {
-			const normalizedItems = {
-				...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
-				enum: schema.enum
-			};
-			const { enum: _enum, ...schemaWithoutEnum } = schema;
-			return convertSchema({
-				schema: {
-					...schemaWithoutEnum,
-					items: normalizedItems
-				},
-				name
-			}, options);
-		}
+	function convertEnum({ schema, name, nullable, type, rawOptions }) {
+		if (type === "array") return parseSchema({
+			schema: normalizeArrayEnum(schema),
+			name
+		}, rawOptions);
 		const nullInEnum = schema.enum.includes(null);
 		const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
 		const enumNullable = nullable || nullInEnum || void 0;
 		const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
+		const enumPrimitive = getPrimitiveType(type);
 		const enumBase = {
 			type: "enum",
-			primitive: getPrimitiveType(type),
+			primitive: enumPrimitive,
 			name,
 			title: schema.title,
 			description: schema.description,
@@ -1412,81 +1363,56 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			example: schema.example
 		};
 		const extensionKey = enumExtensionKeys.find((key) => key in schema);
-		if (extensionKey) {
-			const rawNames = schema[extensionKey];
-			const uniqueNames = [...new Set(rawNames)];
-			const enumType = getPrimitiveType(type) === "number" || getPrimitiveType(type) === "integer" ? "number" : getPrimitiveType(type) === "boolean" ? "boolean" : "string";
-			return createSchema({
+		if (extensionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
+			const enumPrimitiveType = enumPrimitive === "number" || enumPrimitive === "integer" ? "number" : enumPrimitive === "boolean" ? "boolean" : "string";
+			const rawEnumNames = extensionKey ? schema[extensionKey] : void 0;
+			const uniqueValues = [...new Set(filteredValues)];
+			const seenNames = /* @__PURE__ */ new Set();
+			return ast.createSchema({
 				...enumBase,
-				enumType,
-				namedEnumValues: uniqueNames.map((label, index) => ({
-					name: String(label),
-					value: filteredValues[index] ?? label,
-					format: enumType
-				}))
+				primitive: enumPrimitiveType,
+				namedEnumValues: uniqueValues.map((value, index) => ({
+					name: String(rawEnumNames?.[index] ?? value),
+					value,
+					primitive: enumPrimitiveType
+				})).filter((entry) => {
+					if (seenNames.has(entry.name)) return false;
+					seenNames.add(entry.name);
+					return true;
+				})
 			});
 		}
-		if (type === "number" || type === "integer") return createSchema({
-			...enumBase,
-			enumType: "number",
-			namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-				name: String(value),
-				value,
-				format: "number"
-			}))
-		});
-		if (type === "boolean") return createSchema({
-			...enumBase,
-			enumType: "boolean",
-			namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-				name: String(value),
-				value,
-				format: "boolean"
-			}))
-		});
-		return createSchema({
+		return ast.createSchema({
 			...enumBase,
 			enumValues: [...new Set(filteredValues)]
 		});
 	}
 	/**
-	* Converts an object-like schema (`type: 'object'`, `properties`, `additionalProperties`,
-	* or `patternProperties`) into an `ObjectSchemaNode`.
-	*
-	* When a `discriminator` is present, the discriminator property's schema is replaced with an
-	* enum of the mapping keys so generators can produce a precise literal-union type for it.
-	*
-	* Property optionality follows OAS semantics:
-	* - required + not nullable → `required: true`
-	* - not required + not nullable → `optional: true`
-	* - not required + nullable → `nullish: true`
+	* Converts an object-like schema into an `ObjectSchemaNode`.
 	*/
-	function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }) {
+	function convertObject({ schema, name, nullable, defaultValue, rawOptions, options }) {
 		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;
 			const propNullable = isNullable(resolvedPropSchema);
-			const basePropName = name ? pascalCase([name, propName].join(" ")) : void 0;
-			const propNode = convertSchema({
+			const propNode = parseSchema({
 				schema: resolvedPropSchema,
-				name: basePropName
-			}, options);
-			const isEnumNode = !!narrowSchema(propNode, "enum");
-			const derivedPropName = isEnumNode && name ? pascalCase([
-				name,
-				propName,
-				mergedOptions.enumSuffix
-			].filter(Boolean).join(" ")) : basePropName;
-			return createProperty({
+				name: ast.childName(name, propName)
+			}, rawOptions);
+			let schemaNode = ast.setEnumName(propNode, name, propName, options.enumSuffix);
+			const tupleNode = ast.narrowSchema(schemaNode, "tuple");
+			if (tupleNode?.items) {
+				const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix));
+				if (namedItems.some((item, i) => item !== tupleNode.items[i])) schemaNode = {
+					...tupleNode,
+					items: namedItems
+				};
+			}
+			return ast.createProperty({
 				name: propName,
 				schema: {
-					...isEnumNode && derivedPropName !== basePropName ? {
-						...propNode,
-						name: derivedPropName
-					} : propNode,
-					nullable: propNullable || void 0,
-					optional: !required && !propNullable ? true : void 0,
-					nullish: !required && propNullable ? true : void 0
+					...schemaNode,
+					nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
 				},
 				required
 			});
@@ -1494,115 +1420,113 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		const additionalProperties = schema.additionalProperties;
 		let additionalPropertiesNode;
 		if (additionalProperties === true) additionalPropertiesNode = true;
-		else if (additionalProperties && Object.keys(additionalProperties).length > 0) additionalPropertiesNode = convertSchema({ schema: additionalProperties }, options);
-		else if (additionalProperties === false) additionalPropertiesNode = void 0;
-		else if (additionalProperties) additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) });
+		else if (additionalProperties && Object.keys(additionalProperties).length > 0) additionalPropertiesNode = parseSchema({ schema: additionalProperties }, rawOptions);
+		else if (additionalProperties === false) additionalPropertiesNode = false;
+		else if (additionalProperties) additionalPropertiesNode = ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
 		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 ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) }) : convertSchema({ schema: patternSchema }, options)])) : void 0;
-		const objectNode = createSchema({
+		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || typeof patternSchema === "object" && Object.keys(patternSchema).length === 0 ? ast.createSchema({ type: typeOptionMap.get(options.unknownType) }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
+		const objectNode = ast.createSchema({
 			type: "object",
 			primitive: "object",
 			properties,
 			additionalProperties: additionalPropertiesNode,
 			patternProperties,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			minProperties: schema.minProperties,
+			maxProperties: schema.maxProperties,
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 		if (isDiscriminator(schema) && schema.discriminator.mapping) {
 			const discPropName = schema.discriminator.propertyName;
-			return applyDiscriminatorEnum({
+			const values = Object.keys(schema.discriminator.mapping);
+			const enumName = name ? ast.enumPropName(name, discPropName, options.enumSuffix) : void 0;
+			return ast.setDiscriminatorEnum({
 				node: objectNode,
 				propertyName: discPropName,
-				values: Object.keys(schema.discriminator.mapping),
-				enumName: name ? pascalCase([
-					name,
-					discPropName,
-					mergedOptions.enumSuffix
-				].filter(Boolean).join(" ")) : void 0
+				values,
+				enumName
 			});
 		}
 		return objectNode;
 	}
 	/**
 	* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
-	*
-	* Each `prefixItems` element maps to a positional tuple slot. An optional `items` schema
-	* after the prefix items is mapped to the rest parameter of the tuple.
 	*/
-	function convertTuple({ schema, name, nullable, defaultValue, options }) {
-		return createSchema({
+	function convertTuple({ schema, name, nullable, defaultValue, rawOptions }) {
+		const tupleItems = (schema.prefixItems ?? []).map((item) => parseSchema({ schema: item }, rawOptions));
+		const rest = schema.items ? parseSchema({ schema: schema.items }, rawOptions) : ast.createSchema({ type: "any" });
+		return ast.createSchema({
 			type: "tuple",
 			primitive: "array",
-			items: (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item }, options)),
-			rest: schema.items ? convertSchema({ schema: schema.items }, options) : void 0,
+			items: tupleItems,
+			rest,
 			min: schema.minItems,
 			max: schema.maxItems,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
 	* Converts a `type: 'array'` schema into an `ArraySchemaNode`.
-	*
-	* When the items schema is an inline enum, a name derived from the parent array's name and
-	* `enumSuffix` is forwarded so generators can emit a named enum declaration.
 	*/
-	function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }) {
+	function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }) {
 		const rawItems = schema.items;
-		const itemName = rawItems?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(" ")) : void 0;
-		return createSchema({
+		const itemName = rawItems?.enum?.length && name ? ast.enumPropName(void 0, name, options.enumSuffix) : void 0;
+		const items = rawItems ? [parseSchema({
+			schema: rawItems,
+			name: itemName
+		}, rawOptions)] : [];
+		return ast.createSchema({
 			type: "array",
 			primitive: "array",
-			items: rawItems ? [convertSchema({
-				schema: rawItems,
-				name: itemName
-			}, options)] : [],
+			items,
 			min: schema.minItems,
 			max: schema.maxItems,
 			unique: schema.uniqueItems ?? void 0,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
-	* Converts a `type: 'string'` schema (without a special format) into a `StringSchemaNode`.
+	* Converts a `type: 'string'` schema into a `StringSchemaNode`.
 	*/
 	function convertString({ schema, name, nullable, defaultValue }) {
-		return createSchema({
+		return ast.createSchema({
 			type: "string",
 			primitive: "string",
 			min: schema.minLength,
 			max: schema.maxLength,
 			pattern: schema.pattern,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
-	* Converts a `type: 'number'` or `type: 'integer'` schema into the corresponding `SchemaNode`.
+	* Converts a `type: 'number'` or `type: 'integer'` schema.
 	*/
 	function convertNumeric({ schema, name, nullable, defaultValue }, type) {
-		return createSchema({
+		return ast.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,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			multipleOf: schema.multipleOf,
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
-	* Converts a `type: 'boolean'` schema into a `BooleanSchemaNode`.
+	* Converts a `type: 'boolean'` schema.
 	*/
 	function convertBoolean({ schema, name, nullable, defaultValue }) {
-		return createSchema({
+		return ast.createSchema({
 			type: "boolean",
 			primitive: "boolean",
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
-	* Converts an explicit `type: 'null'` or `const: null` schema into a `NullSchemaNode`.
+	* Converts an explicit `type: 'null'` schema.
 	*/
 	function convertNull({ schema, name, nullable }) {
-		return createSchema({
+		return ast.createSchema({
 			type: "null",
 			primitive: "null",
 			name,
@@ -1613,31 +1537,22 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		});
 	}
 	/**
-	* Central dispatcher: converts an OAS `SchemaObject` into a `SchemaNode`.
+	* Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
 	*
-	* Dispatch order (first match wins):
-	* 1. `$ref` pointer
-	* 2. `allOf` composition
-	* 3. `oneOf` / `anyOf` union
-	* 4. `const` literal (OAS 3.1)
-	* 5. `format`-based special type (date/time, uuid, blob, …)
-	* 6. OAS 3.1 `contentMediaType: 'application/octet-stream'` blob
-	* 7. OAS 3.1 multi-type array → union or fallthrough
-	* 8. Constraint-inferred type (minLength/maxLength → string; minimum/maximum → number)
-	* 9. `enum` values
-	* 10. Object / array / tuple / scalar by `type`
-	* 11. Empty schema fallback (`emptySchemaType` option)
+	* Dispatch order (first match wins): `$ref` → `allOf` → `oneOf`/`anyOf` → `const` → `format`
+	* → octet-stream blob → multi-type array → constraint-inferred type → `enum` → object/array/tuple/scalar
+	* → empty-schema fallback (`emptySchemaType` option).
 	*/
-	function convertSchema({ schema, name }, options) {
-		const mergedOptions = {
-			...DEFAULT_OPTIONS,
-			...options
+	function parseSchema({ schema, name }, rawOptions) {
+		const options = {
+			...DEFAULT_PARSER_OPTIONS,
+			...rawOptions
 		};
 		const flattenedSchema = flattenSchema(schema);
-		if (flattenedSchema && flattenedSchema !== schema) return convertSchema({
+		if (flattenedSchema && flattenedSchema !== schema) return parseSchema({
 			schema: flattenedSchema,
 			name
-		}, options);
+		}, rawOptions);
 		const nullable = isNullable(schema) || void 0;
 		const defaultValue = schema.default === null && nullable ? void 0 : schema.default;
 		const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
@@ -1647,8 +1562,8 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			nullable,
 			defaultValue,
 			type,
-			options,
-			mergedOptions
+			rawOptions,
+			options
 		};
 		if (isReference(schema)) return convertRef(ctx);
 		if (schema.allOf?.length) return convertAllOf(ctx);
@@ -1658,24 +1573,24 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			const formatResult = convertFormat(ctx);
 			if (formatResult) return formatResult;
 		}
-		if (schema.type === "string" && schema.contentMediaType === "application/octet-stream") return createSchema({
+		if (schema.type === "string" && schema.contentMediaType === "application/octet-stream") return ast.createSchema({
 			type: "blob",
 			primitive: "string",
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 		if (Array.isArray(schema.type) && schema.type.length > 1) {
 			const nonNullTypes = schema.type.filter((t) => t !== "null");
 			const arrayNullable = schema.type.includes("null") || nullable || void 0;
-			if (nonNullTypes.length > 1) return createSchema({
+			if (nonNullTypes.length > 1) return ast.createSchema({
 				type: "union",
-				members: nonNullTypes.map((t) => convertSchema({
+				members: nonNullTypes.map((t) => parseSchema({
 					schema: {
 						...schema,
 						type: t
 					},
 					name
-				}, options)),
-				...buildSchemaBase(schema, name, arrayNullable, defaultValue)
+				}, rawOptions)),
+				...buildSchemaNode(schema, name, arrayNullable, defaultValue)
 			});
 		}
 		if (!type) {
@@ -1691,57 +1606,102 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		if (type === "integer") return convertNumeric(ctx, "integer");
 		if (type === "boolean") return convertBoolean(ctx);
 		if (type === "null") return convertNull(ctx);
-		return createSchema({
-			type: resolveTypeOption(mergedOptions.emptySchemaType),
+		const emptyType = typeOptionMap.get(options.emptySchemaType);
+		return ast.createSchema({
+			type: emptyType,
 			name,
 			title: schema.title,
 			description: schema.description
 		});
 	}
 	/**
-	* Converts a single dereferenced OAS parameter object into a `ParameterNode`.
-	* When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
+	* Converts a dereferenced OAS parameter object into a `ParameterNode`.
 	*/
 	function parseParameter(options, param) {
 		const required = param["required"] ?? false;
-		const schema = param["schema"] && !isReference(param["schema"]) ? convertSchema({ schema: param["schema"] }, options) : createSchema({ type: resolveTypeOption(options.unknownType) });
-		return createParameter({
+		const schema = param["schema"] ? parseSchema({ schema: param["schema"] }, options) : ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		return ast.createParameter({
 			name: param["name"],
 			in: param["in"],
 			schema: {
 				...schema,
-				optional: !required || !!schema.optional ? true : void 0
+				description: param["description"] ?? schema.description
 			},
 			required
 		});
 	}
 	/**
-	* Converts an OAS `Operation` into an `OperationNode`, resolving parameters,
-	* request body, and all response codes into their AST node equivalents.
+	* Reads the inline `requestBody` metadata (description / required / contentType) that OAS exposes
+	* outside the schema itself. Returns an empty object when the request body is missing or a `$ref`.
 	*/
-	function parseOperation(options, oas, operation) {
-		const parameters = operation.getParameters().map((param) => {
-			return parseParameter(options, oas.dereferenceWithRef(param));
-		});
-		const requestBodySchema = oas.getRequestSchema(operation);
-		const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : void 0;
+	function getRequestBodyMeta(operation) {
+		const body = operation.schema.requestBody;
+		if (!body || isReference(body)) return { required: false };
+		const inline = body;
+		return {
+			description: inline.description,
+			required: inline.required === true,
+			contentType: inline.content ? Object.keys(inline.content)[0] : void 0
+		};
+	}
+	/**
+	* Reads the inline response object (not a `$ref`) and returns its description plus its `content` map.
+	*/
+	function getResponseMeta(responseObj) {
+		if (typeof responseObj !== "object" || responseObj === null || Array.isArray(responseObj)) return {};
+		const inline = responseObj;
+		return {
+			description: inline.description,
+			content: inline.content
+		};
+	}
+	/**
+	* 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 void 0;
+		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 : void 0;
+	}
+	/**
+	* Converts an OAS `Operation` into an `OperationNode`.
+	*/
+	function parseOperation(options, operation) {
+		const parameters = getParameters(document, operation).map((param) => parseParameter(options, param));
+		const requestBodySchema = getRequestSchema(document, operation, { contentType: ctx.contentType });
+		const requestBodySchemaNode = requestBodySchema ? parseSchema({ schema: requestBodySchema }, options) : void 0;
+		const requestBodyMeta = getRequestBodyMeta(operation);
+		const requestBody = requestBodySchemaNode ? {
+			description: requestBodyMeta.description,
+			schema: ast.syncOptionality(requestBodySchemaNode, requestBodyMeta.required),
+			keysToOmit: collectPropertyKeysByFlag(requestBodySchema, "readOnly"),
+			required: requestBodyMeta.required || void 0,
+			contentType: requestBodyMeta.contentType
+		} : void 0;
 		const responses = operation.getResponseStatusCodes().map((statusCode) => {
 			const responseObj = operation.getResponseByStatusCode(statusCode);
-			const responseSchema = oas.getResponseSchema(operation, statusCode);
-			const schema = responseSchema && Object.keys(responseSchema).length > 0 ? convertSchema({ schema: responseSchema }, options) : void 0;
-			const description = typeof responseObj === "object" && responseObj !== null && !Array.isArray(responseObj) ? responseObj.description : void 0;
-			const rawContent = typeof responseObj === "object" && responseObj !== null && !Array.isArray(responseObj) ? responseObj.content : void 0;
-			return createResponse({
+			const responseSchema = getResponseSchema(document, operation, statusCode, { contentType: ctx.contentType });
+			const schema = responseSchema && Object.keys(responseSchema).length > 0 ? parseSchema({ schema: responseSchema }, options) : ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType) });
+			const { description, content } = getResponseMeta(responseObj);
+			const mediaType = content ? getMediaType(Object.keys(content)[0] ?? "") : getMediaType(operation.contentType ?? "");
+			return ast.createResponse({
 				statusCode,
 				description,
 				schema,
-				mediaType: rawContent ? toMediaType(Object.keys(rawContent)[0] ?? "") : toMediaType(operation.contentType ?? "")
+				mediaType,
+				keysToOmit: collectPropertyKeysByFlag(responseSchema, "writeOnly")
 			});
 		});
-		return createOperation({
+		const urlPath = new URLPath(operation.path);
+		return ast.createOperation({
 			operationId: operation.getOperationId(),
 			method: operation.method.toUpperCase(),
-			path: new URLPath(operation.path).URL,
+			path: urlPath.path,
 			tags: operation.getTags().map((tag) => tag.name),
 			summary: operation.getSummary() || void 0,
 			description: operation.getDescription() || void 0,
@@ -1751,158 +1711,159 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			responses
 		});
 	}
-	/**
-	* Converts an OpenAPI/Swagger spec (wrapped in a Kubb `Oas` instance) into
-	* a `RootNode` — the top-level node of the `@kubb/ast` tree.
-	*/
-	function parse(options) {
-		const mergedOptions = {
-			...DEFAULT_OPTIONS,
-			...options
-		};
-		const schemas = Object.entries(schemaObjects).map(([name, schemaObject]) => convertSchema({
-			schema: schemaObject,
-			name
-		}, mergedOptions));
-		const paths = oas.getPaths();
-		return createRoot({
-			schemas,
-			operations: Object.entries(paths).flatMap(([_path, methods]) => Object.entries(methods).map(([, operation]) => operation ? parseOperation(mergedOptions, oas, operation) : null).filter((op) => op !== null))
-		});
-	}
-	/**
-	* Walks a `SchemaNode` tree and resolves all `ref` node names through the provided callbacks.
-	*
-	* `resolveName` handles all schema types; `resolveEnumName` (when provided) takes precedence
-	* for `enum` nodes, enabling a separate naming strategy for enums (e.g. different suffix).
-	*
-	* Collision-resolved names (from `nameMapping`) are applied before user-supplied resolvers.
-	*/
-	function resolveRefs(node, resolveName, resolveEnumName) {
-		return transform(node, { schema(schemaNode) {
-			const schemaRef = narrowSchema(schemaNode, schemaTypes.ref);
-			if (schemaRef && (schemaRef.ref || schemaRef.name)) {
-				const rawRef = schemaRef.ref ?? schemaRef.name;
-				const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef);
-				if (resolved) return {
-					...schemaNode,
-					name: resolved
-				};
-			}
-			if (schemaNode.type === "enum" && schemaNode.name) {
-				const resolved = (resolveEnumName ?? resolveName)(schemaNode.name);
-				if (resolved) return {
-					...schemaNode,
-					name: resolved
-				};
-			}
-		} });
-	}
 	return {
-		parse,
-		convertSchema,
-		resolveRefs,
+		parseSchema,
+		parseOperation,
+		parseParameter
+	};
+}
+/**
+* Converts the entire OpenAPI spec into an `InputNode` (the top-level `@kubb/ast` tree).
+*
+* This is the main entry point: `OpenAPI / Swagger → Kubb AST`.
+* No code is generated here — the resulting tree is spec-agnostic and consumed by
+* downstream plugins (`plugin-ts`, `plugin-zod`, …).
+*
+* @example
+* ```ts
+* const document = await parseFromConfig(config)
+* const root = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+* ```
+*/
+function parseOas(document, options = {}) {
+	const { contentType, ...parserOptions } = options;
+	const mergedOptions = {
+		...DEFAULT_PARSER_OPTIONS,
+		...parserOptions
+	};
+	const { schemas: schemaObjects, nameMapping } = getSchemas(document, { contentType });
+	const { parseSchema: _parseSchema, parseOperation: _parseOperation } = createSchemaParser({
+		document,
+		contentType
+	});
+	const schemas = Object.entries(schemaObjects).map(([name, schema]) => _parseSchema({
+		schema,
+		name
+	}, mergedOptions));
+	const paths = new BaseOas(document).getPaths();
+	const operations = Object.entries(paths).flatMap(([_path, methods]) => Object.entries(methods).map(([, operation]) => operation ? _parseOperation(mergedOptions, operation) : null).filter((op) => op !== null));
+	return {
+		root: ast.createInput({
+			schemas,
+			operations
+		}),
 		nameMapping
 	};
 }
 //#endregion
 //#region src/adapter.ts
+/**
+* Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+*/
 const adapterOasName = "oas";
 /**
-* Creates an OpenAPI / Swagger adapter for Kubb.
+* Creates the default OpenAPI / Swagger adapter for Kubb.
 *
-* This is the default adapter — you can omit it from your config when using
-* an OpenAPI spec, but supplying it explicitly lets you pass options.
+* Parses the spec, optionally validates it, resolves the base URL, and converts
+* everything into an `InputNode` that downstream plugins consume.
 *
 * @example
 * ```ts
-* import { defineConfig } from '@kubb/core'
+* import { defineConfig } from 'kubb'
 * import { adapterOas } from '@kubb/adapter-oas'
+* import { pluginTs } from '@kubb/plugin-ts'
 *
 * export default defineConfig({
-*   adapter: adapterOas({ validate: true, dateType: 'date' }),
-*   input:   { path: './openapi.yaml' },
-*   plugins: [pluginTs(), pluginZod()],
+*   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
+*   input: { path: './openapi.yaml' },
+*   plugins: [pluginTs()],
 * })
 * ```
 */
-const adapterOas = defineAdapter((options) => {
-	const { validate = true, oasClass, contentType, serverIndex, serverVariables, discriminator = "strict", collisionDetection = false, dateType = "string", integerType = "number", unknownType = "any", emptySchemaType = unknownType } = options;
-	const nameMapping = /* @__PURE__ */ new Map();
+const adapterOas = createAdapter((options) => {
+	const { validate = true, contentType, serverIndex, serverVariables, discriminator = "strict", 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;
+	let nameMapping = /* @__PURE__ */ new Map();
+	let parsedDocument;
+	let inputNode;
 	return {
 		name: "oas",
-		options: {
-			validate,
-			oasClass,
-			contentType,
-			serverIndex,
-			serverVariables,
-			discriminator,
-			collisionDetection,
-			dateType,
-			integerType,
-			unknownType,
-			emptySchemaType,
-			nameMapping
+		get options() {
+			return {
+				validate,
+				contentType,
+				serverIndex,
+				serverVariables,
+				discriminator,
+				dateType,
+				integerType,
+				unknownType,
+				emptySchemaType,
+				enumSuffix,
+				nameMapping
+			};
+		},
+		get document() {
+			return parsedDocument;
+		},
+		get inputNode() {
+			return inputNode;
 		},
 		getImports(node, resolve) {
-			return getImports({
+			return ast.collectImports({
 				node,
 				nameMapping,
-				resolve
+				resolve: (schemaName) => {
+					const result = resolve(schemaName);
+					if (!result) return;
+					return ast.createImport({
+						name: [result.name],
+						path: result.path
+					});
+				}
 			});
 		},
 		async parse(source) {
-			const oas = await parseFromConfig(sourceToFakeConfig(source), oasClass);
-			oas.setOptions({
-				contentType,
-				discriminator,
-				collisionDetection
-			});
-			if (validate) try {
-				await oas.validate();
-			} catch (_err) {}
-			const server = serverIndex !== void 0 ? oas.api.servers?.at(serverIndex) : void 0;
+			const document = await parseFromConfig(source);
+			if (validate) await validateDocument(document);
+			const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
 			const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : void 0;
-			const parser = createOasParser(oas, {
+			const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
 				contentType,
-				collisionDetection
+				dateType,
+				integerType,
+				unknownType,
+				emptySchemaType,
+				enumSuffix
 			});
-			nameMapping.clear();
-			for (const [key, value] of parser.nameMapping) nameMapping.set(key, value);
-			return createRoot({
-				...parser.parse({
-					dateType,
-					integerType,
-					unknownType,
-					emptySchemaType
-				}),
+			const node = discriminator === "inherit" ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot;
+			nameMapping = parsedNameMapping;
+			parsedDocument = document;
+			inputNode = ast.createInput({
+				...node,
 				meta: {
-					title: oas.api.info?.title,
-					version: oas.api.info?.version,
+					title: document.info?.title,
+					description: document.info?.description,
+					version: document.info?.version,
 					baseURL
 				}
 			});
+			return inputNode;
 		}
 	};
 });
-function sourceToFakeConfig(source) {
-	switch (source.type) {
-		case "path": return {
-			root: path.dirname(source.path),
-			input: { path: source.path }
-		};
-		case "data": return {
-			root: process.cwd(),
-			input: { data: source.data }
-		};
-		case "paths": return {
-			root: source.paths[0] ? path.dirname(source.paths[0]) : process.cwd(),
-			input: source.paths.map((p) => ({ path: p }))
-		};
-	}
-}
 //#endregion
-export { adapterOas, adapterOasName };
+//#region src/types.ts
+/**
+* Uppercase → lowercase HTTP method map, re-exported for backwards compatibility.
+*
+* @example
+* ```ts
+* HttpMethods['GET'] // 'get'
+* HttpMethods['POST'] // 'post'
+* ```
+*/
+const HttpMethods = Object.fromEntries(Object.entries(ast.httpMethods).map(([lower, upper]) => [upper, lower]));
+//#endregion
+export { HttpMethods, adapterOas, adapterOasName, mergeDocuments, parseDocument, parseFromConfig, validateDocument };
 
 //# sourceMappingURL=index.js.map