@kubb/adapter-oas 5.14.0 → 5.14.2

package/dist/index.cjs

@@ -36,7 +36,7 @@ var compatibility = {
 };
 //#endregion
 //#region package.json
-var version = "5.14.0";
+var version = "5.14.2";
 //#endregion
 //#region src/constants.ts
 /**
@@ -387,6 +387,198 @@ async function read(path) {
 	return (0, node_fs_promises.readFile)(path, { encoding: "utf8" });
 }
 //#endregion
+//#region src/oas.ts
+/**
+* Returns `true` when a schema should be treated as nullable.
+*
+* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
+* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
+*/
+function isNullable(schema) {
+	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
+	const schemaType = schema?.type;
+	if (schemaType === "null") return true;
+	if (Array.isArray(schemaType)) return schemaType.includes("null");
+	return false;
+}
+/**
+* Returns the `x-*` keys of `source` as-is, or `undefined` when there are none.
+*/
+function pickExtensions(source) {
+	const entries = Object.entries(source).filter(([key]) => key.startsWith("x-"));
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+/**
+* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
+*/
+function isReference(obj) {
+	return !!obj && typeof obj === "object" && "$ref" in obj;
+}
+/**
+* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object,
+* excluding the Swagger 2 string form.
+*/
+function isDiscriminator(obj) {
+	const record = obj;
+	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
+}
+/**
+* Returns `true` when a schema is a raw binary payload.
+*/
+function isBinary(schema) {
+	return schema.contentMediaType === "application/octet-stream" && schema.contentEncoding === void 0 && (schema.type === void 0 || schema.type === "string");
+}
+/**
+* Returns the binary schema for a non-JSON entry the OAS 3.1 upgrade emptied out, or `undefined`
+* when the entry carries a schema of its own. The upgrade rewrites `format: 'binary'` into
+* `contentMediaType` and drops it whenever it only repeats the media type key, for any binary
+* media type (`application/octet-stream`, `application/pdf`, `image/png`, ...), not just
+* `application/octet-stream`. Without the fallback such a body resolves to the empty schema type
+* instead of a blob.
+*/
+function getBinaryFallbackSchema(mediaType, schema) {
+	if (!mediaType || isJsonMimeType(mediaType)) return void 0;
+	if (schema && Object.keys(schema).length > 0) return void 0;
+	return {
+		type: "string",
+		contentMediaType: "application/octet-stream"
+	};
+}
+/**
+* MIME type fragments that mark a media type as JSON-like.
+*
+* A content type is JSON when it contains any of these substrings. The `+json` entry catches
+* structured-syntax suffixes such as `application/vnd.api+json`.
+*/
+const jsonMimeFragments = [
+	"application/json",
+	"application/x-json",
+	"text/json",
+	"text/x-json",
+	"+json"
+];
+/**
+* Returns `true` when a media type string is JSON-like.
+*
+* @example
+* ```ts
+* isJsonMimeType('application/json')         // true
+* isJsonMimeType('application/vnd.api+json') // true
+* isJsonMimeType('multipart/form-data')      // false
+* ```
+*/
+function isJsonMimeType(mimeType) {
+	return jsonMimeFragments.some((fragment) => mimeType.includes(fragment));
+}
+//#endregion
+//#region src/refs.ts
+/**
+* Creates the `$ref` resolution service for one document. One pointer walk backs every method.
+*
+* @example
+* ```ts
+* const refs = createRefs(document)
+* refs.resolve<SchemaObject>('#/components/schemas/Pet')
+* refs.resolve<SchemaObject>('#/components/schemas/Pet', { report: false })
+* refs.resolveNode('#/components/schemas/Pet', parseSchema)
+* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
+* refs.derefKeepingRef(parameter)
+* ```
+*/
+function createRefs(document) {
+	const pointerCache = /* @__PURE__ */ new Map();
+	const resolvedNodeCache = /* @__PURE__ */ new Map();
+	const resolvingRefs = /* @__PURE__ */ new Set();
+	function walkPointer($ref) {
+		const trimmed = $ref.trim();
+		if (trimmed === "" || !trimmed.startsWith("#")) return {
+			applicable: false,
+			value: null
+		};
+		const pointer = trimmed.substring(1);
+		if (pointerCache.has(pointer)) return {
+			applicable: true,
+			value: pointerCache.get(pointer)
+		};
+		const current = pointer.split("/").filter(Boolean).map((token) => globalThis.decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")).reduce((obj, key) => obj?.[key], document);
+		if (current) pointerCache.set(pointer, current);
+		return {
+			applicable: true,
+			value: current ?? null
+		};
+	}
+	/**
+	* Resolves a local `#/...` JSON pointer. Returns `null` for an empty or non-local ref.
+	* `report: true` (default) reports a `refNotFound` diagnostic into the active build (or throws
+	* outside one) when the pointer cannot be resolved. `report: false` resolves to `null` silently,
+	* for a speculative lookup where a missing ref is not an error.
+	*/
+	function resolve(refPath, options) {
+		const { applicable, value } = walkPointer(refPath);
+		if (!applicable || value || options?.report === false) return value;
+		const diagnostic = {
+			code: _kubb_kit.Diagnostics.code.refNotFound,
+			severity: "error",
+			message: `Could not find a definition for ${refPath}.`,
+			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
+			location: {
+				kind: "schema",
+				pointer: refPath,
+				ref: refPath
+			}
+		};
+		if (!_kubb_kit.Diagnostics.report(diagnostic)) throw new _kubb_kit.Diagnostics.Error(diagnostic);
+		return null;
+	}
+	/**
+	* Resolves a `$ref` to its parsed node via `parse`, guarding against cycles and memoizing per
+	* instance. Returns `null` when the ref is currently being resolved (a cycle) or cannot be
+	* resolved (e.g. a minimal document in a unit test).
+	*/
+	function resolveNode(refPath, parse) {
+		if (resolvingRefs.has(refPath)) return null;
+		if (!resolvedNodeCache.has(refPath)) {
+			let resolved = null;
+			try {
+				const referenced = resolve(refPath);
+				if (referenced) {
+					resolvingRefs.add(refPath);
+					resolved = parse({ schema: referenced });
+					resolvingRefs.delete(refPath);
+				}
+			} catch {}
+			resolvedNodeCache.set(refPath, resolved);
+		}
+		return resolvedNodeCache.get(refPath) ?? null;
+	}
+	/**
+	* Resolves a `$ref` value without mutating anything: when `value` holds a `$ref`, returns the
+	* resolved target. Returns `null` when the value is empty, cannot be resolved, or is still a
+	* `$ref` after resolving (e.g. a document with no component registry). A non-`$ref` value is
+	* returned as-is.
+	*/
+	function deref(value) {
+		if (!isReference(value)) return value ? value : null;
+		const resolved = resolve(value.$ref);
+		return resolved && !isReference(resolved) ? resolved : null;
+	}
+	/** Resolves a `$ref` object but keeps the `$ref` field on the result; other values pass through. */
+	function derefKeepingRef(value) {
+		if (isReference(value)) return {
+			...value,
+			...resolve(value.$ref),
+			$ref: value.$ref
+		};
+		return value;
+	}
+	return {
+		resolve,
+		resolveNode,
+		deref,
+		derefKeepingRef
+	};
+}
+//#endregion
 //#region src/load/source.ts
 const urlRegExp = /^https?:\/+/i;
 /**
@@ -507,6 +699,22 @@ function hasExternalRef(node) {
 	return Object.values(node).some(hasExternalRef);
 }
 /**
+* Replaces each `$ref` into `#/paths/...` with a copy of its target, in place.
+*
+* The Swagger 2.0 upgrade moves `responses/200/schema` under `content`, so a ref to the old location
+* would no longer resolve. A ref that points back into itself is kept, since inlining it never ends.
+*/
+function inlinePathRefs(node, resolve, visiting = []) {
+	if (!node || typeof node !== "object") return node;
+	const ref = node.$ref;
+	if (typeof ref === "string" && ref.startsWith("#/paths/") && !visiting.includes(ref)) {
+		const target = resolve(ref);
+		return target && typeof target === "object" ? inlinePathRefs(structuredClone(target), resolve, [...visiting, ref]) : node;
+	}
+	for (const [key, value] of Object.entries(node)) node[key] = inlinePathRefs(value, resolve, visiting);
+	return node;
+}
+/**
 * Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
 *
 * External file schemas are hoisted into named `components.schemas` entries, so a property
@@ -564,6 +772,17 @@ async function parseFromConfig(source) {
 		await assertInputExists(source.path);
 		return bundleDocument(source.path);
 	})();
+	if (raw && typeof raw === "object") {
+		const document = raw;
+		for (const key of ["swagger", "openapi"]) {
+			const version = document[key];
+			if (typeof version === "number") document[key] = Number.isInteger(version) ? version.toFixed(1) : String(version);
+		}
+	}
+	if (raw && typeof raw === "object" && "swagger" in raw) {
+		const refs = createRefs(raw);
+		inlinePathRefs(raw, (ref) => refs.resolve(ref, { report: false }));
+	}
 	try {
 		return (0, _scalar_openapi_upgrader.upgrade)(raw, "3.1");
 	} catch (error) {
@@ -660,90 +879,6 @@ async function validateDocumentInWorker(document) {
 	if (!message.valid) reportValidationErrors(message);
 }
 //#endregion
-//#region src/oas.ts
-/**
-* Returns `true` when a schema should be treated as nullable.
-*
-* Recognizes all nullable signals across OAS versions: `nullable: true` (OAS 3.0),
-* `x-nullable: true` (vendor extension), `type: 'null'`, and `type: ['null', ...]` (OAS 3.1).
-*/
-function isNullable(schema) {
-	if ((schema?.nullable ?? schema?.["x-nullable"]) === true) return true;
-	const schemaType = schema?.type;
-	if (schemaType === "null") return true;
-	if (Array.isArray(schemaType)) return schemaType.includes("null");
-	return false;
-}
-/**
-* Returns the `x-*` keys of `source` as-is, or `undefined` when there are none.
-*/
-function pickExtensions(source) {
-	const entries = Object.entries(source).filter(([key]) => key.startsWith("x-"));
-	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
-}
-/**
-* Returns `true` when `obj` is an OpenAPI `$ref` pointer object.
-*/
-function isReference(obj) {
-	return !!obj && typeof obj === "object" && "$ref" in obj;
-}
-/**
-* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object,
-* excluding the Swagger 2 string form.
-*/
-function isDiscriminator(obj) {
-	const record = obj;
-	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
-}
-/**
-* Returns `true` when a schema is a raw binary payload.
-*/
-function isBinary(schema) {
-	return schema.contentMediaType === "application/octet-stream" && schema.contentEncoding === void 0 && (schema.type === void 0 || schema.type === "string");
-}
-/**
-* Returns the binary schema for a non-JSON entry the OAS 3.1 upgrade emptied out, or `undefined`
-* when the entry carries a schema of its own. The upgrade rewrites `format: 'binary'` into
-* `contentMediaType` and drops it whenever it only repeats the media type key, for any binary
-* media type (`application/octet-stream`, `application/pdf`, `image/png`, ...), not just
-* `application/octet-stream`. Without the fallback such a body resolves to the empty schema type
-* instead of a blob.
-*/
-function getBinaryFallbackSchema(mediaType, schema) {
-	if (!mediaType || isJsonMimeType(mediaType)) return void 0;
-	if (schema && Object.keys(schema).length > 0) return void 0;
-	return {
-		type: "string",
-		contentMediaType: "application/octet-stream"
-	};
-}
-/**
-* MIME type fragments that mark a media type as JSON-like.
-*
-* A content type is JSON when it contains any of these substrings. The `+json` entry catches
-* structured-syntax suffixes such as `application/vnd.api+json`.
-*/
-const jsonMimeFragments = [
-	"application/json",
-	"application/x-json",
-	"text/json",
-	"text/x-json",
-	"+json"
-];
-/**
-* Returns `true` when a media type string is JSON-like.
-*
-* @example
-* ```ts
-* isJsonMimeType('application/json')         // true
-* isJsonMimeType('application/vnd.api+json') // true
-* isJsonMimeType('multipart/form-data')      // false
-* ```
-*/
-function isJsonMimeType(mimeType) {
-	return jsonMimeFragments.some((fragment) => mimeType.includes(fragment));
-}
-//#endregion
 //#region src/model/components.ts
 /**
 * Extracts the inline schema from a media-type `content` map, with the media type it sits under.
@@ -1172,6 +1307,28 @@ function getParameters({ operation, refs }) {
 	for (const entry of [...pathLevelParams, ...operationParams]) if (entry.param.name && entry.param.in) paramMap.set(`${entry.param.in}:${entry.param.name}`, entry);
 	return Array.from(paramMap.values());
 }
+const PARAMETER_STYLES = /* @__PURE__ */ new Set([
+	"matrix",
+	"label",
+	"form",
+	"simple",
+	"spaceDelimited",
+	"pipeDelimited",
+	"deepObject"
+]);
+/** The `encoding` of a media type, reduced to the entries that set a field Kubb carries. A `style` outside the OpenAPI set is dropped. */
+function getEncoding(encoding) {
+	const entries = Object.entries(encoding ?? {}).flatMap(([property, { contentType, style, explode, allowReserved }]) => {
+		const node = {
+			...contentType !== void 0 ? { contentType } : {},
+			...style !== void 0 && PARAMETER_STYLES.has(style) ? { style } : {},
+			...explode !== void 0 ? { explode } : {},
+			...allowReserved !== void 0 ? { allowReserved } : {}
+		};
+		return Object.keys(node).length ? [[property, node]] : [];
+	});
+	return entries.length ? Object.fromEntries(entries) : void 0;
+}
 /** Schema for one media type of a `content` map, with the binary fallback for an emptied non-JSON entry. */
 function getBodySchema({ content, contentType, refs }) {
 	const entry = contentType ? content?.[contentType] : void 0;
@@ -1226,7 +1383,7 @@ function parseParameter({ param, pointer, parentName, options, parseSchema }) {
 		name: schemaName
 	}) : _kubb_kit.ast.factory.createSchema({ type: options.unknownType });
 	if (rawSchema) scanSchema(schema, contentType ? `${pointer}/content/${escapePointerToken(contentType)}/schema` : `${pointer}/schema`);
-	const style = param.style;
+	const style = param.style !== void 0 && PARAMETER_STYLES.has(param.style) ? param.style : void 0;
 	const explode = param.explode;
 	const allowReserved = param.allowReserved;
 	return _kubb_kit.ast.factory.createParameter({
@@ -1279,10 +1436,12 @@ function parseOperation({ operation, ...ctx }) {
 			name: requestBodyName
 		});
 		scanSchema(node, `${pointer}/requestBody/content/${escapePointerToken(ct)}/schema`);
+		const encoding = getEncoding(body?.content?.[ct]?.encoding);
 		return [_kubb_kit.ast.factory.createContent({
 			contentType: ct,
 			schema: _kubb_kit.ast.optionality(node, bodyRequired),
-			keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
+			keysToOmit: collectPropertyKeysByFlag(schema, "readOnly"),
+			...encoding && { encoding }
 		})];
 	});
 	const requestBody = content.length > 0 || body?.description ? {
@@ -1379,6 +1538,42 @@ function createNode({ schema, name, nullable, defaultValue }, extras) {
 //#endregion
 //#region src/emit/discriminator/preserve.ts
 /**
+* Turns string mapping keys into the discriminator property's type when they parse cleanly.
+*/
+function typedKeys({ keys, propertyType }) {
+	return keys.map((key) => {
+		if (propertyType === "integer" || propertyType === "number") {
+			const value = Number(key);
+			return key.trim() !== "" && Number.isFinite(value) ? value : key;
+		}
+		if (propertyType === "boolean") {
+			const lower = key.toLowerCase();
+			return lower === "true" ? true : lower === "false" ? false : key;
+		}
+		return key;
+	});
+}
+/**
+* Reads the declared `type` of `propertyName` on a schema, following `$ref`s and `allOf` members.
+* A nullable array such as `['integer', 'null']` reads as its one non-null type.
+*/
+function propertyTypeOf({ schema, propertyName, refs, seen = /* @__PURE__ */ new Set() }) {
+	const deref = (value) => value && isReference(value) ? refs.resolve(value.$ref, { report: false }) : value;
+	if (schema && isReference(schema)) {
+		if (seen.has(schema.$ref)) return void 0;
+		seen.add(schema.$ref);
+	}
+	const resolved = deref(schema);
+	const type = deref(resolved?.properties?.[propertyName])?.type ?? resolved?.allOf?.map((member) => propertyTypeOf({
+		schema: member,
+		propertyName,
+		refs,
+		seen
+	})).find(Boolean);
+	const nonNull = Array.isArray(type) ? type.filter((t) => t !== "null") : [];
+	return nonNull.length === 1 ? nonNull[0] : type;
+}
+/**
 * Creates a single-property object schema used as a discriminator literal.
 *
 * @example
@@ -1395,7 +1590,7 @@ function createDiscriminantNode({ propertyName, values }) {
 			name: propertyName,
 			schema: _kubb_kit.ast.factory.createSchema({
 				type: "enum",
-				primitive: "string",
+				primitive: (0, _kubb_kit.enumPrimitive)(values),
 				enumValues: values
 			}),
 			required: true
@@ -1410,21 +1605,61 @@ function createDiscriminantNode({ propertyName, values }) {
 *
 * @example
 * ```ts
-* findDiscriminators({ dog: '#/components/schemas/Dog', hound: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // ['dog', 'hound']
+* findDiscriminators({ mapping: { dog: '#/components/schemas/Dog', hound: '#/components/schemas/Dog' }, ref: '#/components/schemas/Dog' }) // ['dog', 'hound']
 * ```
 */
-function findDiscriminators(mapping, ref) {
+function findDiscriminators({ mapping, ref }) {
 	if (!mapping || !ref) return [];
 	return Object.entries(mapping).filter(([, value]) => value === ref).map(([key]) => key);
 }
 /**
+* Finds the discriminator a schema declares itself or through an inline `allOf` member.
+*/
+function getDiscriminator(schema) {
+	return (isDiscriminator(schema) ? schema : schema.allOf?.find(isDiscriminator))?.discriminator;
+}
+/**
+* Lists the mapping keys of a discriminator plus the keys of the nested discriminators its mapped
+* schemas declare on the same property, so a root `$type` accepts values from every level.
+*/
+function getMappingKeys({ discriminator: { propertyName, mapping }, refs, seen = /* @__PURE__ */ new Set() }) {
+	return Object.entries(mapping ?? {}).flatMap(([key, target]) => {
+		if (seen.has(target)) return [key];
+		seen.add(target);
+		const resolved = refs.resolve(target, { report: false });
+		const nested = resolved && getDiscriminator(resolved);
+		return nested?.propertyName === propertyName ? [key, ...getMappingKeys({
+			discriminator: nested,
+			refs,
+			seen
+		})] : [key];
+	});
+}
+/**
+* Drops the discriminator from an inline `allOf` member when a `$ref` sibling already declares one on
+* the same property. That mapping names the schema's own children, and keeping it pins the property
+* to those keys next to the parent's, which leaves `never`.
+*/
+function removeInheritedDiscriminator({ members, refs }) {
+	const inherited = new Set(members.flatMap((member) => {
+		const parent = isReference(member) ? refs.resolve(member.$ref, { report: false }) : null;
+		return parent && getDiscriminator(parent)?.propertyName || [];
+	}));
+	return members.map((member) => {
+		if (isReference(member) || !isDiscriminator(member) || member.oneOf || member.anyOf) return member;
+		if (!inherited.has(member.discriminator.propertyName)) return member;
+		const { discriminator: _discriminator, ...rest } = member;
+		return rest;
+	});
+}
+/**
 * Narrows each `oneOf`/`anyOf` member with its discriminant value, intersecting the member's own
 * node with either the shared-properties slice carrying that value, or a synthetic discriminant
 * literal. The referenced child schema's own definition is left untouched — narrowing happens only
 * at this union usage site, which is what makes this mode "preserve" (as opposed to `propagate`,
 * which additionally patches the child schema's own definition in a post-pass).
 */
-function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parse, name, refs }) {
+function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode, parentType, parse, name, refs }) {
 	function pickDiscriminatorPropertyNode(node, propertyName) {
 		const discriminatorProperty = _kubb_kit.ast.narrowSchema(node, "object")?.properties?.find((property) => property.name === propertyName);
 		if (!discriminatorProperty) return null;
@@ -1460,9 +1695,20 @@ function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode,
 	}
 	return unionMembers.map((s) => {
 		const ref = isReference(s) ? s.$ref : void 0;
-		const mappedValues = findDiscriminators(discriminator?.mapping, ref);
+		const mappedValues = findDiscriminators({
+			mapping: discriminator?.mapping,
+			ref
+		});
 		const implicitValue = mappedValues.length ? null : implicitDiscriminantValue(s);
-		const discriminatorValues = mappedValues.length ? mappedValues : implicitValue ? [implicitValue] : [];
+		const propertyType = propertyTypeOf({
+			schema: s,
+			propertyName: discriminator?.propertyName ?? "",
+			refs
+		}) ?? parentType;
+		const discriminatorValues = typedKeys({
+			keys: mappedValues.length ? mappedValues : implicitValue ? [implicitValue] : [],
+			propertyType
+		});
 		const memberNode = parse({
 			schema: s,
 			name
@@ -1494,21 +1740,34 @@ function extractDiscriminatedAllOfMembers({ allOfMembers, name, refs }) {
 		members: allOfMembers.filter((item) => {
 			if (!isReference(item) || !name) return true;
 			const deref = refs.resolve(item.$ref);
-			if (!deref || !isDiscriminator(deref)) return true;
-			const parentUnion = deref.oneOf ?? deref.anyOf;
-			if (!parentUnion) return true;
+			const discriminator = deref && getDiscriminator(deref);
+			const parentUnion = deref?.oneOf ?? deref?.anyOf;
+			if (!deref || !discriminator || isDiscriminator(deref) && !parentUnion) return true;
 			const childRef = `${SCHEMA_REF_PREFIX}${name}`;
-			const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef);
-			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
-			if (inOneOf || inMapping) {
-				const values = findDiscriminators(deref.discriminator.mapping, childRef);
-				if (values.length) discriminantValues.push({
-					propertyName: deref.discriminator.propertyName,
-					values
+			const values = findDiscriminators({
+				mapping: discriminator.mapping,
+				ref: childRef
+			});
+			if (values.length) {
+				const { propertyName } = discriminator;
+				const propertyType = propertyTypeOf({
+					schema: deref,
+					propertyName,
+					refs
+				}) ?? propertyTypeOf({
+					schema: { $ref: childRef },
+					propertyName,
+					refs
+				});
+				discriminantValues.push({
+					propertyName,
+					values: typedKeys({
+						keys: values,
+						propertyType
+					})
 				});
-				return false;
 			}
-			return true;
+			return !(parentUnion && (values.length > 0 || parentUnion.some((member) => isReference(member) && member.$ref === childRef)));
 		}),
 		discriminantValues
 	};
@@ -1635,10 +1894,9 @@ function resolveUnionMembers(members, siblingProperties) {
 	});
 }
 /**
-* Enriches any `oneOf` or `anyOf` branches on a schema object with properties from sibling schemas.
+* Enriches a schema object, and any `oneOf` or `anyOf` branches on it, with properties from sibling schemas.
 */
 function resolveUnionSchema(schema, siblingProperties) {
-	if (!schema.oneOf && !schema.anyOf) return schema;
 	const next = { ...resolveUnionMembers([schema], siblingProperties)[0] ?? schema };
 	if (schema.oneOf) next.oneOf = resolveUnionMembers(schema.oneOf, siblingProperties);
 	if (schema.anyOf) next.anyOf = resolveUnionMembers(schema.anyOf, siblingProperties);
@@ -1662,6 +1920,17 @@ function convertRef({ schema, name, nullable, defaultValue, document, parse, ref
 		defaultValue
 	};
 	if (refPath && document.components && !refs.resolve(refPath, { report: false })) return createNode(ctx, { type: "unknown" });
+	if (refPath && !refPath.startsWith("#/components/schemas/") && resolvedSchema) return _kubb_kit.ast.factory.createSchema({
+		...resolvedSchema,
+		title: schema.title ?? resolvedSchema.title,
+		description: schema.description ?? resolvedSchema.description,
+		deprecated: schema.deprecated ?? resolvedSchema.deprecated,
+		readOnly: schema.readOnly ?? resolvedSchema.readOnly,
+		writeOnly: schema.writeOnly ?? resolvedSchema.writeOnly,
+		default: defaultValue ?? resolvedSchema.default,
+		name: name ?? resolvedSchema.name,
+		nullable: nullable ?? resolvedSchema.nullable
+	});
 	const targetName = renames?.get(schema.$ref);
 	return createNode(ctx, {
 		type: "ref",
@@ -1693,9 +1962,41 @@ function convertNot({ schema, name, nullable, defaultValue, parse }) {
 	});
 }
 /**
+* Keywords that describe a schema or conditionally constrain it, but add no structure.
+*/
+const annotationKeys = /* @__PURE__ */ new Set([
+	"description",
+	"title",
+	"example",
+	"examples",
+	"default",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"if",
+	"then",
+	"else"
+]);
+/**
+* Moves `allOf` members that hold only annotations or `if`/`then`/`else` onto the parent, so they do
+* not become `unknown`. The parent's own values win, and the conditional keywords are not enforced.
+*/
+function mergeAnnotations(schema) {
+	const members = schema.allOf;
+	const isAnnotation = (member) => !isReference(member) && Object.keys(member).every((key) => annotationKeys.has(key));
+	const annotations = members.filter(isAnnotation);
+	const rest = members.filter((member) => !isAnnotation(member));
+	return annotations.length && rest.length ? {
+		...Object.assign({}, ...annotations),
+		...schema,
+		allOf: rest
+	} : schema;
+}
+/**
 * Converts an `allOf` schema into a flattened node or an `IntersectionSchemaNode`.
 */
-function convertAllOf({ schema, name, nullable, defaultValue, parse, refs }) {
+function convertAllOf({ schema: original, name, nullable, defaultValue, parse, refs }) {
+	const schema = mergeAnnotations(original);
 	if (schema.allOf.length === 1 && !schema.properties && !(Array.isArray(schema.required) && schema.required.length) && schema.additionalProperties === void 0) {
 		const [memberSchema] = schema.allOf;
 		const memberNode = parse({
@@ -1721,7 +2022,10 @@ function convertAllOf({ schema, name, nullable, defaultValue, parse, refs }) {
 		});
 	}
 	const { members: discriminatedAllOf, discriminantValues } = extractDiscriminatedAllOfMembers({
-		allOfMembers: schema.allOf,
+		allOfMembers: removeInheritedDiscriminator({
+			members: schema.allOf,
+			refs
+		}),
 		name,
 		refs
 	});
@@ -1801,6 +2105,11 @@ function convertUnion(context) {
 			unionMembers,
 			discriminator,
 			sharedPropertiesNode,
+			parentType: discriminator && propertyTypeOf({
+				schema,
+				propertyName: discriminator.propertyName,
+				refs
+			}),
 			parse,
 			name,
 			refs
@@ -2064,7 +2373,7 @@ function nameEnums(node, options) {
 /**
 * Converts an object-like schema into an `ObjectSchemaNode`.
 */
-function convertObject({ schema, name, nullable, defaultValue, options, parse }) {
+function convertObject({ schema, name, nullable, defaultValue, options, parse, refs }) {
 	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;
@@ -2081,7 +2390,7 @@ function convertObject({ schema, name, nullable, defaultValue, options, parse })
 			name: propName,
 			schema: {
 				...schemaNode,
-				nullable: schemaNode.type === "null" ? void 0 : propNullable || void 0
+				nullable: schemaNode.type === "null" ? void 0 : propNullable || schemaNode.nullable || void 0
 			},
 			required
 		});
@@ -2121,7 +2430,17 @@ function convertObject({ schema, name, nullable, defaultValue, options, parse })
 	});
 	if (isDiscriminator(schema) && schema.discriminator.mapping) {
 		const discPropName = schema.discriminator.propertyName;
-		const values = Object.keys(schema.discriminator.mapping);
+		const values = typedKeys({
+			keys: getMappingKeys({
+				discriminator: schema.discriminator,
+				refs
+			}),
+			propertyType: propertyTypeOf({
+				schema,
+				propertyName: discPropName,
+				refs
+			})
+		});
 		const enumName = name ? (0, _kubb_kit.enumPropName)(name, discPropName, options.enumSuffix) : void 0;
 		return _kubb_kit.ast.applyMacros(objectNode, [(0, _kubb_kit.macroDiscriminatorEnum)({
 			propertyName: discPropName,
@@ -2179,8 +2498,9 @@ function convertArray({ schema, name, nullable, defaultValue, options, parse })
 //#region src/emit/parseSchema.ts
 /**
 * Ordered schema rule table. Order is significant: composition keywords (`not`, `$ref`, `allOf`,
-* `oneOf`/`anyOf`) take precedence over `const`, which takes precedence over a genuine OAS 3.1
-* multi-type array (more than one non-`null` type), which takes precedence over `format`/`type`.
+* `oneOf`/`anyOf`) take precedence over `const` (except a `$ref` with a sibling `const`, where the
+* `const` wins), which takes precedence over a genuine OAS 3.1 multi-type array (more than one
+* non-`null` type), which takes precedence over `format`/`type`.
 * A multi-type array must split into its per-type members before `format` runs, otherwise
 * `format` collapses the whole schema to one type (e.g. `type: ['null', 'integer', 'string'],
 * format: 'int32'` would drop `string` and emit just `integer`); each split-off member still
@@ -2194,7 +2514,7 @@ const schemaRules = [
 		convert: convertNot
 	},
 	{
-		match: ({ schema }) => isReference(schema),
+		match: ({ schema }) => isReference(schema) && !("const" in schema && schema.const !== void 0),
 		convert: convertRef
 	},
 	{
@@ -2362,114 +2682,6 @@ function refPromotedEnums(node, promoted) {
 	} });
 }
 //#endregion
-//#region src/refs.ts
-/**
-* Creates the `$ref` resolution service for one document. One pointer walk backs every method.
-*
-* @example
-* ```ts
-* const refs = createRefs(document)
-* refs.resolve<SchemaObject>('#/components/schemas/Pet')
-* refs.resolve<SchemaObject>('#/components/schemas/Pet', { report: false })
-* refs.resolveNode('#/components/schemas/Pet', parseSchema)
-* refs.deref<ResponseObject>(operation.schema.responses?.['200'])
-* refs.derefKeepingRef(parameter)
-* ```
-*/
-function createRefs(document) {
-	const pointerCache = /* @__PURE__ */ new Map();
-	const resolvedNodeCache = /* @__PURE__ */ new Map();
-	const resolvingRefs = /* @__PURE__ */ new Set();
-	function walkPointer($ref) {
-		const trimmed = $ref.trim();
-		if (trimmed === "" || !trimmed.startsWith("#")) return {
-			applicable: false,
-			value: null
-		};
-		const pointer = trimmed.substring(1);
-		if (pointerCache.has(pointer)) return {
-			applicable: true,
-			value: pointerCache.get(pointer)
-		};
-		const current = pointer.split("/").filter(Boolean).map((token) => globalThis.decodeURIComponent(token).replaceAll("~1", "/").replaceAll("~0", "~")).reduce((obj, key) => obj?.[key], document);
-		if (current) pointerCache.set(pointer, current);
-		return {
-			applicable: true,
-			value: current ?? null
-		};
-	}
-	/**
-	* Resolves a local `#/...` JSON pointer. Returns `null` for an empty or non-local ref.
-	* `report: true` (default) reports a `refNotFound` diagnostic into the active build (or throws
-	* outside one) when the pointer cannot be resolved. `report: false` resolves to `null` silently,
-	* for a speculative lookup where a missing ref is not an error.
-	*/
-	function resolve(refPath, options) {
-		const { applicable, value } = walkPointer(refPath);
-		if (!applicable || value || options?.report === false) return value;
-		const diagnostic = {
-			code: _kubb_kit.Diagnostics.code.refNotFound,
-			severity: "error",
-			message: `Could not find a definition for ${refPath}.`,
-			help: "Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.",
-			location: {
-				kind: "schema",
-				pointer: refPath,
-				ref: refPath
-			}
-		};
-		if (!_kubb_kit.Diagnostics.report(diagnostic)) throw new _kubb_kit.Diagnostics.Error(diagnostic);
-		return null;
-	}
-	/**
-	* Resolves a `$ref` to its parsed node via `parse`, guarding against cycles and memoizing per
-	* instance. Returns `null` when the ref is currently being resolved (a cycle) or cannot be
-	* resolved (e.g. a minimal document in a unit test).
-	*/
-	function resolveNode(refPath, parse) {
-		if (resolvingRefs.has(refPath)) return null;
-		if (!resolvedNodeCache.has(refPath)) {
-			let resolved = null;
-			try {
-				const referenced = resolve(refPath);
-				if (referenced) {
-					resolvingRefs.add(refPath);
-					resolved = parse({ schema: referenced });
-					resolvingRefs.delete(refPath);
-				}
-			} catch {}
-			resolvedNodeCache.set(refPath, resolved);
-		}
-		return resolvedNodeCache.get(refPath) ?? null;
-	}
-	/**
-	* Resolves a `$ref` value without mutating anything: when `value` holds a `$ref`, returns the
-	* resolved target. Returns `null` when the value is empty, cannot be resolved, or is still a
-	* `$ref` after resolving (e.g. a document with no component registry). A non-`$ref` value is
-	* returned as-is.
-	*/
-	function deref(value) {
-		if (!isReference(value)) return value ? value : null;
-		const resolved = resolve(value.$ref);
-		return resolved && !isReference(resolved) ? resolved : null;
-	}
-	/** Resolves a `$ref` object but keeps the `$ref` field on the result; other values pass through. */
-	function derefKeepingRef(value) {
-		if (isReference(value)) return {
-			...value,
-			...resolve(value.$ref),
-			$ref: value.$ref
-		};
-		return value;
-	}
-	return {
-		resolve,
-		resolveNode,
-		deref,
-		derefKeepingRef
-	};
-}
-//#endregion
 //#region src/sourceLocator.ts
 let cached;
 const toRange = ([start, end]) => ({
@@ -2702,7 +2914,7 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 				};
 				parsedByName.set(name, node);
 				scanSchema(node);
-				if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
+				if (node.type === "ref" && node.name) refAliasMap.set(name, node);
 				if (_kubb_kit.ast.narrowSchema(node, "enum") && node.name) enumNames.push(node.name);
 				if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
 			}
@@ -2717,6 +2929,36 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 			}));
 			const promotedEnums = enums === "root" ? collectInlineEnums([...parsedByName.values(), ...operationNodes], new Set(Object.keys(schemas))) : null;
 			if (promotedEnums) for (const name of promotedEnums.keys()) enumNames.push(name);
+			const aliasTargetOf = (name) => {
+				const node = refAliasMap.get(name);
+				return node?.ref ? _kubb_kit.ast.refName(node.ref) : node?.name;
+			};
+			function isAliasCycle(name) {
+				const seen = /* @__PURE__ */ new Set([name]);
+				for (let next = aliasTargetOf(name); next; next = aliasTargetOf(next)) {
+					if (next === name) return true;
+					if (seen.has(next)) return false;
+					seen.add(next);
+				}
+				return false;
+			}
+			function createCycleNode(name, pointer) {
+				_kubb_kit.Diagnostics.report({
+					code: _kubb_kit.Diagnostics.code.aliasCycle,
+					severity: "warning",
+					message: `${name} only refers to other schemas that lead back to it, so it is resolved to unknown.`,
+					help: "Give one of the schemas in the loop a real definition, or remove the `$ref` that closes it.",
+					location: {
+						kind: "schema",
+						pointer: pointer ?? `#/components/schemas/${name}`
+					}
+				});
+				return _kubb_kit.ast.factory.createSchema({
+					type: "unknown",
+					name,
+					pointer
+				});
+			}
 			const schemaNodes = promotedEnums ? [...promotedEnums.values()] : [];
 			for (const name of Object.keys(schemas)) {
 				const aliasTarget = refAliasMap.get(name)?.name;
@@ -2724,11 +2966,12 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 				const parsed = parsedByName.get(name);
 				const child = discriminatorChildMap?.get(name);
 				const base = child ? patchDiscriminatorNode(parsed, child) : parsed;
-				const node = aliased ? {
+				const resolved = aliased ? {
 					...aliased,
 					name,
 					pointer: parsed.pointer
 				} : base;
+				const node = isAliasCycle(name) ? createCycleNode(name, parsed.pointer) : resolved;
 				schemaNodes.push(promotedEnums ? refPromotedEnums(node, promotedEnums) : node);
 			}
 			const operations = promotedEnums ? operationNodes.map((node) => refPromotedEnums(node, promotedEnums)) : operationNodes;