@kubb/adapter-oas 5.0.0-beta.4 → 5.0.0-beta.40

package/dist/index.js

@@ -1,10 +1,11 @@
-import "./chunk--u3MIqq1.js";
-import { ast, createAdapter } from "@kubb/core";
+import "./chunk-C0LytTxp.js";
+import { Diagnostics, ast, createAdapter } from "@kubb/core";
+import BaseOas from "oas";
 import path from "node:path";
+import { access } from "node:fs/promises";
 import { bundle, loadConfig } from "@redocly/openapi-core";
 import OASNormalize from "oas-normalize";
 import swagger2openapi from "swagger2openapi";
-import BaseOas from "oas";
 import { isRef } from "oas/types";
 import { matchesMimeType } from "oas/utils";
 //#region src/constants.ts
@@ -89,6 +90,18 @@ const structuralKeys = new Set([
 * formatMap['float']  // 'number'
 * ```
 */
+/**
+* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+* `int64` and the date/time family. Keep this in sync with the `convertFormat`
+* special-cases in `parser.ts`. `isHandledFormat` reads it so the
+* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+*/
+const specialCasedFormats = new Set([
+	"int64",
+	"date-time",
+	"date",
+	"time"
+]);
 const formatMap = {
 	uuid: "uuid",
 	email: "email",
@@ -127,87 +140,6 @@ const typeOptionMap = new Map([
 	["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]
-			});
-		}
-	}
-	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
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -272,6 +204,23 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/fs.ts
+/**
+* Resolves to `true` when the file or directory at `path` exists.
+* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
+*
+* @example
+* ```ts
+* if (await exists('./kubb.config.ts')) {
+*   const content = await read('./kubb.config.ts')
+* }
+* ```
+*/
+async function exists(path) {
+	if (typeof Bun !== "undefined") return Bun.file(path).exists();
+	return access(path).then(() => true, () => false);
+}
+//#endregion
 //#region ../../internals/utils/src/object.ts
 /**
 * Returns `true` when `value` is a plain (non-null, non-array) object.
@@ -517,12 +466,13 @@ var URLPath = class {
 	* @example
 	* new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
 	*/
-	toTemplateString({ prefix = "", replacer } = {}) {
-		return `\`${prefix}${this.path.split(/\{([^}]+)\}/).map((part, i) => {
+	toTemplateString({ prefix, replacer } = {}) {
+		const result = this.path.split(/\{([^}]+)\}/).map((part, i) => {
 			if (i % 2 === 0) return part;
 			const param = this.#transformParam(part);
 			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("")}\``;
+		}).join("");
+		return `\`${prefix ?? ""}${result}\``;
 	}
 	/**
 	* Extracts all `{param}` segments from the path and returns them as a key-value map.
@@ -660,12 +610,17 @@ async function parseDocument(pathOrApi, { canBundle = true, enablePaths = true }
 * ```
 */
 async function mergeDocuments(pathOrApi) {
-	const documents = [];
-	for (const p of pathOrApi) documents.push(await parseDocument(p, {
+	const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, {
 		enablePaths: false,
 		canBundle: false
-	}));
-	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
+	})));
+	if (documents.length === 0) throw new Diagnostics.Error({
+		code: Diagnostics.code.inputRequired,
+		severity: "error",
+		message: "No OAS documents were provided for merging.",
+		help: "Pass at least one path or document to `input.path`.",
+		location: { kind: "config" }
+	});
 	const seed = {
 		openapi: MERGE_OPENAPI_VERSION,
 		info: {
@@ -681,9 +636,9 @@ async function mergeDocuments(pathOrApi) {
 * 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.
+* - `{ 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.
 *
 * @example
 * ```ts
@@ -691,14 +646,31 @@ async function mergeDocuments(pathOrApi) {
 * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
 * ```
 */
-function parseFromConfig(source) {
+async 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));
+	const resolved = path.resolve(path.dirname(source.path), source.path);
+	await assertInputExists(resolved);
+	return parseDocument(resolved);
+}
+/**
+* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* its parse error instead.
+*/
+async function assertInputExists(input) {
+	if (new URLPath(input).isURL) return;
+	if (!await exists(input)) throw new Diagnostics.Error({
+		code: Diagnostics.code.inputNotFound,
+		severity: "error",
+		message: `Cannot read the file set in \`input.path\` (or via \`kubb generate PATH\`): ${input}`,
+		help: "Check that the path exists and is readable, then set it in `input.path` or pass it as `kubb generate PATH`.",
+		location: { kind: "config" }
+	});
 }
 /**
 * Validates an OpenAPI document using `oas-normalize` with colorized error output.
@@ -720,6 +692,7 @@ async function validateDocument(document, { throwOnError = false } = {}) {
 }
 //#endregion
 //#region src/refs.ts
+const _refCache = /* @__PURE__ */ new WeakMap();
 /**
 * Resolves a local JSON pointer reference from a document.
 *
@@ -735,10 +708,31 @@ 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;
+	if (!$ref.startsWith("#")) return null;
+	$ref = globalThis.decodeURIComponent($ref.substring(1));
+	let docCache = _refCache.get(document);
+	if (!docCache) {
+		docCache = /* @__PURE__ */ new Map();
+		_refCache.set(document, docCache);
+	}
+	if (docCache.has($ref)) return docCache.get($ref);
 	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
-	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
+	if (!current) {
+		const diagnostic = {
+			code: Diagnostics.code.refNotFound,
+			severity: "error",
+			message: `Could not find a definition for ${origRef}.`,
+			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+			location: {
+				kind: "schema",
+				pointer: origRef,
+				ref: origRef
+			}
+		};
+		if (!Diagnostics.report(diagnostic)) throw new Diagnostics.Error(diagnostic);
+		return null;
+	}
+	docCache.set($ref, current);
 	return current;
 }
 /**
@@ -762,6 +756,35 @@ function dereferenceWithRef(document, schema) {
 	return schema;
 }
 //#endregion
+//#region src/dialect.ts
+/**
+* The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
+*
+* Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
+* decisions that differ between specs (nullability, `$ref`, discriminator, binary,
+* ref resolution) so the converter pipeline and dispatch rules stay shared. A
+* future adapter (e.g. AsyncAPI) ships its own dialect, `type: ['null', …]`
+* nullability, no discriminator object, binary via `contentEncoding` and reuses
+* the rest unchanged.
+*
+* Formats (`uuid`, `email`, dates, …) are intentionally NOT here: they are shared
+* JSON Schema vocabulary, so the converters keep that common case.
+*
+* @example
+* ```ts
+* const parser = createSchemaParser(context)             // uses oasDialect
+* const parser = createSchemaParser(context, oasDialect) // explicit
+* ```
+*/
+const oasDialect = ast.defineSchemaDialect({
+	name: "oas",
+	isNullable,
+	isReference,
+	isDiscriminator,
+	isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
+	resolveRef
+});
+//#endregion
 //#region src/resolvers.ts
 /**
 * Replaces `{variable}` placeholders in an OpenAPI server URL with provided values.
@@ -783,7 +806,16 @@ function resolveServerUrl(server, overrides) {
 	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(", ")}.`);
+		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Diagnostics.Error({
+			code: Diagnostics.code.invalidServerVariable,
+			severity: "error",
+			message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`,
+			help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,
+			location: {
+				kind: "document",
+				pointer: "#/servers"
+			}
+		});
 		url = url.replaceAll(`{${key}}`, value);
 	}
 	return url;
@@ -796,6 +828,15 @@ function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
+* `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
+* base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* diagnostic in step with the parser as `formatMap` grows.
+*/
+function isHandledFormat(format) {
+	return getSchemaType(format) !== null || specialCasedFormats.has(format);
+}
+/**
 * Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
 * Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
 */
@@ -805,12 +846,6 @@ function getPrimitiveType(type) {
 	return "string";
 }
 /**
-* Narrows a content-type string to the `MediaType` union Kubb recognizes, or returns `null`.
-*/
-function getMediaType(contentType) {
-	return Object.values(ast.mediaTypes).includes(contentType) ? contentType : null;
-}
-/**
 * Returns all parameters for an operation, merging path-level and operation-level entries.
 * Operation-level parameters override path-level ones with the same `in:name` key.
 * `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
@@ -898,7 +933,7 @@ function getRequestSchema(document, operation, options = {}) {
 /**
 * Flattens a keyword-only `allOf` into its parent schema.
 *
-* Only flattens when every member is a plain fragment — no `$ref` and no structural keywords
+* Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
 * (see `structuralKeys`). Outer schema values take precedence over fragment values.
 * Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
 *
@@ -908,7 +943,7 @@ function getRequestSchema(document, operation, options = {}) {
 * // { type: 'object', properties: {}, description: 'A pet' }
 *
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
-* // returned unchanged — contains a $ref
+* // returned unchanged, contains a $ref
 * ```
 */
 /**
@@ -934,7 +969,7 @@ function flattenSchema(schema) {
 /**
 * Extracts the inline schema from a media-type `content` map.
 *
-* Prefers `preferredContentType` when given; otherwise uses the first key in the 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
@@ -953,21 +988,22 @@ function extractSchemaFromContent(content, preferredContentType) {
 /**
 * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
 */
-function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
+function* collectRefs(schema) {
 	if (Array.isArray(schema)) {
-		for (const item of schema) collectRefs(item, refs);
-		return refs;
+		for (const item of schema) yield* collectRefs(item);
+		return;
 	}
 	if (schema && typeof schema === "object") for (const key in schema) {
 		const value = schema[key];
-		if (key === "$ref" && typeof value === "string") {
-			if (value.startsWith("#/components/schemas/")) {
-				const name = value.slice(21);
-				if (name) refs.add(name);
-			}
-		} else collectRefs(value, refs);
+		if (!(key === "$ref" && typeof value === "string")) {
+			yield* collectRefs(value);
+			continue;
+		}
+		if (value.startsWith("#/components/schemas/")) {
+			const name = value.slice(21);
+			if (name) yield name;
+		}
 	}
-	return refs;
 }
 /**
 * Returns a copy of `schemas` topologically sorted by `$ref` dependency.
@@ -983,7 +1019,7 @@ function collectRefs(schema, refs = /* @__PURE__ */ new Set()) {
 */
 function sortSchemas(schemas) {
 	const deps = /* @__PURE__ */ new Map();
-	for (const [name, schema] of Object.entries(schemas)) deps.set(name, Array.from(collectRefs(schema)));
+	for (const [name, schema] of Object.entries(schemas)) deps.set(name, [...new Set(collectRefs(schema))]);
 	const sorted = [];
 	const visited = /* @__PURE__ */ new Set();
 	function visit(name, stack) {
@@ -1118,15 +1154,16 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 		readOnly: schema.readOnly,
 		writeOnly: schema.writeOnly,
 		default: defaultValue,
-		example: schema.example
+		example: schema.example,
+		format: schema.format
 	};
 }
 /**
 * Returns all request body content type keys for an operation.
 *
-* The requestBody is dereferenced **in-place** when it is a `$ref` — the same mutation
-* that `getRequestSchema` already performs — so that the returned list accurately reflects
-* the available content types even for referenced bodies.
+* The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
+* `getRequestSchema` already performs), so the returned list accurately reflects the
+* available content types even for referenced bodies.
 *
 * @example
 * ```ts
@@ -1140,6 +1177,31 @@ function getRequestBodyContentTypes(document, operation) {
 	if (!body) return [];
 	return body.content ? Object.keys(body.content) : [];
 }
+/**
+* Returns all response content type keys for an operation at a given status code.
+*
+* Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
+* so the returned list reflects the available content types even for referenced responses.
+*
+* @example
+* ```ts
+* getResponseBodyContentTypes(document, operation, 200)
+* // ['application/json', 'application/xml']
+* ```
+*/
+function getResponseBodyContentTypes(document, operation, statusCode) {
+	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);
+		}
+	}
+	const responseObj = operation.getResponseByStatusCode(statusCode);
+	if (!responseObj || typeof responseObj !== "object" || isReference(responseObj)) return [];
+	const body = responseObj;
+	return body.content ? Object.keys(body.content) : [];
+}
 //#endregion
 //#region src/parser.ts
 /**
@@ -1168,9 +1230,9 @@ function normalizeArrayEnum(schema) {
 * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
 * made possible by hoisting of function declarations.
 *
-* @note Not exported; called internally by `parseOas()` and `parseSchema()`.
+* @internal
 */
-function createSchemaParser(ctx) {
+function createSchemaParser(ctx, dialect = oasDialect) {
 	const document = ctx.document;
 	/**
 	* Tracks `$ref` paths that are currently being resolved to prevent infinite
@@ -1178,6 +1240,15 @@ function createSchemaParser(ctx) {
 	*/
 	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
+	* Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
+	*
+	* Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
+	* it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
+	* since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
+	* Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
+	*/
+	const resolvedRefCache = /* @__PURE__ */ new Map();
+	/**
 	* Converts a `$ref` schema into a `RefSchemaNode`.
 	*
 	* The resolved schema is stored in `node.schema`. Usage-site sibling fields
@@ -1186,16 +1257,22 @@ function createSchemaParser(ctx) {
 	* Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
 	*/
 	function convertRef({ schema, name, nullable, defaultValue, rawOptions }) {
-		let resolvedSchema;
+		let resolvedSchema = null;
 		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);
+		if (refPath && !resolvingRefs.has(refPath)) {
+			if (!resolvedRefCache.has(refPath)) {
+				try {
+					const referenced = dialect.resolveRef(document, refPath);
+					if (referenced) {
+						resolvingRefs.add(refPath);
+						resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
+						resolvingRefs.delete(refPath);
+					}
+				} catch {}
+				resolvedRefCache.set(refPath, resolvedSchema);
 			}
-		} catch {}
+			resolvedSchema = resolvedRefCache.get(refPath) ?? null;
+		}
 		return ast.createSchema({
 			...buildSchemaNode(schema, name, nullable, defaultValue),
 			type: "ref",
@@ -1212,7 +1289,7 @@ function createSchemaParser(ctx) {
 			const [memberSchema] = schema.allOf;
 			const memberNode = parseSchema({
 				schema: memberSchema,
-				name: null
+				name
 			}, rawOptions);
 			const { kind: _kind, ...memberNodeProps } = memberNode;
 			const mergedNullable = nullable || memberNode.nullable || void 0;
@@ -1228,18 +1305,19 @@ function createSchemaParser(ctx) {
 				writeOnly: schema.writeOnly ?? memberNode.writeOnly,
 				default: mergedDefault,
 				example: schema.example ?? memberNode.example,
-				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0)
+				pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0),
+				format: schema.format ?? memberNode.format
 			});
 		}
 		const filteredDiscriminantValues = [];
 		const allOfMembers = schema.allOf.filter((item) => {
-			if (!isReference(item) || !name) return true;
-			const deref = resolveRef(document, item.$ref);
-			if (!deref || !isDiscriminator(deref)) return true;
+			if (!dialect.isReference(item) || !name) return true;
+			const deref = dialect.resolveRef(document, item.$ref);
+			if (!deref || !dialect.isDiscriminator(deref)) return true;
 			const parentUnion = deref.oneOf ?? deref.anyOf;
 			if (!parentUnion) return true;
 			const childRef = `${SCHEMA_REF_PREFIX}${name}`;
-			const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef);
+			const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef);
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			if (inOneOf || inMapping) {
 				const discriminatorValue = ast.findDiscriminator(deref.discriminator.mapping, childRef);
@@ -1250,22 +1328,28 @@ function createSchemaParser(ctx) {
 				return false;
 			}
 			return true;
-		}).map((s) => parseSchema({ schema: s }, rawOptions));
+		}).map((s) => parseSchema({
+			schema: s,
+			name
+		}, rawOptions));
 		const syntheticStart = allOfMembers.length;
 		if (Array.isArray(schema.required) && schema.required.length) {
 			const outerKeys = schema.properties ? new Set(Object.keys(schema.properties)) : /* @__PURE__ */ new Set();
 			const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
 			if (missingRequired.length) {
 				const resolvedMembers = schema.allOf.flatMap((item) => {
-					if (!isReference(item)) return [item];
-					const deref = resolveRef(document, item.$ref);
-					return deref && !isReference(deref) ? [deref] : [];
+					if (!dialect.isReference(item)) return [item];
+					const deref = dialect.resolveRef(document, item.$ref);
+					return deref && !dialect.isReference(deref) ? [deref] : [];
 				});
 				for (const key of missingRequired) for (const resolved of resolvedMembers) if (resolved.properties?.[key]) {
-					allOfMembers.push(parseSchema({ schema: {
-						properties: { [key]: resolved.properties[key] },
-						required: [key]
-					} }, rawOptions));
+					allOfMembers.push(parseSchema({
+						schema: {
+							properties: { [key]: resolved.properties[key] },
+							required: [key]
+						},
+						name
+					}, rawOptions));
 					break;
 				}
 			}
@@ -1280,7 +1364,7 @@ function createSchemaParser(ctx) {
 		}));
 		return ast.createSchema({
 			type: "intersection",
-			members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+			members: [...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
@@ -1301,10 +1385,10 @@ function createSchemaParser(ctx) {
 		const strategy = schema.oneOf ? "one" : "any";
 		const unionBase = {
 			...buildSchemaNode(schema, name, nullable, defaultValue),
-			discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
+			discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
 			strategy
 		};
-		const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
+		const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : void 0;
 		const sharedPropertiesNode = schema.properties ? (() => {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
 			return parseSchema({
@@ -1314,9 +1398,12 @@ function createSchemaParser(ctx) {
 		})() : void 0;
 		if (sharedPropertiesNode || discriminator?.mapping) {
 			const members = unionMembers.map((s) => {
-				const ref = isReference(s) ? s.$ref : void 0;
+				const ref = dialect.isReference(s) ? s.$ref : void 0;
 				const discriminatorValue = ast.findDiscriminator(discriminator?.mapping, ref);
-				const memberNode = parseSchema({ schema: s }, rawOptions);
+				const memberNode = parseSchema({
+					schema: s,
+					name
+				}, rawOptions);
 				if (!discriminatorValue || !discriminator) return memberNode;
 				const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.setDiscriminatorEnum({
 					node: sharedPropertiesNode,
@@ -1346,7 +1433,10 @@ function createSchemaParser(ctx) {
 		return ast.createSchema({
 			type: "union",
 			...unionBase,
-			members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({ schema: s }, rawOptions)))
+			members: ast.simplifyUnion(unionMembers.map((s) => parseSchema({
+				schema: s,
+				name
+			}, rawOptions)))
 		});
 	}
 	/**
@@ -1360,7 +1450,8 @@ function createSchemaParser(ctx) {
 			name,
 			title: schema.title,
 			description: schema.description,
-			deprecated: schema.deprecated
+			deprecated: schema.deprecated,
+			format: schema.format
 		});
 		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
 		return ast.createSchema({
@@ -1450,6 +1541,15 @@ function createSchemaParser(ctx) {
 		}, rawOptions);
 		const nullInEnum = schema.enum.includes(null);
 		const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
+		if (nullInEnum && filteredValues.length === 0) return ast.createSchema({
+			type: "null",
+			primitive: "null",
+			name,
+			title: schema.title,
+			description: schema.description,
+			deprecated: schema.deprecated,
+			format: schema.format
+		});
 		const enumNullable = nullable || nullInEnum || void 0;
 		const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
 		const enumPrimitive = getPrimitiveType(type);
@@ -1464,7 +1564,8 @@ function createSchemaParser(ctx) {
 			readOnly: schema.readOnly,
 			writeOnly: schema.writeOnly,
 			default: enumDefault,
-			example: schema.example
+			example: schema.example,
+			format: schema.format
 		};
 		const extensionKey = enumExtensionKeys.find((key) => key in schema);
 		if (extensionKey || enumPrimitive === "number" || enumPrimitive === "integer" || enumPrimitive === "boolean") {
@@ -1498,20 +1599,23 @@ function createSchemaParser(ctx) {
 		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 propNullable = dialect.isNullable(resolvedPropSchema);
 			const propNode = parseSchema({
 				schema: resolvedPropSchema,
 				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
-				};
-			}
+			const schemaNode = (() => {
+				const node = ast.setEnumName(propNode, name, propName, options.enumSuffix);
+				const tupleNode = ast.narrowSchema(node, "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])) return {
+						...tupleNode,
+						items: namedItems
+					};
+				}
+				return node;
+			})();
 			return ast.createProperty({
 				name: propName,
 				schema: {
@@ -1522,11 +1626,12 @@ function createSchemaParser(ctx) {
 			});
 		}) : [];
 		const additionalProperties = schema.additionalProperties;
-		let additionalPropertiesNode;
-		if (additionalProperties === true) additionalPropertiesNode = true;
-		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 additionalPropertiesNode = (() => {
+			if (additionalProperties === true) return true;
+			if (additionalProperties === false) return false;
+			if (additionalProperties && Object.keys(additionalProperties).length > 0) return parseSchema({ schema: additionalProperties }, rawOptions);
+			if (additionalProperties) return 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 ? ast.createSchema({ type: typeOptionMap.get(options.unknownType) }) : parseSchema({ schema: patternSchema }, rawOptions)])) : void 0;
 		const objectNode = ast.createSchema({
@@ -1539,7 +1644,7 @@ function createSchemaParser(ctx) {
 			maxProperties: schema.maxProperties,
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
-		if (isDiscriminator(schema) && schema.discriminator.mapping) {
+		if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
 			const discPropName = schema.discriminator.propertyName;
 			const values = Object.keys(schema.discriminator.mapping);
 			const enumName = name ? ast.enumPropName(name, discPropName, options.enumSuffix) : void 0;
@@ -1573,7 +1678,7 @@ function createSchemaParser(ctx) {
 	*/
 	function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }) {
 		const rawItems = schema.items;
-		const itemName = rawItems?.enum?.length && name ? ast.enumPropName(void 0, name, options.enumSuffix) : void 0;
+		const itemName = rawItems?.enum?.length && name ? ast.enumPropName(null, name, options.enumSuffix) : name;
 		const items = rawItems ? [parseSchema({
 			schema: rawItems,
 			name: itemName
@@ -1637,15 +1742,148 @@ function createSchemaParser(ctx) {
 			title: schema.title,
 			description: schema.description,
 			deprecated: schema.deprecated,
-			nullable
+			nullable,
+			format: schema.format
+		});
+	}
+	/**
+	* Converts a binary string schema (`type: 'string'`, `contentMediaType: 'application/octet-stream'`)
+	* into a `blob` node.
+	*/
+	function convertBlob({ schema, name, nullable, defaultValue }) {
+		return ast.createSchema({
+			type: "blob",
+			primitive: "string",
+			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
+	* Converts an OAS 3.1 multi-type array (e.g. `type: ['string', 'number']`) into a `UnionSchemaNode`.
+	*
+	* Returns `null` when only one non-`null` type remains (e.g. `['string', 'null']`), so `parseSchema`
+	* falls through and handles it as that single type with nullability already folded in.
+	*/
+	function convertMultiType({ schema, name, nullable, defaultValue, rawOptions }) {
+		const types = schema.type;
+		const nonNullTypes = types.filter((t) => t !== "null");
+		if (nonNullTypes.length <= 1) return null;
+		const arrayNullable = types.includes("null") || nullable || void 0;
+		return ast.createSchema({
+			type: "union",
+			members: nonNullTypes.map((t) => parseSchema({
+				schema: {
+					...schema,
+					type: t
+				},
+				name
+			}, rawOptions)),
+			...buildSchemaNode(schema, name, arrayNullable, defaultValue)
+		});
+	}
+	/**
+	* Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
+	* `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
+	* `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
+	* match/convert/fall-through contract.
+	*/
+	const schemaRules = [
+		{
+			name: "ref",
+			match: ({ schema }) => dialect.isReference(schema),
+			convert: convertRef
+		},
+		{
+			name: "allOf",
+			match: ({ schema }) => !!schema.allOf?.length,
+			convert: convertAllOf
+		},
+		{
+			name: "union",
+			match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length),
+			convert: convertUnion
+		},
+		{
+			name: "const",
+			match: ({ schema }) => "const" in schema && schema.const !== void 0,
+			convert: convertConst
+		},
+		{
+			name: "format",
+			match: ({ schema }) => !!schema.format,
+			convert: convertFormat
+		},
+		{
+			name: "blob",
+			match: ({ schema }) => dialect.isBinary(schema),
+			convert: convertBlob
+		},
+		{
+			name: "multi-type",
+			match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1,
+			convert: convertMultiType
+		},
+		{
+			name: "constrained-string",
+			match: ({ schema, type }) => !type && (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0),
+			convert: convertString
+		},
+		{
+			name: "constrained-number",
+			match: ({ schema, type }) => !type && (schema.minimum !== void 0 || schema.maximum !== void 0),
+			convert: (ctx) => convertNumeric(ctx, "number")
+		},
+		{
+			name: "enum",
+			match: ({ schema }) => !!schema.enum?.length,
+			convert: convertEnum
+		},
+		{
+			name: "object",
+			match: ({ schema, type }) => type === "object" || !!schema.properties || !!schema.additionalProperties || "patternProperties" in schema,
+			convert: convertObject
+		},
+		{
+			name: "tuple",
+			match: ({ schema }) => "prefixItems" in schema,
+			convert: convertTuple
+		},
+		{
+			name: "array",
+			match: ({ schema, type }) => type === "array" || "items" in schema,
+			convert: convertArray
+		},
+		{
+			name: "string",
+			match: ({ type }) => type === "string",
+			convert: convertString
+		},
+		{
+			name: "number",
+			match: ({ type }) => type === "number",
+			convert: (ctx) => convertNumeric(ctx, "number")
+		},
+		{
+			name: "integer",
+			match: ({ type }) => type === "integer",
+			convert: (ctx) => convertNumeric(ctx, "integer")
+		},
+		{
+			name: "boolean",
+			match: ({ type }) => type === "boolean",
+			convert: convertBoolean
+		},
+		{
+			name: "null",
+			match: ({ type }) => type === "null",
+			convert: convertNull
+		}
+	];
+	/**
 	* Central dispatcher that converts an OAS `SchemaObject` into a `SchemaNode`.
 	*
-	* 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).
+	* Builds the per-schema context, then runs it through the ordered {@link schemaRules} table
+	* via {@link ast.dispatch}. When no rule produces a node, falls back to the configured
+	* `emptySchemaType`.
 	*/
 	function parseSchema({ schema, name }, rawOptions) {
 		const options = {
@@ -1657,75 +1895,40 @@ function createSchemaParser(ctx) {
 			schema: flattenedSchema,
 			name
 		}, 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;
-		const ctx = {
+		const nullable = dialect.isNullable(schema) || void 0;
+		const schemaCtx = {
 			schema,
 			name,
 			nullable,
-			defaultValue,
-			type,
+			defaultValue: schema.default === null && nullable ? void 0 : schema.default,
+			type: Array.isArray(schema.type) ? schema.type[0] : schema.type,
 			rawOptions,
 			options
 		};
-		if (isReference(schema)) return convertRef(ctx);
-		if (schema.allOf?.length) return convertAllOf(ctx);
-		if ([...schema.oneOf ?? [], ...schema.anyOf ?? []].length) return convertUnion(ctx);
-		if ("const" in schema && schema.const !== void 0) return convertConst(ctx);
-		if (schema.format) {
-			const formatResult = convertFormat(ctx);
-			if (formatResult) return formatResult;
-		}
-		if (schema.type === "string" && schema.contentMediaType === "application/octet-stream") return ast.createSchema({
-			type: "blob",
-			primitive: "string",
-			...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 ast.createSchema({
-				type: "union",
-				members: nonNullTypes.map((t) => parseSchema({
-					schema: {
-						...schema,
-						type: t
-					},
-					name
-				}, rawOptions)),
-				...buildSchemaNode(schema, name, arrayNullable, defaultValue)
-			});
-		}
-		if (!type) {
-			if (schema.minLength !== void 0 || schema.maxLength !== void 0 || schema.pattern !== void 0) return convertString(ctx);
-			if (schema.minimum !== void 0 || schema.maximum !== void 0) return convertNumeric(ctx, "number");
-		}
-		if (schema.enum?.length) return convertEnum(ctx);
-		if (type === "object" || schema.properties || schema.additionalProperties || "patternProperties" in schema) return convertObject(ctx);
-		if ("prefixItems" in schema) return convertTuple(ctx);
-		if (type === "array" || "items" in schema) return convertArray(ctx);
-		if (type === "string") return convertString(ctx);
-		if (type === "number") return convertNumeric(ctx, "number");
-		if (type === "integer") return convertNumeric(ctx, "integer");
-		if (type === "boolean") return convertBoolean(ctx);
-		if (type === "null") return convertNull(ctx);
+		const node = ast.dispatch(schemaRules, schemaCtx);
+		if (node) return node;
 		const emptyType = typeOptionMap.get(options.emptySchemaType);
 		return ast.createSchema({
 			type: emptyType,
 			name,
 			title: schema.title,
-			description: schema.description
+			description: schema.description,
+			format: schema.format
 		});
 	}
 	/**
 	* Converts a dereferenced OAS parameter object into a `ParameterNode`.
 	*/
-	function parseParameter(options, param) {
+	function parseParameter(options, param, parentName) {
 		const required = param["required"] ?? false;
-		const schema = param["schema"] ? parseSchema({ schema: param["schema"] }, options) : ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
+		const paramName = param["name"];
+		const schemaName = parentName && paramName ? pascalCase(`${parentName} ${paramName}`) : void 0;
+		const schema = param["schema"] ? parseSchema({
+			schema: param["schema"],
+			name: schemaName
+		}, options) : ast.createSchema({ type: typeOptionMap.get(options.unknownType) });
 		return ast.createParameter({
-			name: param["name"],
+			name: paramName,
 			in: param["in"],
 			schema: {
 				...schema,
@@ -1762,27 +1965,33 @@ function createSchemaParser(ctx) {
 	* `$ref` entries are skipped since their flags live on the dereferenced target.
 	*/
 	function collectPropertyKeysByFlag(schema, flag) {
-		if (!schema?.properties) return void 0;
+		if (!schema?.properties) return null;
 		const keys = [];
 		for (const key in schema.properties) {
 			const prop = schema.properties[key];
-			if (prop && !isReference(prop) && prop[flag]) keys.push(key);
+			if (prop && !dialect.isReference(prop) && prop[flag]) keys.push(key);
 		}
-		return keys.length ? keys : void 0;
+		return keys.length ? keys : null;
 	}
 	/**
 	* Converts an OAS `Operation` into an `OperationNode`.
 	*/
 	function parseOperation(options, operation) {
-		const parameters = getParameters(document, operation).map((param) => parseParameter(options, param));
+		const operationId = operation.getOperationId();
+		const operationName = operationId ? pascalCase(operationId) : void 0;
+		const parameters = getParameters(document, operation).map((param) => parseParameter(options, param, operationName));
 		const allContentTypes = ctx.contentType ? [ctx.contentType] : getRequestBodyContentTypes(document, operation);
 		const requestBodyMeta = getRequestBodyMeta(operation);
+		const requestBodyName = operationName ? `${operationName}Request` : void 0;
 		const content = allContentTypes.flatMap((ct) => {
 			const schema = getRequestSchema(document, operation, { contentType: ct });
 			if (!schema) return [];
 			return [{
 				contentType: ct,
-				schema: ast.syncOptionality(parseSchema({ schema }, options), requestBodyMeta.required),
+				schema: ast.syncOptionality(parseSchema({
+					schema,
+					name: requestBodyName
+				}, options), requestBodyMeta.required),
 				keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
 			}];
 		});
@@ -1793,21 +2002,36 @@ function createSchemaParser(ctx) {
 		} : void 0;
 		const responses = operation.getResponseStatusCodes().map((statusCode) => {
 			const responseObj = operation.getResponseByStatusCode(statusCode);
-			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 ?? "");
+			const responseName = operationName ? `${operationName}Status${statusCode}` : void 0;
+			const { description } = getResponseMeta(responseObj);
+			const parseEntrySchema = (contentType) => {
+				const raw = getResponseSchema(document, operation, statusCode, { contentType });
+				return {
+					schema: raw && Object.keys(raw).length > 0 ? parseSchema({
+						schema: raw,
+						name: responseName
+					}, options) : ast.createSchema({ type: typeOptionMap.get(options.emptySchemaType) }),
+					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
+				};
+			};
+			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ({
+				contentType,
+				...parseEntrySchema(contentType)
+			}));
+			if (content.length === 0) content.push({
+				contentType: operation.contentType || "application/json",
+				...parseEntrySchema(ctx.contentType)
+			});
 			return ast.createResponse({
 				statusCode,
 				description,
-				schema,
-				mediaType,
-				keysToOmit: collectPropertyKeysByFlag(responseSchema, "writeOnly")
+				content
 			});
 		});
 		const urlPath = new URLPath(operation.path);
 		return ast.createOperation({
-			operationId: operation.getOperationId(),
+			operationId,
+			protocol: "http",
 			method: operation.method.toUpperCase(),
 			path: urlPath.path,
 			tags: operation.getTags().map((tag) => tag.name),
@@ -1825,59 +2049,336 @@ function createSchemaParser(ctx) {
 		parseParameter
 	};
 }
+//#endregion
+//#region src/discriminator.ts
+/**
+* Builds a map of child schema names → discriminator patch data by scanning the given
+* top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
+*
+* The streaming path calls this on a small pre-parsed subset of schemas (only the
+* discriminator parents) rather than on all schemas at once.
+*/
+function buildDiscriminatorChildMap(schemas) {
+	const childMap = /* @__PURE__ */ new Map();
+	for (const schema of 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 = null;
+			let objNode = null;
+			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") : null;
+			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) {
+				childMap.set(refNode.name, {
+					propertyName: discriminatorPropertyName,
+					enumValues: [...enumValues]
+				});
+				continue;
+			}
+			existing.enumValues.push(...enumValues);
+		}
+	}
+	return childMap;
+}
+/**
+* Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+* the discriminant property). Used by the streaming path to apply patches inline per yield
+* without buffering all schemas.
+*/
+function patchDiscriminatorNode(node, entry) {
+	const objectNode = ast.narrowSchema(node, "object");
+	if (!objectNode) return node;
+	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 src/schemaDiagnostics.ts
+/**
+* Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
+* top-level schema. Walks the node the parser produced during `preScan`, threading the RFC 6901
+* pointer as it descends so a nested field reports against its full path
+* (`#/components/schemas/Pet/properties/owner/properties/name`). Refs are not followed, so the
+* resolved schema is reported under its own walk. Reports land in the active build run, are a
+* no-op outside one, and repeats are deduped by the build.
+*/
+function reportSchemaDiagnostics({ node, name }) {
+	visit(node, `#/components/schemas/${escapePointerToken(name)}`);
+}
+/**
+* Escapes a single JSON pointer reference token per RFC 6901 (`~` → `~0`, `/` → `~1`), so a
+* property name with those characters maps to a distinct pointer instead of colliding in the dedupe.
+*/
+function escapePointerToken(token) {
+	return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function visit(node, pointer) {
+	if (node.deprecated) Diagnostics.report({
+		code: Diagnostics.code.deprecated,
+		severity: "info",
+		message: "This schema is marked as deprecated.",
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (typeof node.format === "string" && !isHandledFormat(node.format)) Diagnostics.report({
+		code: Diagnostics.code.unsupportedFormat,
+		severity: "warning",
+		message: `Kubb does not map the format "${node.format}" to a specific type, so it falls back to the base type.`,
+		help: `Use a format Kubb supports, or handle "${node.format}" with a custom parser or plugin.`,
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (node.type === "object") {
+		for (const property of node.properties) visit(property.schema, `${pointer}/properties/${escapePointerToken(property.name)}`);
+		if (node.additionalProperties && typeof node.additionalProperties === "object") visit(node.additionalProperties, `${pointer}/additionalProperties`);
+		return;
+	}
+	if (node.type === "array") {
+		for (const item of node.items ?? []) visit(item, `${pointer}/items`);
+		return;
+	}
+	if (node.type === "tuple") {
+		for (const [index, item] of (node.items ?? []).entries()) visit(item, `${pointer}/items/${index}`);
+		return;
+	}
+	if (node.type === "union" || node.type === "intersection") for (const [index, member] of (node.members ?? []).entries()) visit(member, `${pointer}/members/${index}`);
+}
+//#endregion
+//#region src/stream.ts
+/**
+* Builds the deduplication plan from the already-parsed top-level schema nodes plus a
+* single extra parse pass over operations (so duplicates in request/response bodies are seen).
+*
+* Only enums and objects are candidates, and object shapes that reference a circular schema are
+* rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
+* name (collision-resolved against existing component names); shapes without a name stay inline.
+*/
+function createDedupePlan({ schemaNodes, operationNodes, schemaNames, circularNames }) {
+	const circularSchemas = new Set(circularNames);
+	const usedNames = new Set(schemaNames);
+	return ast.buildDedupePlan([...schemaNodes, ...operationNodes], {
+		isCandidate: (node) => {
+			if (node.type === "enum") return true;
+			if (node.type !== "object") return false;
+			if (node.name && circularSchemas.has(node.name)) return false;
+			return !ast.containsCircularRef(node, { circularSchemas });
+		},
+		nameFor: (node) => {
+			const base = node.name;
+			if (!base) return null;
+			let name = base;
+			let counter = 2;
+			while (usedNames.has(name)) name = `${base}${counter++}`;
+			usedNames.add(name);
+			return name;
+		},
+		refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`
+	});
+}
+/**
+* Reads the server URL from the document's `servers` array at `serverIndex`,
+* interpolating any `serverVariables` into the URL template.
+*
+* Returns `null` when `serverIndex` is omitted or out of range.
+*
+* @example Resolve the first server
+* `resolveBaseUrl({ document, serverIndex: 0 })`
+*
+* @example Override a path variable
+* `resolveBaseUrl({ document, serverIndex: 0, serverVariables: { version: 'v2' } })`
+*/
+function resolveBaseUrl({ document, serverIndex, serverVariables }) {
+	const server = serverIndex !== void 0 ? document.servers?.at(serverIndex) : void 0;
+	return server?.url ? resolveServerUrl(server, serverVariables) : null;
+}
 /**
-* Parses an OpenAPI specification into Kubb's universal `InputNode` AST.
+* Parses every schema once to build the lookup structures that streaming needs upfront.
+*
+* Three things happen in this single pass:
+* - `refAliasMap` records schemas that are pure `$ref` aliases so the streaming pass can inline them.
+* - `enumNames` collects the names of every enum schema so plugins skip re-scanning the stream.
+* - `circularNames` runs cycle detection, which requires all nodes in memory simultaneously.
+*   The `allNodes` array is local and drops out of scope as soon as this function returns.
 *
-* This is the main entry point for `@kubb/adapter-oas`. It converts OpenAPI/Swagger specs into a spec-agnostic tree
-* that downstream plugins (`plugin-ts`, `plugin-zod`, etc.) consume for code generation. No code is generated here —
-* the tree is a pure data structure representing all schemas and operations.
+* After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
+* Both are proportional to the number of aliases or discriminator parents, not total schema count.
 *
-* Returns the AST root and a `nameMapping` for resolving schema references.
+* Each schema is parsed again during the streaming pass. This is intentional.
+* Holding the parsed nodes in memory here would defeat the streaming memory benefit.
 *
 * @example
 * ```ts
-* import { parseOas } from '@kubb/adapter-oas'
-*
-* const document = await parseFromConfig(config)
-* const { root, nameMapping } = parseOas(document, { dateType: 'date', contentType: 'application/json' })
+* const { refAliasMap, enumNames, circularNames } = preScan({
+*   schemas,
+*   parseSchema,
+*   parserOptions,
+*   discriminator: 'strict',
+* })
 * ```
 */
-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));
+function preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe }) {
+	const allNodes = [];
+	const refAliasMap = /* @__PURE__ */ new Map();
+	const enumNames = [];
+	const discriminatorParentNodes = [];
+	for (const [name, schema] of Object.entries(schemas)) {
+		const node = parseSchema({
+			schema,
+			name
+		}, parserOptions);
+		allNodes.push(node);
+		reportSchemaDiagnostics({
+			node,
+			name
+		});
+		if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
+		if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) enumNames.push(node.name);
+		if (discriminator === "inherit" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
+	}
+	const circularNames = [...ast.findCircularSchemas(allNodes)];
+	const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null;
+	let dedupePlan = null;
+	if (dedupe) {
+		const operationNodes = [];
+		for (const methods of Object.values(baseOas.getPaths())) for (const operation of Object.values(methods)) {
+			if (!operation) continue;
+			const operationNode = parseOperation(parserOptions, operation);
+			if (operationNode) operationNodes.push(operationNode);
+		}
+		dedupePlan = createDedupePlan({
+			schemaNodes: allNodes,
+			operationNodes,
+			schemaNames: Object.keys(schemas),
+			circularNames
+		});
+		for (const definition of dedupePlan.hoisted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
+	}
 	return {
-		root: ast.createInput({
-			schemas,
-			operations
-		}),
-		nameMapping
+		refAliasMap,
+		enumNames,
+		circularNames,
+		discriminatorChildMap,
+		dedupePlan
+	};
+}
+/**
+* Creates a lazy `InputStreamNode` from already-resolved adapter state.
+*
+* The schema and operation iterables each start a fresh parse pass on every
+* `[Symbol.asyncIterator]()` call. This lets multiple plugins consume the same
+* stream object independently without sharing a cursor or holding all nodes in memory.
+*
+* Ref aliases in `refAliasMap` are inlined during iteration: an alias entry is replaced
+* with its target's parsed node (but keeps the alias name) so plugins never receive bare `ref` nodes.
+*
+* @example
+* ```ts
+* const streamNode = createInputStream({ schemas, parseSchema, parseOperation, baseOas, parserOptions, refAliasMap, discriminatorChildMap, meta })
+* for await (const schema of streamNode.schemas) {
+*   // each call to for-await restarts from the first schema
+* }
+* ```
+*/
+function createInputStream({ schemas, parseSchema, parseOperation, baseOas, parserOptions, refAliasMap, discriminatorChildMap, dedupePlan, meta }) {
+	const rewriteTopLevelSchema = (node) => {
+		if (!dedupePlan) return node;
+		const canonical = dedupePlan.canonicalBySignature.get(ast.schemaSignature(node));
+		if (canonical && canonical.name !== node.name) return ast.createSchema({
+			type: "ref",
+			name: node.name ?? null,
+			ref: canonical.ref,
+			description: node.description,
+			deprecated: node.deprecated
+		});
+		return ast.applyDedupe(node, dedupePlan.canonicalBySignature, true);
 	};
+	const schemasIterable = { [Symbol.asyncIterator]() {
+		return (async function* () {
+			if (dedupePlan) for (const definition of dedupePlan.hoisted) yield definition;
+			for (const [name, schema] of Object.entries(schemas)) {
+				const alias = refAliasMap.get(name);
+				if (alias?.name && schemas[alias.name]) {
+					yield rewriteTopLevelSchema({
+						...parseSchema({
+							schema: schemas[alias.name],
+							name: alias.name
+						}, parserOptions),
+						name
+					});
+					continue;
+				}
+				const parsed = parseSchema({
+					schema,
+					name
+				}, parserOptions);
+				yield rewriteTopLevelSchema(discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed);
+			}
+		})();
+	} };
+	const operationsIterable = { [Symbol.asyncIterator]() {
+		return (async function* () {
+			for (const methods of Object.values(baseOas.getPaths())) for (const operation of Object.values(methods)) {
+				if (!operation) continue;
+				const node = parseOperation(parserOptions, operation);
+				if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan.canonicalBySignature) : node;
+			}
+		})();
+	} };
+	return ast.createStreamInput(schemasIterable, operationsIterable, meta);
 }
 //#endregion
 //#region src/adapter.ts
 /**
-* Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+* Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
 */
 const adapterOasName = "oas";
 /**
-* Creates the default OpenAPI / Swagger adapter for Kubb.
+* Default Kubb adapter for OpenAPI 2.0, 3.0, and 3.1 specifications. Reads the
+* file at `input.path`, validates it, resolves the base URL, and converts every
+* schema and operation into the universal AST that every downstream plugin
+* consumes.
 *
-* Parses the spec, optionally validates it, resolves the base URL, and converts
-* everything into an `InputNode` that downstream plugins consume.
+* Configure once on `defineConfig`. The adapter's choices (date representation,
+* integer width, server URL) apply to every plugin in the build.
 *
 * @example
 * ```ts
@@ -1886,17 +2387,118 @@ const adapterOasName = "oas";
 * import { pluginTs } from '@kubb/plugin-ts'
 *
 * export default defineConfig({
-*   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
-*   input: { path: './openapi.yaml' },
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas({
+*     serverIndex: 0,
+*     discriminator: 'inherit',
+*     dateType: 'date',
+*   }),
 *   plugins: [pluginTs()],
 * })
 * ```
 */
 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;
+	const { validate = true, contentType, serverIndex, serverVariables, discriminator = "strict", dedupe = true, dateType = DEFAULT_PARSER_OPTIONS.dateType, integerType = DEFAULT_PARSER_OPTIONS.integerType, unknownType = DEFAULT_PARSER_OPTIONS.unknownType, enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix, emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType } = options;
+	const parserOptions = {
+		...DEFAULT_PARSER_OPTIONS,
+		dateType,
+		integerType,
+		unknownType,
+		emptySchemaType,
+		enumSuffix
+	};
 	let nameMapping = /* @__PURE__ */ new Map();
-	let parsedDocument;
-	let inputNode;
+	let parsedDocument = null;
+	const documentCache = /* @__PURE__ */ new WeakMap();
+	const schemasCache = /* @__PURE__ */ new WeakMap();
+	const baseOasCache = /* @__PURE__ */ new WeakMap();
+	const schemaParserCache = /* @__PURE__ */ new WeakMap();
+	const preScanCache = /* @__PURE__ */ new WeakMap();
+	function ensureDocument(source) {
+		const cached = documentCache.get(source);
+		if (cached) return cached;
+		const promise = (async () => {
+			const fresh = await parseFromConfig(source);
+			if (validate) await validateDocument(fresh);
+			parsedDocument = fresh;
+			return fresh;
+		})();
+		documentCache.set(source, promise);
+		return promise;
+	}
+	function ensureSchemas(document) {
+		const cached = schemasCache.get(document);
+		if (cached) return cached;
+		const promise = Promise.resolve().then(() => {
+			const result = getSchemas(document, { contentType });
+			nameMapping = result.nameMapping;
+			return result.schemas;
+		});
+		schemasCache.set(document, promise);
+		return promise;
+	}
+	function ensureBaseOas(document) {
+		const cached = baseOasCache.get(document);
+		if (cached) return cached;
+		const baseOas = new BaseOas(document);
+		baseOasCache.set(document, baseOas);
+		return baseOas;
+	}
+	function ensureSchemaParser(document) {
+		const cached = schemaParserCache.get(document);
+		if (cached) return cached;
+		const parser = createSchemaParser({
+			document,
+			contentType
+		});
+		schemaParserCache.set(document, parser);
+		return parser;
+	}
+	function ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas) {
+		const cached = preScanCache.get(document);
+		if (cached) return cached;
+		const result = preScan({
+			schemas,
+			parseSchema,
+			parseOperation,
+			baseOas,
+			parserOptions,
+			discriminator,
+			dedupe
+		});
+		preScanCache.set(document, result);
+		return result;
+	}
+	async function createStream(source) {
+		const document = await ensureDocument(source);
+		const schemas = await ensureSchemas(document);
+		const { parseSchema, parseOperation } = ensureSchemaParser(document);
+		const baseOas = ensureBaseOas(document);
+		const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas);
+		return createInputStream({
+			schemas,
+			parseSchema,
+			parseOperation,
+			baseOas,
+			parserOptions,
+			refAliasMap,
+			discriminatorChildMap,
+			dedupePlan,
+			meta: {
+				title: document.info?.title,
+				description: document.info?.description,
+				version: document.info?.version,
+				baseURL: resolveBaseUrl({
+					document,
+					serverIndex,
+					serverVariables
+				}),
+				circularNames,
+				enumNames
+			}
+		});
+	}
 	return {
 		name: "oas",
 		get options() {
@@ -1906,6 +2508,7 @@ const adapterOas = createAdapter((options) => {
 				serverIndex,
 				serverVariables,
 				discriminator,
+				dedupe,
 				dateType,
 				integerType,
 				unknownType,
@@ -1917,8 +2520,9 @@ const adapterOas = createAdapter((options) => {
 		get document() {
 			return parsedDocument;
 		},
-		get inputNode() {
-			return inputNode;
+		async validate(input, options) {
+			await assertInputExists(input);
+			await validateDocument(await parseDocument(input), options);
 		},
 		getImports(node, resolve) {
 			return ast.collectImports({
@@ -1926,7 +2530,7 @@ const adapterOas = createAdapter((options) => {
 				nameMapping,
 				resolve: (schemaName) => {
 					const result = resolve(schemaName);
-					if (!result) return;
+					if (!result) return null;
 					return ast.createImport({
 						name: [result.name],
 						path: result.path
@@ -1935,32 +2539,20 @@ const adapterOas = createAdapter((options) => {
 			});
 		},
 		async parse(source) {
-			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 { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-				contentType,
-				dateType,
-				integerType,
-				unknownType,
-				emptySchemaType,
-				enumSuffix
-			});
-			const node = discriminator === "inherit" ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot;
-			nameMapping = parsedNameMapping;
-			parsedDocument = document;
-			inputNode = ast.createInput({
-				...node,
-				meta: {
-					title: document.info?.title,
-					description: document.info?.description,
-					version: document.info?.version,
-					baseURL
-				}
+			const streamNode = await createStream(source);
+			const collect = async (iter) => {
+				const out = [];
+				for await (const item of iter) out.push(item);
+				return out;
+			};
+			const [schemas, operations] = await Promise.all([collect(streamNode.schemas), collect(streamNode.operations)]);
+			return ast.createInput({
+				schemas,
+				operations,
+				meta: streamNode.meta
 			});
-			return inputNode;
-		}
+		},
+		stream: createStream
 	};
 });
 //#endregion
@@ -1976,6 +2568,6 @@ const adapterOas = createAdapter((options) => {
 */
 const HttpMethods = Object.fromEntries(Object.entries(ast.httpMethods).map(([lower, upper]) => [upper, lower]));
 //#endregion
-export { HttpMethods, adapterOas, adapterOasName, mergeDocuments, parseDocument, parseFromConfig, validateDocument };
+export { HttpMethods, adapterOas, adapterOasName, mergeDocuments };
 
 //# sourceMappingURL=index.js.map