@kubb/adapter-oas 5.16.1 → 5.17.1

package/dist/index.cjs

@@ -35,7 +35,7 @@ var compatibility = {
 	"node": ">=22.22"
 };
 // package.json
-var version = "5.16.1";
+var version = "5.17.1";
 // src/constants.ts
 /**
 * Default parser options applied when no explicit options are provided.
@@ -445,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"
 	};
@@ -1220,6 +1235,30 @@ function resolveServerUrl(server, overrides) {
 	}
 	return url;
 }
+/**
+* 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 } : {};
+		try {
+			return {
+				url: resolveServerUrl({
+					url,
+					variables
+				}),
+				description,
+				...declared
+			};
+		} catch {
+			return {
+				url,
+				description,
+				...declared
+			};
+		}
+	});
+}
 // src/model/mediaType.ts
 /**
 * The media type without its parameters, so `text/event-stream; charset=utf-8` matches the bare name.
@@ -1401,6 +1440,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;
+	_kubb_kit.Diagnostics.report({
+		code: _kubb_kit.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) _kubb_kit.Diagnostics.report({
@@ -1412,16 +1484,7 @@ function visit(node, pointer) {
 			pointer
 		}
 	});
-	if (typeof node.format === "string" && !isHandledFormat(node.format)) _kubb_kit.Diagnostics.report({
-		code: _kubb_kit.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`);
@@ -1530,18 +1593,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) => {
@@ -1804,15 +1855,13 @@ function parseOperation({ operation, ...ctx }) {
 				}) : {}
 			};
 		};
-		const responseContent = (contentType ? [contentType] : Object.keys(response?.content ?? {})).map((ct) => _kubb_kit.ast.factory.createContent({
+		const declaredContentTypes = Object.keys(response?.content ?? {});
+		const responseContent = (contentType && declaredContentTypes.length ? [contentType] : declaredContentTypes).map((ct) => _kubb_kit.ast.factory.createContent({
 			contentType: ct,
 			...parseEntrySchema(ct)
 		}));
 		if (responseContent.length === 0) responseContent.push(_kubb_kit.ast.factory.createContent({
-			contentType: getRequestContentType({
-				operation,
-				refs
-			}),
+			contentType: "",
 			...parseEntrySchema(contentType)
 		}));
 		return _kubb_kit.ast.factory.createResponse({
@@ -1828,6 +1877,7 @@ function parseOperation({ operation, ...ctx }) {
 		const fallback = operation.pathItem[key];
 		return typeof fallback === "string" ? fallback : void 0;
 	};
+	const servers = operation.schema.servers ?? operation.pathItem.servers;
 	return _kubb_kit.ast.factory.createOperation({
 		pointer,
 		operationId,
@@ -1841,7 +1891,8 @@ function parseOperation({ operation, ...ctx }) {
 		parameters,
 		requestBody,
 		responses,
-		extensions: pickExtensions(operation.schema)
+		extensions: pickExtensions(operation.schema),
+		...servers && { servers: toInputServers(servers) }
 	});
 }
 // src/emit/createNode.ts
@@ -1990,6 +2041,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
@@ -2052,7 +2112,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(_kubb_kit.ast.applyMacros(sharedPropertiesNode, [(0, _kubb_kit.macroDiscriminatorEnum)({
 			propertyName: discriminator.propertyName,
 			values: discriminatorValues
@@ -3399,25 +3459,7 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 						document,
 						server
 					}),
-					servers: (document.servers ?? []).filter((entry) => entry.url).map(({ url, description, variables }) => {
-						const declared = variables && Object.keys(variables).length > 0 ? { variables } : {};
-						try {
-							return {
-								url: resolveServerUrl({
-									url,
-									variables
-								}),
-								description,
-								...declared
-							};
-						} catch {
-							return {
-								url,
-								description,
-								...declared
-							};
-						}
-					}),
+					servers: toInputServers(document.servers ?? []),
 					securitySchemes: Object.entries(document.components?.securitySchemes ?? {}).flatMap(([name, value]) => {
 						const scheme = refs.deref(value);
 						return scheme?.type ? [{
@@ -3470,18 +3512,19 @@ const adapterOas = (0, _kubb_core.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,