@kubb/adapter-oas 5.0.0-alpha.1 → 5.0.0-alpha.11

package/dist/index.js

@@ -1,7 +1,7 @@
 import "./chunk--u3MIqq1.js";
 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 { createAdapter } from "@kubb/core";
 import { bundle, loadConfig } from "@redocly/openapi-core";
 import yaml from "@stoplight/yaml";
 import { isRef } from "oas/types";
@@ -11,6 +11,110 @@ import swagger2openapi from "swagger2openapi";
 import jsonpointer from "jsonpointer";
 import BaseOas from "oas";
 import { matchesMimeType } from "oas/utils";
+//#region src/constants.ts
+/**
+* Default values for all `Options` fields.
+*/
+const DEFAULT_PARSER_OPTIONS = {
+	dateType: "string",
+	integerType: "number",
+	unknownType: "any",
+	emptySchemaType: "any",
+	enumSuffix: "enum"
+};
+/**
+* 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"
+]);
+/**
+* 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.
+*
+* 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.
+*/
+const knownMediaTypes = new Set([
+	"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"];
+/**
+* Scalar primitive schema types used for union member simplification.
+*/
+const SCALAR_PRIMITIVE_TYPES = new Set([
+	"string",
+	"number",
+	"integer",
+	"bigint",
+	"boolean"
+]);
+//#endregion
 //#region src/oas/resolveServerUrl.ts
 /**
 * Resolves an OpenAPI server URL by substituting `{variable}` placeholders.
@@ -89,6 +193,27 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/names.ts
+/**
+* Returns a unique name by appending an incrementing numeric suffix when the name has already been used.
+* Mutates `data` in-place as a usage counter so subsequent calls remain consistent.
+*
+* @example
+* const seen: Record<string, number> = {}
+* getUniqueName('Foo', seen) // 'Foo'
+* getUniqueName('Foo', seen) // 'Foo2'
+* getUniqueName('Foo', seen) // 'Foo3'
+*/
+function getUniqueName(originalName, data) {
+	let used = data[originalName] || 0;
+	if (used) {
+		data[originalName] = ++used;
+		originalName += used;
+	}
+	data[originalName] = 1;
+	return originalName;
+}
+//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * Returns `true` when `name` is a syntactically valid JavaScript variable name.
@@ -205,91 +330,6 @@ var URLPath = class {
 	}
 };
 //#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"
-]);
-/**
-* 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.
-*
-* 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.
@@ -501,8 +541,15 @@ var Oas = class extends BaseOas {
 		if (!schema) return;
 		return this.dereferenceWithRef(schema);
 	}
-	getParametersSchema(operation, inKey) {
-		const { contentType = operation.getContentType() } = this.#options;
+	/**
+	* Returns all resolved parameters for an operation, merging path-level and operation-level
+	* parameters and deduplicating by `in:name` (operation-level takes precedence).
+	*
+	* oas v31+ filters out `$ref` parameters in `getParameters()`, so this method accesses the
+	* raw `operation.schema.parameters` and path-item parameters directly and resolves `$ref`
+	* pointers via `dereferenceWithRef` to preserve backward compatibility.
+	*/
+	getParameters(operation) {
 		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];
@@ -510,7 +557,11 @@ var Oas = class extends BaseOas {
 		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);
+		return Array.from(paramMap.values());
+	}
+	getParametersSchema(operation, inKey) {
+		const { contentType = operation.getContentType() } = this.#options;
+		const params = this.getParameters(operation).filter((v) => v.in === inKey);
 		if (!params.length) return null;
 		return params.reduce((schema, pathParameters) => {
 			const property = pathParameters.content?.[contentType]?.schema ?? pathParameters.schema;
@@ -900,17 +951,137 @@ function resolveCollisions(schemasWithMeta) {
 	};
 }
 //#endregion
-//#region src/parser.ts
+//#region src/utils.ts
 /**
-* Default values for all `Options` fields.
+* 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.
 */
-const DEFAULT_OPTIONS = {
-	dateType: "string",
-	integerType: "number",
-	unknownType: "any",
-	emptySchemaType: "any",
-	enumSuffix: "enum"
-};
+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.
+*
+* Const-derived enums (those without an `enumType`, produced from an OpenAPI `const`
+* keyword) are **never** removed — `'accepted' | string` must stay as-is because the
+* literal is intentional.
+*/
+function simplifyUnionMembers(members) {
+	const scalarPrimitives = new Set(members.filter((m) => SCALAR_PRIMITIVE_TYPES.has(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 (!m.enumType) 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,
+*   }),
+* })
+* ```
+*/
+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;
+		return {
+			name: [result.name],
+			path: result.path
+		};
+	} });
+}
+//#endregion
+//#region src/parser.ts
 /**
 * Looks up the Kubb `SchemaType` for a given OAS `format` string.
 * Returns `undefined` for formats not in `formatMap` (e.g. `int64`, `date-time`),
@@ -920,14 +1091,6 @@ function formatToSchemaType(format) {
 	return formatMap[format];
 }
 /**
-* Extracts the final path segment of a JSON Pointer `$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;
-}
-/**
 * 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'`.
@@ -942,27 +1105,7 @@ function getPrimitiveType(type) {
 * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
 */
 function toMediaType(contentType) {
-	return knownMediaTypes.includes(contentType) ? contentType : void 0;
-}
-/**
-* When a discriminator is present, replaces the discriminator property's schema with
-* an enum of the mapping keys so downstream code emits a precise literal-union type.
-* Returns the original schema unchanged when there is no discriminator or no mapping.
-*/
-function applyDiscriminatorEnum(schema) {
-	if (!isDiscriminator(schema)) return schema;
-	const propName = schema.discriminator.propertyName;
-	if (!schema.properties?.[propName]) return schema;
-	return {
-		...schema,
-		properties: {
-			...schema.properties,
-			[propName]: {
-				...schema.properties[propName],
-				enum: schema.discriminator.mapping ? Object.keys(schema.discriminator.mapping) : void 0
-			}
-		}
-	};
+	return knownMediaTypes.has(contentType) ? contentType : void 0;
 }
 /**
 * Creates an OAS parser that converts an OpenAPI/Swagger spec into
@@ -988,6 +1131,8 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		contentType,
 		collisionDetection
 	});
+	const usedEnumNames = {};
+	const isLegacyNaming = collisionDetection === false;
 	/**
 	* Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
 	* Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
@@ -1034,7 +1179,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* Shared metadata fields included in every `createSchema` call.
 	* Centralizes the common properties so sub-handlers don't repeat them.
 	*/
-	function buildSchemaBase(schema, name, nullable, defaultValue) {
+	function renderSchemaBase(schema, name, nullable, defaultValue) {
 		return {
 			name,
 			nullable,
@@ -1055,18 +1200,17 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* reflected in generated JSDoc and type modifiers.
 	*/
 	function convertRef({ schema, nullable, defaultValue }) {
-		const schemaObject = schema;
 		return createSchema({
 			type: "ref",
-			name: extractRefName(schemaObject.$ref),
-			ref: schemaObject.$ref,
+			name: extractRefName(schema.$ref),
+			ref: schema.$ref,
 			nullable,
-			description: schemaObject.description,
-			deprecated: schemaObject.deprecated,
-			readOnly: schemaObject.readOnly,
-			writeOnly: schemaObject.writeOnly,
-			pattern: schemaObject.type === "string" ? schemaObject.pattern : void 0,
-			example: schemaObject.example,
+			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
 		});
 	}
@@ -1117,6 +1261,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			return !inOneOf && !inMapping;
 		}).map((s) => convertSchema({ schema: s }, options));
+		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));
@@ -1141,8 +1286,8 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		}
 		return createSchema({
 			type: "intersection",
-			members: allOfMembers,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1156,25 +1301,39 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	function convertUnion({ schema, name, nullable, defaultValue, options }) {
 		const unionMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
 		const unionBase = {
-			...buildSchemaBase(schema, name, nullable, defaultValue),
+			...renderSchemaBase(schema, name, nullable, defaultValue),
 			discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : void 0
 		};
 		if (schema.properties) {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
-			const propertiesNode = convertSchema({ schema: schemaWithoutUnion }, options);
+			const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
+			const sharedPropertiesNode = convertSchema({
+				schema: discriminator ? Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== "discriminator")) : schemaWithoutUnion,
+				name: isLegacyNaming ? void 0 : name
+			}, options);
 			return createSchema({
 				type: "union",
 				...unionBase,
-				members: unionMembers.map((s) => createSchema({
-					type: "intersection",
-					members: [convertSchema({ schema: s }, options), propertiesNode]
-				}))
+				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 = sharedPropertiesNode;
+					if (discriminatorValue && discriminator) propertiesNode = applyDiscriminatorEnum({
+						node: propertiesNode,
+						propertyName: discriminator.propertyName,
+						values: [discriminatorValue]
+					});
+					return createSchema({
+						type: "intersection",
+						members: [convertSchema({ schema: s }, options), propertiesNode]
+					});
+				})
 			});
 		}
 		return createSchema({
 			type: "union",
 			...unionBase,
-			members: unionMembers.map((s) => convertSchema({ schema: s }, options))
+			members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s }, options)))
 		});
 	}
 	/**
@@ -1197,7 +1356,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			type: "enum",
 			primitive: getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string"),
 			enumValues: [constValue],
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1206,7 +1365,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* (i.e. `format: 'date-time'` with `dateType: false`).
 	*/
 	function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }) {
-		const base = buildSchemaBase(schema, name, nullable, defaultValue);
+		const base = renderSchemaBase(schema, name, nullable, defaultValue);
 		if (schema.format === "int64") return createSchema({
 			type: mergedOptions.integerType === "bigint" ? "bigint" : "integer",
 			primitive: "integer",
@@ -1241,6 +1400,11 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			primitive: specialPrimitive,
 			type: specialType
 		});
+		if (specialType === "url") return createSchema({
+			...base,
+			primitive: "string",
+			type: "url"
+		});
 		return createSchema({
 			...base,
 			primitive: specialPrimitive,
@@ -1259,9 +1423,8 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	*/
 	function convertEnum({ schema, name, nullable, type, options }) {
 		if (type === "array") {
-			const rawSchema = schema;
 			const normalizedItems = {
-				...typeof rawSchema.items === "object" && !Array.isArray(rawSchema.items) ? rawSchema.items : {},
+				...typeof schema.items === "object" && !Array.isArray(schema.items) ? schema.items : {},
 				enum: schema.enum
 			};
 			const { enum: _enum, ...schemaWithoutEnum } = schema;
@@ -1340,23 +1503,62 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* - not required + not nullable → `optional: true`
 	* - not required + nullable → `nullish: true`
 	*/
+	/**
+	* Builds the propagation name for a child property during recursive schema conversion.
+	*
+	* - **Legacy naming** (`isLegacyNaming`): only the immediate property key is used
+	*   (e.g. `Params` for property `params`), keeping nested names short.
+	* - **Default naming**: the parent name is prepended so the full path is encoded
+	*   (e.g. `OrderParams` when parent is `Order`).
+	*/
+	function resolveChildName(parentName, propName) {
+		if (isLegacyNaming) return pascalCase(propName);
+		return parentName ? pascalCase([parentName, propName].join(" ")) : void 0;
+	}
+	/**
+	* Derives the final name for an enum property schema node.
+	*
+	* The raw name always includes the enum suffix (e.g. `StatusEnum`).
+	* In legacy mode an additional deduplication step appends a numeric suffix
+	* when the same name has already been used (e.g. `ParamsStatusEnum2`).
+	*/
+	function resolveEnumPropName(parentName, propName, enumSuffix) {
+		const raw = pascalCase([
+			parentName,
+			propName,
+			enumSuffix
+		].filter(Boolean).join(" "));
+		return isLegacyNaming ? getUniqueName(raw, usedEnumNames) : raw;
+	}
+	/**
+	* Given a freshly-converted property schema, returns the node with a correct
+	* `name` attached — or stripped — depending on whether the node is a named
+	* enum, a boolean const-enum (always inlined), or a regular schema.
+	*/
+	function applyEnumName(propNode, parentName, propName, enumSuffix) {
+		const enumNode = narrowSchema(propNode, "enum");
+		if (enumNode?.primitive === "boolean") return {
+			...propNode,
+			name: void 0
+		};
+		if (enumNode) return {
+			...propNode,
+			name: resolveEnumPropName(parentName, propName, enumSuffix)
+		};
+		return propNode;
+	}
 	function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }) {
-		const resolvedSchema = applyDiscriminatorEnum(schema);
-		const properties = resolvedSchema.properties ? Object.entries(resolvedSchema.properties).map(([propName, propSchema]) => {
-			const required = Array.isArray(resolvedSchema.required) ? resolvedSchema.required.includes(propName) : !!resolvedSchema.required;
+		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);
 			return createProperty({
 				name: propName,
 				schema: {
-					...convertSchema({
+					...applyEnumName(convertSchema({
 						schema: resolvedPropSchema,
-						name: name ? pascalCase([
-							name,
-							propName,
-							mergedOptions.enumSuffix
-						].filter(Boolean).join(" ")) : void 0
-					}, options),
+						name: resolveChildName(name, propName)
+					}, options), name, propName, mergedOptions.enumSuffix),
 					nullable: propNullable || void 0,
 					optional: !required && !propNullable ? true : void 0,
 					nullish: !required && propNullable ? true : void 0
@@ -1364,22 +1566,32 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 				required
 			});
 		}) : [];
-		const additionalProperties = resolvedSchema.additionalProperties;
+		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) });
-		const rawPatternProperties = "patternProperties" in resolvedSchema ? resolvedSchema.patternProperties : void 0;
-		const patternProperties = rawPatternProperties ? Object.fromEntries(Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [pattern, patternSchema === true || Object.keys(patternSchema).length === 0 ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) }) : convertSchema({ schema: patternSchema }, options)])) : void 0;
-		return createSchema({
+		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({
 			type: "object",
 			primitive: "object",
 			properties,
 			additionalProperties: additionalPropertiesNode,
 			patternProperties,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
+		if (isDiscriminator(schema) && schema.discriminator.mapping) {
+			const discPropName = schema.discriminator.propertyName;
+			return applyDiscriminatorEnum({
+				node: objectNode,
+				propertyName: discPropName,
+				values: Object.keys(schema.discriminator.mapping),
+				enumName: name ? resolveEnumPropName(name, discPropName, mergedOptions.enumSuffix) : void 0
+			});
+		}
+		return objectNode;
 	}
 	/**
 	* Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
@@ -1388,15 +1600,14 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* after the prefix items is mapped to the rest parameter of the tuple.
 	*/
 	function convertTuple({ schema, name, nullable, defaultValue, options }) {
-		const rawSchema = schema;
 		return createSchema({
 			type: "tuple",
 			primitive: "array",
-			items: rawSchema.prefixItems.map((item) => convertSchema({ schema: item }, options)),
-			rest: rawSchema.items ? convertSchema({ schema: rawSchema.items }, options) : void 0,
+			items: (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item }, options)),
+			rest: schema.items ? convertSchema({ schema: schema.items }, options) : void 0,
 			min: schema.minItems,
 			max: schema.maxItems,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1406,19 +1617,19 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* `enumSuffix` is forwarded so generators can emit a named enum declaration.
 	*/
 	function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }) {
-		const rawSchema = schema;
-		const itemName = rawSchema.items?.enum?.length && name ? pascalCase([name, mergedOptions.enumSuffix].join(" ")) : void 0;
+		const rawItems = schema.items;
+		const itemName = rawItems?.enum?.length && name ? resolveEnumPropName(void 0, name, mergedOptions.enumSuffix) : void 0;
 		return createSchema({
 			type: "array",
 			primitive: "array",
-			items: rawSchema.items ? [convertSchema({
-				schema: rawSchema.items,
+			items: rawItems ? [convertSchema({
+				schema: rawItems,
 				name: itemName
 			}, options)] : [],
 			min: schema.minItems,
 			max: schema.maxItems,
 			unique: schema.uniqueItems ?? void 0,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1431,7 +1642,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			min: schema.minLength,
 			max: schema.maxLength,
 			pattern: schema.pattern,
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1445,7 +1656,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			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)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1455,7 +1666,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		return createSchema({
 			type: "boolean",
 			primitive: "boolean",
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(schema, name, nullable, defaultValue)
 		});
 	}
 	/**
@@ -1490,7 +1701,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	*/
 	function convertSchema({ schema, name }, options) {
 		const mergedOptions = {
-			...DEFAULT_OPTIONS,
+			...DEFAULT_PARSER_OPTIONS,
 			...options
 		};
 		const flattenedSchema = flattenSchema(schema);
@@ -1521,18 +1732,21 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		if (schema.type === "string" && schema.contentMediaType === "application/octet-stream") return createSchema({
 			type: "blob",
 			primitive: "string",
-			...buildSchemaBase(schema, name, nullable, defaultValue)
+			...renderSchemaBase(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({
 				type: "union",
-				members: nonNullTypes.map((t) => convertSchema({ schema: {
-					...schema,
-					type: t
-				} }, options)),
-				...buildSchemaBase(schema, name, arrayNullable, defaultValue)
+				members: nonNullTypes.map((t) => convertSchema({
+					schema: {
+						...schema,
+						type: t
+					},
+					name
+				}, options)),
+				...renderSchemaBase(schema, name, arrayNullable, defaultValue)
 			});
 		}
 		if (!type) {
@@ -1560,12 +1774,17 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
 	*/
 	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({
 			name: param["name"],
 			in: param["in"],
-			schema,
-			required: param["required"] ?? false
+			schema: {
+				...schema,
+				description: param["description"] ?? schema.description,
+				optional: !required || !!schema.optional ? true : void 0
+			},
+			required
 		});
 	}
 	/**
@@ -1573,15 +1792,13 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	* request body, and all response codes into their AST node equivalents.
 	*/
 	function parseOperation(options, oas, operation) {
-		const parameters = operation.getParameters().map((param) => {
-			return parseParameter(options, oas.dereferenceWithRef(param));
-		});
+		const parameters = oas.getParameters(operation).map((param) => parseParameter(options, param));
 		const requestBodySchema = oas.getRequestSchema(operation);
 		const requestBody = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : 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 schema = responseSchema && Object.keys(responseSchema).length > 0 ? convertSchema({ schema: responseSchema }, options) : createSchema({ type: resolveTypeOption(options.emptySchemaType) });
 			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({
@@ -1594,7 +1811,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 		return createOperation({
 			operationId: operation.getOperationId(),
 			method: operation.method.toUpperCase(),
-			path: operation.path,
+			path: new URLPath(operation.path).URL,
 			tags: operation.getTags().map((tag) => tag.name),
 			summary: operation.getSummary() || void 0,
 			description: operation.getDescription() || void 0,
@@ -1610,7 +1827,7 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 	*/
 	function parse(options) {
 		const mergedOptions = {
-			...DEFAULT_OPTIONS,
+			...DEFAULT_PARSER_OPTIONS,
 			...options
 		};
 		const schemas = Object.entries(schemaObjects).map(([name, schemaObject]) => convertSchema({
@@ -1651,31 +1868,11 @@ function createOasParser(oas, { contentType, collisionDetection } = {}) {
 			}
 		} });
 	}
-	/**
-	* Collects all `KubbFile.Import` descriptors needed by a `SchemaNode` tree.
-	*
-	* Walks the tree looking for `ref` nodes, verifies each `$ref` is resolvable in the spec,
-	* applies collision-resolved names from `nameMapping`, and calls `resolve` to obtain the
-	* import path and name. Returns an empty array for refs that cannot be resolved.
-	*/
-	function getImports(node, resolve) {
-		return collect(node, { schema(schemaNode) {
-			if (schemaNode.type !== "ref" || !schemaNode.ref) return;
-			if (!oas.get(schemaNode.ref)) return;
-			const rawName = extractRefName(schemaNode.ref);
-			const result = resolve(nameMapping.get(rawName) ?? rawName);
-			if (!result) return;
-			return {
-				name: [result.name],
-				path: result.path
-			};
-		} });
-	}
 	return {
 		parse,
 		convertSchema,
 		resolveRefs,
-		getImports
+		nameMapping
 	};
 }
 //#endregion
@@ -1699,8 +1896,9 @@ const adapterOasName = "oas";
 * })
 * ```
 */
-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 adapterOas = createAdapter((options) => {
+	const { validate = true, oasClass, contentType, serverIndex, serverVariables, discriminator = "strict", collisionDetection = 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 nameMapping = /* @__PURE__ */ new Map();
 	return {
 		name: "oas",
 		options: {
@@ -1714,7 +1912,16 @@ const adapterOas = defineAdapter((options) => {
 			dateType,
 			integerType,
 			unknownType,
-			emptySchemaType
+			emptySchemaType,
+			enumSuffix,
+			nameMapping
+		},
+		getImports(node, resolve) {
+			return getImports({
+				node,
+				nameMapping,
+				resolve
+			});
 		},
 		async parse(source) {
 			const oas = await parseFromConfig(sourceToFakeConfig(source), oasClass);
@@ -1728,18 +1935,23 @@ const adapterOas = defineAdapter((options) => {
 			} catch (_err) {}
 			const server = serverIndex !== void 0 ? oas.api.servers?.at(serverIndex) : void 0;
 			const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : void 0;
+			const parser = createOasParser(oas, {
+				contentType,
+				collisionDetection
+			});
+			nameMapping.clear();
+			for (const [key, value] of parser.nameMapping) nameMapping.set(key, value);
 			return createRoot({
-				...createOasParser(oas, {
-					contentType,
-					collisionDetection
-				}).parse({
+				...parser.parse({
 					dateType,
 					integerType,
 					unknownType,
-					emptySchemaType
+					emptySchemaType,
+					enumSuffix
 				}),
 				meta: {
 					title: oas.api.info?.title,
+					description: oas.api.info?.description,
 					version: oas.api.info?.version,
 					baseURL
 				}