@kubb/adapter-oas 5.17.0 → 5.18.0

package/dist/index.js

@@ -1,6 +1,7 @@
 import { defineExtension } from "@kubb/core";
 import { Diagnostics, ast, childName, enumPrimitive, enumPropName, extractRefName, macroDedupeUnion, macroDiscriminatorEnum, macroEnumName, mergeAdjacentObjectsLazy } from "@kubb/kit";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { access, readFile } from "node:fs/promises";
 import { upgrade } from "@scalar/openapi-upgrader";
 import { bundle } from "api-ref-bundler";
@@ -19,7 +20,7 @@ var compatibility = {
 	"node": ">=22.22"
 };
 // package.json
-var version = "5.17.0";
+var version = "5.18.0";
 // src/constants.ts
 /**
 * Default parser options applied when no explicit options are provided.
@@ -401,6 +402,21 @@ function isOpenApi32(document) {
 	const [major = 0, minor = 0] = String(document.openapi).split(".").map(Number);
 	return major > 3 || major === 3 && minor >= 2;
 }
+function pickStrings(source, keys) {
+	if (!source || typeof source !== "object") return void 0;
+	const entries = keys.flatMap((key) => {
+		const value = source[key];
+		return typeof value === "string" ? [[key, value]] : [];
+	});
+	return entries.length ? Object.fromEntries(entries) : void 0;
+}
+function getExternalDocs(source) {
+	const docs = pickStrings(source, ["url", "description"]);
+	return docs?.url ? {
+		url: docs.url,
+		...docs.description !== void 0 && { description: docs.description }
+	} : void 0;
+}
 /**
 * Returns the `x-*` keys of `source` as-is, or `undefined` when there are none.
 */
@@ -415,12 +431,12 @@ 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.
+* Returns `true` when `obj` is a schema with a structured OAS 3.x `discriminator` object that names a
+* `propertyName`, excluding the Swagger 2 string form and a 3.2 discriminator that only sets `defaultMapping`.
 */
 function isDiscriminator(obj) {
-	const record = obj;
-	return !!obj && !!record["discriminator"] && typeof record["discriminator"] !== "string";
+	const discriminator = obj?.["discriminator"];
+	return !!discriminator && typeof discriminator === "object" && typeof discriminator.propertyName === "string";
 }
 /**
 * Returns `true` when a schema is a raw binary payload.
@@ -429,17 +445,32 @@ function isBinary(schema) {
 	return schema.contentMediaType === "application/octet-stream" && schema.contentEncoding === void 0 && (schema.type === void 0 || schema.type === "string");
 }
 /**
+* Keywords that only annotate a schema. A schema with nothing else does not constrain the value.
+*/
+const annotationKeywords = /* @__PURE__ */ new Set([
+	"title",
+	"description",
+	"default",
+	"example",
+	"examples",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"externalDocs"
+]);
+/**
 * 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.
+* instead of a blob. Annotations such as `description` survive the upgrade and are kept.
 */
 function getBinaryFallbackSchema(mediaType, schema) {
 	if (!mediaType || isJsonMimeType(mediaType)) return void 0;
-	if (schema && Object.keys(schema).length > 0) return void 0;
+	if (schema && Object.keys(schema).some((key) => !annotationKeywords.has(key) && !key.startsWith("x-"))) return void 0;
 	return {
+		...schema,
 		type: "string",
 		contentMediaType: "application/octet-stream"
 	};
@@ -578,6 +609,65 @@ function createRefs(document) {
 		derefKeepingRef
 	};
 }
+// src/load/schemaIds.ts
+const DATA_KEYS = /* @__PURE__ */ new Set([
+	"example",
+	"examples",
+	"const",
+	"enum",
+	"default"
+]);
+const NAMED_ENTRY_KEYS = /* @__PURE__ */ new Set([
+	"properties",
+	"patternProperties",
+	"$defs",
+	"definitions",
+	"schemas",
+	"dependentSchemas"
+]);
+function walk(node, pointer, visit, parentKey) {
+	if (!node || typeof node !== "object") return;
+	if (!Array.isArray(node)) visit(node, pointer);
+	const named = parentKey !== void 0 && NAMED_ENTRY_KEYS.has(parentKey);
+	for (const [key, value] of Object.entries(node)) {
+		if (!named && (DATA_KEYS.has(key) || key.startsWith("x-"))) continue;
+		walk(value, `${pointer}/${escapePointerToken(key)}`, visit, Array.isArray(node) ? parentKey : key);
+	}
+}
+/**
+* The declaration in the nearest enclosing schema, else the only one, else `undefined`.
+*/
+function pick(declarations, pointer) {
+	if (!declarations) return void 0;
+	const enclosing = declarations.filter((target) => pointer === target || pointer.startsWith(`${target}/`));
+	if (enclosing.length) return enclosing.reduce((a, b) => b.length > a.length ? b : a);
+	return declarations.length === 1 ? declarations[0] : void 0;
+}
+/**
+* Rewrites, in place, each `$ref` to an `$id`, `$anchor` or `$dynamicAnchor`, and each `$dynamicRef`, into a
+* `#/...` pointer, so it is not fetched. Instance data and `x-` extensions are left as written.
+*
+* shortcut: `$id` matches the `$ref` string exactly and `$dynamicRef` resolves statically to the nearest
+* enclosing anchor, so a relative `$id` base or a recursively extended schema is not followed, upgrade when a spec needs that.
+*/
+function resolveSchemaIds(document) {
+	const targets = /* @__PURE__ */ new Map();
+	const declare = (key, pointer) => targets.set(key, [...targets.get(key) ?? [], pointer]);
+	walk(document, "#", (node, pointer) => {
+		if (typeof node["$id"] === "string") declare(node["$id"], pointer);
+		for (const key of ["$anchor", "$dynamicAnchor"]) if (typeof node[key] === "string") declare(`#${node[key]}`, pointer);
+	});
+	if (!targets.size) return;
+	walk(document, "#", (node, pointer) => {
+		const ref = typeof node["$ref"] === "string" ? pick(targets.get(node["$ref"]), pointer) : void 0;
+		if (ref) node["$ref"] = ref;
+		const dynamicRef = typeof node["$dynamicRef"] === "string" ? pick(targets.get(node["$dynamicRef"]), pointer) : void 0;
+		if (dynamicRef && node["$ref"] === void 0) {
+			node["$ref"] = dynamicRef;
+			delete node["$dynamicRef"];
+		}
+	});
+}
 // src/load/source.ts
 const urlRegExp = /^https?:\/+/i;
 /**
@@ -747,6 +837,21 @@ function isExtensionPath(path) {
 	return path.some((token, index) => String(token).startsWith("x-") && !namedEntryKeys.has(String(path[index - 1])));
 }
 /**
+* Returns the base for relative `$ref`s: the 3.2 `$self` resolved against `pathOrUrl`, else `pathOrUrl`.
+*/
+function getBaseUri(pathOrUrl, root) {
+	const self = root && typeof root === "object" ? root.$self : void 0;
+	if (typeof self !== "string" || !self) return pathOrUrl;
+	try {
+		if (urlRegExp.test(self)) return new URL(self).href;
+		if (/^file:/i.test(self)) return fileURLToPath(self);
+		if (/^[a-z][a-z\d+.-]*:/i.test(self)) return pathOrUrl;
+		return urlRegExp.test(pathOrUrl) ? new URL(self, pathOrUrl).href : resolve(dirname(pathOrUrl), self);
+	} catch {
+		return pathOrUrl;
+	}
+}
+/**
 * 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
@@ -759,8 +864,9 @@ function isExtensionPath(path) {
 * all-internal document it is a no-op that still walks the whole tree to confirm that, which
 * costs real time on a large spec.
 *
-* `document` stands in for the file at `pathOrUrl`, such as inline input. Every other file or URL
-* read, including one that fails, lands in `sources`. A `$ref` that cannot be read reports
+* `document` stands in for the file at `pathOrUrl`, such as inline input. Relative `$ref`s resolve
+* against the OpenAPI 3.2 `$self` when the document sets one. Every other file or URL read,
+* including one that fails, lands in `sources`. A `$ref` that cannot be read reports
 * `KUBB_REF_NOT_FOUND` at the key that holds it, as a warning when it sits inside an `x-` extension.
 *
 * @example Local file
@@ -772,8 +878,10 @@ function isExtensionPath(path) {
 async function bundleDocument(pathOrUrl, { document, sources = [] } = {}) {
 	const cache = /* @__PURE__ */ new Map();
 	const toKey = (sourcePath) => urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath;
+	let entry = pathOrUrl;
+	let entryDocument = document;
 	const resolver = (sourcePath) => {
-		if (document && sourcePath === pathOrUrl) return Promise.resolve(document);
+		if (entryDocument !== void 0 && toKey(sourcePath) === toKey(entry)) return Promise.resolve(entryDocument);
 		const key = toKey(sourcePath);
 		const cached = cache.get(key);
 		if (cached) return cached;
@@ -783,9 +891,12 @@ async function bundleDocument(pathOrUrl, { document, sources = [] } = {}) {
 		return result;
 	};
 	const root = await resolver(pathOrUrl);
+	resolveSchemaIds(root);
 	if (typeof root === "object" && root !== null && !hasExternalRef(root)) return root;
-	return await bundle(pathOrUrl, resolver, { hooks: { onError: (message, { path, state }) => {
-		const pointer = toKey(state.baseFile) === toKey(pathOrUrl) ? `#/${path.map((token) => escapePointerToken(String(token))).join("/")}` : void 0;
+	entry = getBaseUri(pathOrUrl, root);
+	entryDocument = root;
+	return await bundle(entry, resolver, { hooks: { onError: (message, { path, state }) => {
+		const pointer = toKey(state.baseFile) === toKey(entry) ? `#/${path.map((token) => escapePointerToken(String(token))).join("/")}` : void 0;
 		const diagnostic = {
 			code: Diagnostics.code.refNotFound,
 			severity: isExtensionPath(path) ? "warning" : "error",
@@ -824,10 +935,12 @@ async function parseFromConfig(source, sources = []) {
 				origin: "the inline `input` string",
 				help: "Fix the syntax at the reported line. Kubb reads `input` as an inline spec, not a file path, because it starts with `{`, `[`, `openapi:`, or `swagger:`, or spans several lines."
 			}) : structuredClone(source.data);
-			return source.root && hasExternalRef(data) ? bundleDocument(join(source.root, inlineInputName), {
+			if (source.root && hasExternalRef(data)) return bundleDocument(join(source.root, inlineInputName), {
 				document: data,
 				sources
-			}) : data;
+			});
+			resolveSchemaIds(data);
+			return data;
 		}
 		await assertInputExists(source.path);
 		return bundleDocument(source.path, { sources });
@@ -1152,6 +1265,80 @@ function getSchemas(document, { contentType }, refs) {
 		pointers
 	};
 }
+// src/model/security.ts
+const SCHEME_POINTER = "#/components/securitySchemes/";
+const API_KEY_LOCATIONS = /* @__PURE__ */ new Set([
+	"header",
+	"query",
+	"cookie"
+]);
+function getCredential(scheme) {
+	if (scheme.type === "apiKey") return scheme.name && scheme.in && API_KEY_LOCATIONS.has(scheme.in) ? {
+		type: "apiKey",
+		in: scheme.in,
+		name: scheme.name
+	} : void 0;
+	if (scheme.type === "http") return scheme.scheme ? {
+		type: "http",
+		scheme: scheme.scheme.toLowerCase(),
+		...scheme.bearerFormat && { bearerFormat: scheme.bearerFormat }
+	} : void 0;
+	if (scheme.type === "openIdConnect") return {
+		type: "openIdConnect",
+		...scheme.openIdConnectUrl && { url: scheme.openIdConnectUrl }
+	};
+	if (scheme.type === "oauth2") {
+		const flows = Object.entries(scheme.flows ?? {}).map(([name, flow]) => {
+			const scopes = flow && typeof flow === "object" && flow.scopes && typeof flow.scopes === "object" ? { scopes: flow.scopes } : {};
+			return [name, {
+				...pickStrings(flow, [
+					"authorizationUrl",
+					"deviceAuthorizationUrl",
+					"tokenUrl",
+					"refreshUrl"
+				]),
+				...scopes
+			}];
+		});
+		return {
+			type: "oauth2",
+			flows: Object.fromEntries(flows),
+			...scheme.oauth2MetadataUrl && { metadataUrl: scheme.oauth2MetadataUrl }
+		};
+	}
+	return scheme.type === "mutualTLS" ? { type: "mutualTLS" } : void 0;
+}
+/**
+* Maps `components.securitySchemes` to `AuthScheme` entries, leaving out a scheme a client cannot place.
+*/
+function toAuthSchemes(schemes, refs) {
+	return Object.entries(schemes ?? {}).flatMap(([name, value]) => {
+		const scheme = refs.deref(value);
+		const credential = scheme && getCredential(scheme);
+		if (!scheme || !credential) return [];
+		return [{
+			name,
+			...scheme.description && { description: scheme.description },
+			...scheme.deprecated && { deprecated: true },
+			credential
+		}];
+	});
+}
+/**
+* Maps security requirements to `AuthRequirement` entries. A 3.2 URI key becomes the scheme name.
+*/
+function toAuthRequirements(requirements, document) {
+	if (!Array.isArray(requirements)) return void 0;
+	const schemes = document.components?.securitySchemes ?? {};
+	const toName = (key) => {
+		const index = key.indexOf(SCHEME_POINTER);
+		return Object.hasOwn(schemes, key) || index === -1 ? key : unescapePointerToken(key.slice(index + 29));
+	};
+	return requirements.filter((requirement) => !!requirement && typeof requirement === "object").map((requirement) => Object.entries(requirement).map(([key, scopes]) => ({
+		scheme: toName(key),
+		...Array.isArray(scopes) && scopes.length && { scopes: scopes.map(String) }
+	})));
+}
 // src/model/server.ts
 /**
 * Reads the server URL from the document's `servers` array at `server.index`,
@@ -1208,8 +1395,11 @@ function resolveServerUrl(server, overrides) {
 * Maps OpenAPI servers to `InputServer` entries: drops entries without a `url` and fills `{variable}` defaults.
 */
 function toInputServers(servers) {
-	return servers.filter((entry) => entry.url).map(({ url, description, variables }) => {
-		const declared = variables && Object.keys(variables).length > 0 ? { variables } : {};
+	return servers.filter((entry) => entry.url).map(({ url, name, description, variables }) => {
+		const declared = {
+			...name !== void 0 && { name },
+			...variables && Object.keys(variables).length > 0 && { variables }
+		};
 		try {
 			return {
 				url: resolveServerUrl({
@@ -1228,6 +1418,20 @@ function toInputServers(servers) {
 		}
 	});
 }
+// src/model/tag.ts
+function toInputTags(tags) {
+	return tags.filter((tag) => typeof tag.name === "string").map(({ name, summary, description, parent, kind, externalDocs }) => {
+		const docs = getExternalDocs(externalDocs);
+		return {
+			name,
+			...typeof summary === "string" && { summary },
+			...typeof description === "string" && { description },
+			...typeof parent === "string" && { parent },
+			...typeof kind === "string" && { kind },
+			...docs && { externalDocs: docs }
+		};
+	});
+}
 // src/model/mediaType.ts
 /**
 * The media type without its parameters, so `text/event-stream; charset=utf-8` matches the bare name.
@@ -1409,6 +1613,39 @@ function flattenSchema(schema) {
 function scanSchema(node, pointer = node.pointer) {
 	if (pointer) visit(node, pointer);
 }
+let formatTally;
+/**
+* Runs `fn` and reports `KUBB_UNSUPPORTED_FORMAT` once per format with the number of schemas that use it,
+* instead of once per schema. `format` is an open value in OpenAPI, so a large spec would otherwise print
+* thousands of warnings that say the same thing. `fn` must be synchronous.
+*/
+function groupUnsupportedFormats(fn) {
+	formatTally = /* @__PURE__ */ new Map();
+	try {
+		return fn();
+	} finally {
+		const tally = formatTally;
+		formatTally = void 0;
+		for (const [format, pointers] of tally) reportUnsupportedFormat(format, [...pointers]);
+	}
+}
+function tallyFormat(format, pointer) {
+	if (!formatTally) return reportUnsupportedFormat(format, [pointer]);
+	formatTally.set(format, (formatTally.get(format) ?? /* @__PURE__ */ new Set()).add(pointer));
+}
+function reportUnsupportedFormat(format, pointers) {
+	const count = pointers.length;
+	Diagnostics.report({
+		code: Diagnostics.code.unsupportedFormat,
+		severity: "warning",
+		message: count === 1 ? `Kubb does not map the format "${format}" to a specific type, so it falls back to the base type.` : `Kubb does not map the format "${format}" to a specific type, so ${count} schemas fall back to the base type.`,
+		help: `Use a format Kubb supports, or handle "${format}" with a custom parser or plugin.`,
+		location: {
+			kind: "schema",
+			pointer: pointers[0]
+		}
+	});
+}
 function visit(node, pointer) {
 	node.pointer ??= pointer;
 	if (node.deprecated) Diagnostics.report({
@@ -1420,16 +1657,7 @@ function visit(node, pointer) {
 			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 (typeof node.format === "string" && !isHandledFormat(node.format)) tallyFormat(node.format, 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`);
@@ -1538,18 +1766,6 @@ function getResponseByStatusCode({ operation, refs, statusCode }) {
 function getRequestBody({ operation, refs }) {
 	return refs.deref(operation.schema.requestBody);
 }
-/**
-* Returns the primary request content type. Prefers a JSON-like media type (the last one wins
-* when several are declared), then the first declared one, defaulting to `'application/json'`.
-*/
-function getRequestContentType({ operation, refs }) {
-	const content = getRequestBody({
-		operation,
-		refs
-	})?.content;
-	const mediaTypes = content ? Object.keys(content) : [];
-	return mediaTypes.findLast(isJsonMimeType) ?? mediaTypes[0] ?? "application/json";
-}
 /** Merges path-level and operation-level parameters; operation-level wins per `in:name`. */
 function getParameters({ operation, refs }) {
 	const resolveParams = (params, pointer) => params.flatMap((entry, index) => {
@@ -1573,7 +1789,8 @@ const PARAMETER_STYLES = /* @__PURE__ */ new Set([
 	"simple",
 	"spaceDelimited",
 	"pipeDelimited",
-	"deepObject"
+	"deepObject",
+	"cookie"
 ]);
 function pickStyleFields({ style, explode, allowReserved }) {
 	return {
@@ -1582,16 +1799,45 @@ function pickStyleFields({ style, explode, allowReserved }) {
 		...allowReserved !== void 0 ? { allowReserved } : {}
 	};
 }
-/** 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, ...rest }]) => {
-		const node = {
-			...contentType !== void 0 ? { contentType } : {},
-			...pickStyleFields(rest)
-		};
+function getEncodingFields({ encoding, prefixEncoding, itemEncoding }) {
+	const entries = Object.entries(encoding ?? {}).flatMap(([property, entry]) => {
+		const node = toEncodingNode(entry);
 		return Object.keys(node).length ? [[property, node]] : [];
 	});
-	return entries.length ? Object.fromEntries(entries) : void 0;
+	const item = itemEncoding && toEncodingNode(itemEncoding);
+	return {
+		...entries.length && { encoding: Object.fromEntries(entries) },
+		...prefixEncoding?.length && { prefixEncoding: prefixEncoding.map(toEncodingNode) },
+		...item && Object.keys(item).length && { itemEncoding: item }
+	};
+}
+function toEncodingNode({ contentType, encoding, prefixEncoding, itemEncoding, ...rest }) {
+	return {
+		...contentType !== void 0 && { contentType },
+		...pickStyleFields(rest),
+		...getEncodingFields({
+			encoding,
+			prefixEncoding,
+			itemEncoding
+		})
+	};
+}
+function getExamples({ example, examples }, refs) {
+	const named = Object.entries(examples ?? {}).flatMap(([name, entry]) => {
+		const resolved = refs.deref(entry);
+		if (!resolved) return [];
+		const { summary, description, dataValue, value, serializedValue } = resolved;
+		const data = dataValue !== void 0 ? dataValue : value;
+		return [{
+			name,
+			...typeof summary === "string" && { summary },
+			...typeof description === "string" && { description },
+			...data !== void 0 && { value: data },
+			...typeof serializedValue === "string" && { serializedValue }
+		}];
+	});
+	if (named.length) return { examples: named };
+	return example !== void 0 ? { examples: [{ value: example }] } : {};
 }
 /**
 * Returns the media type entry for `contentType`, resolving a `$ref` into `components.mediaTypes`. `null` when absent.
@@ -1620,6 +1866,24 @@ function getBodySchema({ content, contentType, refs, document }) {
 	if (binary) return binary;
 	return schema ? refs.derefKeepingRef(schema) : null;
 }
+function getLinks(links, refs) {
+	const entries = Object.entries(links ?? {}).flatMap(([name, value]) => {
+		const link = refs.deref(value);
+		if (!link) return [];
+		const server = link.server ? toInputServers([link.server])[0] : void 0;
+		return [[name, {
+			...pickStrings(link, [
+				"operationId",
+				"operationRef",
+				"description"
+			]),
+			...link.parameters && { parameters: link.parameters },
+			..."requestBody" in link && { requestBody: link.requestBody },
+			...server && { server }
+		}]];
+	});
+	return entries.length ? Object.fromEntries(entries) : void 0;
+}
 /** The `stream` field of a content node, set when the media type is a stream. `node` is the parsed item schema. */
 function getStreamField({ contentType, mediaType, refs, document, node }) {
 	if (!isStream(contentType, mediaType)) return {};
@@ -1690,11 +1954,12 @@ function collectPropertyKeysByFlag(schema, flag) {
 function parseParameter({ param, pointer, parentName, options, parseSchema, refs }) {
 	const schemaName = parentName && param.name ? pascalCase(`${parentName} ${param.name}`) : void 0;
 	const contentType = param.schema ? void 0 : Object.keys(param.content ?? {})[0];
-	const rawSchema = param.schema ?? getMediaType({
+	const mediaType = getMediaType({
 		content: param.content,
 		contentType,
 		refs
-	})?.schema;
+	});
+	const rawSchema = param.schema ?? mediaType?.schema;
 	const schema = rawSchema ? parseSchema({
 		schema: rawSchema,
 		name: schemaName
@@ -1710,7 +1975,10 @@ function parseParameter({ param, pointer, parentName, options, parseSchema, refs
 		},
 		required: param.required ?? false,
 		...pickStyleFields(param),
-		...contentType !== void 0 ? { contentType } : {}
+		...contentType !== void 0 ? { contentType } : {},
+		...getExamples(mediaType ?? param, refs),
+		...param.deprecated && { deprecated: true },
+		...param.allowEmptyValue && { allowEmptyValue: true }
 	});
 }
 /**
@@ -1755,12 +2023,12 @@ function parseOperation({ operation, ...ctx }) {
 			name: requestBodyName
 		}), bodyRequired);
 		scanSchema(node, `${mediaTypePointer(body?.content, ct, `${pointer}/requestBody/content/${escapePointerToken(ct)}`)}/${schemaKeyword(mediaType)}`);
-		const encoding = getEncoding(mediaType?.encoding);
 		return [ast.factory.createContent({
 			contentType: ct,
 			schema: node,
 			keysToOmit: collectPropertyKeysByFlag(schema, "readOnly"),
-			...encoding && { encoding },
+			...mediaType && getEncodingFields(mediaType),
+			...mediaType && getExamples(mediaType, refs),
 			...getStreamField({
 				contentType: ct,
 				mediaType,
@@ -1803,6 +2071,8 @@ function parseOperation({ operation, ...ctx }) {
 			return {
 				schema: node,
 				keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly"),
+				...mediaType && getEncodingFields(mediaType),
+				...mediaType && getExamples(mediaType, refs),
 				...ct ? getStreamField({
 					contentType: ct,
 					mediaType,
@@ -1812,22 +2082,41 @@ function parseOperation({ operation, ...ctx }) {
 				}) : {}
 			};
 		};
-		const responseContent = (contentType ? [contentType] : Object.keys(response?.content ?? {})).map((ct) => ast.factory.createContent({
+		const declaredContentTypes = Object.keys(response?.content ?? {});
+		const responseContent = (contentType && declaredContentTypes.length ? [contentType] : declaredContentTypes).map((ct) => ast.factory.createContent({
 			contentType: ct,
 			...parseEntrySchema(ct)
 		}));
 		if (responseContent.length === 0) responseContent.push(ast.factory.createContent({
-			contentType: getRequestContentType({
-				operation,
-				refs
-			}),
+			contentType: "",
 			...parseEntrySchema(contentType)
 		}));
+		const responsePointer = `${pointer}/responses/${statusCode}`;
+		const headers = Object.entries(response?.headers ?? {}).flatMap(([name, value]) => {
+			const header = name.toLowerCase() === "content-type" ? null : refs.deref(value);
+			if (!header) return [];
+			return [parseParameter({
+				param: {
+					...header,
+					name,
+					in: "header"
+				},
+				pointer: `${responsePointer}/headers/${escapePointerToken(name)}`,
+				parentName: responseName,
+				options,
+				parseSchema,
+				refs
+			})];
+		});
+		const links = getLinks(response?.links, refs);
 		return ast.factory.createResponse({
-			pointer: `${pointer}/responses/${statusCode}`,
+			pointer: responsePointer,
 			statusCode,
+			summary: response?.summary,
 			description: response?.description,
-			content: responseContent
+			content: responseContent,
+			...headers.length && { headers },
+			...links && { links }
 		});
 	});
 	const pickDoc = (key) => {
@@ -1837,6 +2126,7 @@ function parseOperation({ operation, ...ctx }) {
 		return typeof fallback === "string" ? fallback : void 0;
 	};
 	const servers = operation.schema.servers ?? operation.pathItem.servers;
+	const auth = toAuthRequirements(operation.schema.security ?? document.security, document);
 	return ast.factory.createOperation({
 		pointer,
 		operationId,
@@ -1847,11 +2137,13 @@ function parseOperation({ operation, ...ctx }) {
 		summary: pickDoc("summary") || void 0,
 		description: pickDoc("description") || void 0,
 		deprecated: operation.schema.deprecated || void 0,
+		externalDocs: getExternalDocs(operation.schema.externalDocs),
 		parameters,
 		requestBody,
 		responses,
 		extensions: pickExtensions(operation.schema),
-		...servers && { servers: toInputServers(servers) }
+		...servers && { servers: toInputServers(servers) },
+		...auth && { auth }
 	});
 }
 // src/emit/createNode.ts
@@ -1872,6 +2164,7 @@ function createNode({ schema, name, nullable, defaultValue }, extras) {
 		default: defaultValue,
 		examples: extractExamples(schema),
 		format: schema.format,
+		externalDocs: getExternalDocs(schema.externalDocs),
 		...extras
 	});
 }
@@ -2000,6 +2293,15 @@ function removeInheritedDiscriminator({ members, refs }) {
 	});
 }
 /**
+* Whether a member can carry the discriminator property. A discriminator is only a hint, so an array
+* or primitive member keeps its own type instead of an intersection no value can satisfy.
+*/
+function isObjectLike(member, refs) {
+	const type = (isReference(member) ? refs.resolve(member.$ref, { report: false }) : member)?.type;
+	if (type === void 0) return true;
+	return Array.isArray(type) ? type.includes("object") : type === "object";
+}
+/**
 * 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
@@ -2062,7 +2364,7 @@ function narrowUnionMembers({ unionMembers, discriminator, sharedPropertiesNode,
 			schema: s,
 			name
 		});
-		if (!discriminatorValues.length || !discriminator) return memberNode;
+		if (!discriminatorValues.length || !discriminator || !isObjectLike(s, refs)) return memberNode;
 		const narrowedDiscriminatorNode = sharedPropertiesNode ? pickDiscriminatorPropertyNode(ast.applyMacros(sharedPropertiesNode, [macroDiscriminatorEnum({
 			propertyName: discriminator.propertyName,
 			values: discriminatorValues
@@ -2327,13 +2629,15 @@ const annotationKeys = /* @__PURE__ */ new Set([
 ]);
 /**
 * 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.
+* not become `unknown`. The parent's own values win. The parser reads their `if`/`then`/`else` into `conditionals`.
 */
+function isAnnotationMember(member) {
+	return !!member && typeof member === "object" && !isReference(member) && Object.keys(member).every((key) => annotationKeys.has(key));
+}
 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));
+	const annotations = members.filter(isAnnotationMember);
+	const rest = members.filter((member) => !isAnnotationMember(member));
 	return annotations.length && rest.length ? {
 		...Object.assign({}, ...annotations),
 		...schema,
@@ -2366,7 +2670,8 @@ function convertAllOf({ schema: original, name, nullable, defaultValue, parse, r
 			default: mergedDefault,
 			examples: extractExamples(schema) ?? memberNode.examples,
 			pattern: schema.pattern ?? ("pattern" in memberNode ? memberNode.pattern : void 0),
-			format: schema.format ?? memberNode.format
+			format: schema.format ?? memberNode.format,
+			externalDocs: getExternalDocs(schema.externalDocs) ?? memberNode.externalDocs
 		});
 	}
 	const { members: discriminatedAllOf, discriminantValues } = extractDiscriminatedAllOfMembers({
@@ -2441,7 +2746,7 @@ function convertUnion(context) {
 	};
 	const discriminator = isDiscriminator(schema) ? schema.discriminator : void 0;
 	const declaredMembers = [...schema.oneOf ?? [], ...schema.anyOf ?? []];
-	const defaultRef = getDefaultMappingRef(discriminator);
+	const defaultRef = getDefaultMappingRef(typeof schema.discriminator === "object" ? schema.discriminator : void 0);
 	const unionMembers = resolveUnionMembers(defaultRef && !declaredMembers.some((member) => isReference(member) && member.$ref === defaultRef) ? [...declaredMembers, { $ref: defaultRef }] : declaredMembers, schema.properties ?? {});
 	const strategy = schema.oneOf ? "one" : "any";
 	const explicitDiscriminatorPropertyName = discriminator?.propertyName;
@@ -2553,11 +2858,18 @@ function getPrimitiveType(type) {
 }
 /** Shared by number, integer and bigint nodes; the exclusive bounds keep only the OAS 3.1 numeric form. */
 function getNumericConstraints(schema) {
+	const exclusiveMinimum = typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0;
+	const exclusiveMaximum = typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0;
+	const hasExclusive = exclusiveMinimum !== void 0 || exclusiveMaximum !== void 0;
 	return {
 		min: schema.minimum,
 		max: schema.maximum,
-		exclusiveMinimum: typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : void 0,
-		exclusiveMaximum: typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : void 0,
+		...hasExclusive && { exclusive: {
+			...exclusiveMinimum !== void 0 && { min: exclusiveMinimum },
+			...exclusiveMaximum !== void 0 && { max: exclusiveMaximum }
+		} },
+		exclusiveMinimum,
+		exclusiveMaximum,
 		multipleOf: schema.multipleOf
 	};
 }
@@ -2566,11 +2878,11 @@ function getNumericConstraints(schema) {
 */
 function isWithinBounds({ value, schema }) {
 	if (typeof value !== "number") return true;
-	const { min, max, exclusiveMinimum, exclusiveMaximum, multipleOf } = getNumericConstraints(schema);
+	const { min, max, exclusive, multipleOf } = getNumericConstraints(schema);
 	if (min !== void 0 && value < min) return false;
 	if (max !== void 0 && value > max) return false;
-	if (exclusiveMinimum !== void 0 && value <= exclusiveMinimum) return false;
-	if (exclusiveMaximum !== void 0 && value >= exclusiveMaximum) return false;
+	if (exclusive?.min !== void 0 && value <= exclusive.min) return false;
+	if (exclusive?.max !== void 0 && value >= exclusive.max) return false;
 	if (multipleOf !== void 0 && Math.abs(value / multipleOf - Math.round(value / multipleOf)) > 1e-9) return false;
 	return true;
 }
@@ -2728,6 +3040,15 @@ function convertFormattedEnum(context) {
 		}))
 	});
 }
+function getStringContent({ schema, parse }) {
+	const { contentMediaType: mediaType, contentEncoding: encoding, contentSchema } = schema;
+	if (mediaType === void 0 && encoding === void 0 && !contentSchema) return {};
+	return { content: {
+		...mediaType !== void 0 && { mediaType },
+		...encoding !== void 0 && { encoding },
+		...contentSchema && { schema: parse({ schema: contentSchema }) }
+	} };
+}
 /**
 * Converts a `type: 'string'` schema into a `StringSchemaNode`.
 */
@@ -2738,7 +3059,8 @@ function convertString(context) {
 		primitive: "string",
 		min: schema.minLength,
 		max: schema.maxLength,
-		pattern: schema.pattern
+		pattern: schema.pattern,
+		...getStringContent(context)
 	});
 }
 /**
@@ -2752,6 +3074,15 @@ function convertNumeric(context, type) {
 	});
 }
 // src/emit/converters/structural.ts
+function getContains(schema, parse) {
+	const { contains, minContains, maxContains } = schema;
+	if (!contains || typeof contains !== "object") return {};
+	return { contains: {
+		schema: parse({ schema: contains }),
+		...typeof minContains === "number" && { min: minContains },
+		...typeof maxContains === "number" && { max: maxContains }
+	} };
+}
 /**
 * Resolves a `true` or empty-object map schema (`additionalProperties`/`patternProperties`) to
 * `options.unknownType`, otherwise parses it as a regular schema.
@@ -2804,7 +3135,7 @@ function convertObject({ schema, name, nullable, defaultValue, options, parse, r
 			required
 		});
 	}) : [];
-	const additionalProperties = schema.additionalProperties;
+	const additionalProperties = schema.additionalProperties ?? schema.unevaluatedProperties;
 	const additionalPropertiesNode = (() => {
 		if (additionalProperties === true) return true;
 		if (additionalProperties) return resolveMapSchema(additionalProperties, {
@@ -2834,6 +3165,8 @@ function convertObject({ schema, name, nullable, defaultValue, options, parse, r
 		additionalProperties: additionalPropertiesNode,
 		patternProperties,
 		propertyNames,
+		min: schema.minProperties,
+		max: schema.maxProperties,
 		minProperties: schema.minProperties,
 		maxProperties: schema.maxProperties
 	});
@@ -2864,7 +3197,8 @@ function convertObject({ schema, name, nullable, defaultValue, options, parse, r
 */
 function convertTuple({ schema, name, nullable, defaultValue, options, parse }) {
 	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }));
-	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: schema.items });
+	const tail = schema.items ?? schema.unevaluatedItems;
+	const rest = tail === false ? void 0 : !tail || tail === true ? ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: tail });
 	return createNode({
 		schema,
 		name,
@@ -2876,7 +3210,8 @@ function convertTuple({ schema, name, nullable, defaultValue, options, parse })
 		items: tupleItems,
 		rest,
 		min: schema.minItems,
-		max: schema.maxItems
+		max: schema.maxItems,
+		...getContains(schema, parse)
 	});
 }
 /**
@@ -2900,7 +3235,8 @@ function convertArray({ schema, name, nullable, defaultValue, options, parse })
 		items,
 		min: schema.minItems,
 		max: schema.maxItems,
-		unique: schema.uniqueItems ?? void 0
+		unique: schema.uniqueItems ?? void 0,
+		...getContains(schema, parse)
 	});
 }
 // src/emit/parseSchema.ts
@@ -3028,6 +3364,20 @@ const schemaRules = [
 ];
 // src/parser.ts
 /**
+* `unevaluated*` also sees what composition siblings evaluate, so with such a sibling it is dropped to keep the schema open.
+*/
+function hasUnevaluatedSiblings(schema) {
+	if (schema.unevaluatedProperties === void 0 && schema.unevaluatedItems === void 0) return false;
+	return [
+		schema.allOf,
+		schema.anyOf,
+		schema.oneOf,
+		schema.if,
+		schema.dependentSchemas,
+		schema.$ref
+	].some((value) => value !== void 0);
+}
+/**
 * Creates the schema converter bound to one OpenAPI document: `parseSchema` dispatches each
 * schema through the ordered `schemaRules` table, with the parser options merged once.
 *
@@ -3045,6 +3395,13 @@ function createSchemaParser(ctx) {
 			schema: flattenedSchema,
 			name
 		});
+		if (hasUnevaluatedSiblings(schema)) {
+			const { unevaluatedProperties: _properties, unevaluatedItems: _items, ...open } = schema;
+			return parseSchema({
+				schema: open,
+				name
+			});
+		}
 		const nullable = isNullable(schema) || void 0;
 		const context = {
 			schema,
@@ -3058,8 +3415,62 @@ function createSchemaParser(ctx) {
 			refs,
 			renames
 		};
-		for (const rule of schemaRules) if (rule.match(context)) return rule.convert(context);
-		return createNode(context, { type: options.emptySchemaType });
+		const rule = schemaRules.find((entry) => entry.match(context));
+		return withConditionals(rule ? rule.convert(context) : createNode(context, { type: options.emptySchemaType }), schema);
+	}
+	function requireKeys(keys) {
+		const unknown = ast.factory.createSchema({ type: ast.schemaTypes.unknown });
+		return ast.factory.createSchema({
+			type: ast.schemaTypes.object,
+			primitive: "object",
+			properties: keys.map((name) => ast.factory.createProperty({
+				name,
+				required: true,
+				schema: unknown
+			}))
+		});
+	}
+	/**
+	* Adds `if`/`then`/`else`, `dependentRequired` and `dependentSchemas` to the node as `conditionals`.
+	*/
+	function withConditionals(node, schema) {
+		const conditionals = [schema, ...Array.isArray(schema.allOf) ? schema.allOf.filter(isAnnotationMember) : []].flatMap(toConditionals);
+		return conditionals.length ? {
+			...node,
+			conditionals
+		} : node;
+	}
+	function toConditionals(schema) {
+		const branch = (value) => {
+			if (!value || typeof value !== "object") return void 0;
+			const { required, type, ...rest } = value;
+			if (Array.isArray(required) && required.length && (type === void 0 || type === "object") && !Object.keys(rest).length) return requireKeys(required);
+			return parseSchema({ schema: value });
+		};
+		const entries = (value) => value && typeof value === "object" ? Object.entries(value) : [];
+		const conditionals = [];
+		const condition = branch(schema.if);
+		if (condition) {
+			const thenNode = branch(schema.then);
+			const elseNode = branch(schema.else);
+			conditionals.push({
+				if: condition,
+				...thenNode && { then: thenNode },
+				...elseNode && { else: elseNode }
+			});
+		}
+		for (const [key, required] of entries(schema.dependentRequired)) if (Array.isArray(required) && required.length && required.every((name) => typeof name === "string")) conditionals.push({
+			if: requireKeys([key]),
+			then: requireKeys(required)
+		});
+		for (const [key, dependent] of entries(schema.dependentSchemas)) {
+			const thenNode = branch(dependent);
+			if (thenNode) conditionals.push({
+				if: requireKeys([key]),
+				then: thenNode
+			});
+		}
+		return conditionals;
 	}
 	return parseSchema;
 }
@@ -3399,6 +3810,7 @@ const adapterOas = defineExtension({
 				schemaNodes.push(promotedEnums ? refPromotedEnums(node, promotedEnums) : node);
 			}
 			const operations = promotedEnums ? operationNodes.map((node) => refPromotedEnums(node, promotedEnums)) : operationNodes;
+			const authSchemes = toAuthSchemes(document.components?.securitySchemes, refs);
 			return ast.factory.createInput({
 				schemas: schemaNodes,
 				operations,
@@ -3406,23 +3818,25 @@ const adapterOas = defineExtension({
 					title: document.info?.title,
 					description: document.info?.description,
 					version: document.info?.version,
+					summary: document.info?.summary,
+					termsOfService: document.info?.termsOfService,
+					contact: pickStrings(document.info?.contact, [
+						"name",
+						"url",
+						"email"
+					]),
+					license: typeof document.info?.license?.name === "string" ? {
+						...pickStrings(document.info.license, ["identifier", "url"]),
+						name: document.info.license.name
+					} : void 0,
+					externalDocs: getExternalDocs(document.externalDocs),
 					baseURL: resolveBaseUrl({
 						document,
 						server
 					}),
 					servers: toInputServers(document.servers ?? []),
-					securitySchemes: Object.entries(document.components?.securitySchemes ?? {}).flatMap(([name, value]) => {
-						const scheme = refs.deref(value);
-						return scheme?.type ? [{
-							name,
-							type: scheme.type,
-							description: scheme.description,
-							scheme: scheme.scheme,
-							bearerFormat: scheme.bearerFormat,
-							in: scheme.in,
-							parameterName: scheme.name
-						}] : [];
-					}),
+					...document.tags?.length && { tags: toInputTags(document.tags) },
+					...authSchemes.length && { auth: authSchemes },
 					extensions: pickExtensions(document)
 				}
 			});
@@ -3463,18 +3877,19 @@ const adapterOas = defineExtension({
 					parsedDocument = document;
 					const refs = createRefs(document);
 					const { schemas, renames, pointers } = getSchemas(document, { contentType }, refs);
-					return parseInput({
+					const parseSchema = createSchemaParser({
+						document,
+						refs,
+						renames,
+						options: parserOptions
+					});
+					return groupUnsupportedFormats(() => parseInput({
 						document,
 						refs,
 						schemas,
 						pointers,
-						parseSchema: createSchemaParser({
-							document,
-							refs,
-							renames,
-							options: parserOptions
-						})
-					});
+						parseSchema
+					}));
 				})();
 				inputCache.set(source, {
 					promise,