@kubb/adapter-oas 5.0.0-beta.106 → 5.0.0-beta.108

package/README.md

@@ -45,29 +45,31 @@ import { defineConfig } from 'kubb'
 import { adapterOas } from '@kubb/adapter-oas'
 
 export default defineConfig({
-  input: {
-    path: './openapi.yaml',
-  },
+  input: './openapi.yaml',
   output: {
     path: './src/gen',
   },
-  adapters: [adapterOas()],
+  adapter: adapterOas(),
 })
 ```
 
+`input` accepts a file path, a URL, an inline JSON or YAML string, or a parsed spec object.
+
 ## API
 
 ### `adapterOas(options?)`
 
-Creates the OAS adapter instance. Pass it in the `adapters` array of `defineConfig`.
+Creates the OAS adapter instance. Pass it as `adapter` in `defineConfig`.
 
-### `mergeDocuments(documents)`
+### `adapterOasName`
 
-Merges multiple OpenAPI documents into a single document before parsing.
+The adapter's name, `'oas'`. Use it to identify this adapter in a Kubb config.
 
 ### Types
 
-All OpenAPI types (`Document`, `Operation`, `SchemaObject`, `HttpMethod`, etc.) are re-exported from this package.
+The package re-exports the OpenAPI types it works with: `ContentType`, `DiscriminatorObject`, `Document`,
+`MediaTypeObject`, `Operation`, `ReferenceObject`, `ResponseObject`, and `SchemaObject`. Its own option types are
+`AdapterOas`, `AdapterOasOptions`, and `AdapterOasResolvedOptions`.
 
 ## Supporting Kubb
 

package/dist/index.cjs

@@ -38,8 +38,8 @@ let _kubb_kit = require("@kubb/kit");
 const DEFAULT_PARSER_OPTIONS = {
 	dateType: "string",
 	integerType: "bigint",
-	unknownType: "any",
-	emptySchemaType: "any",
+	unknownType: "unknown",
+	emptySchemaType: "unknown",
 	enumSuffix: "enum"
 };
 /**
@@ -247,6 +247,20 @@ function pascalCase(text, { prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/errors.ts
+/**
+* Extracts a human-readable message from any thrown value.
+*
+* @example
+* ```ts
+* getErrorMessage(new Error('oops')) // 'oops'
+* getErrorMessage('plain string')    // 'plain string'
+* ```
+*/
+function getErrorMessage(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+//#endregion
 //#region ../../internals/utils/src/runtime.ts
 /**
 * Detects the JavaScript runtime executing the current process and exposes its name and version.
@@ -349,11 +363,50 @@ async function read(path) {
 //#endregion
 //#region src/load/source.ts
 const urlRegExp = /^https?:\/+/i;
+/**
+* Node reports every connection failure as `TypeError: fetch failed` and keeps the useful part
+* (`connect ECONNREFUSED 127.0.0.1:8000`) on `cause`, one level deeper again when a host resolves
+* to several addresses and the attempts collect into an `AggregateError`.
+*/
+function describeFetchFailure(error) {
+	if (error instanceof AggregateError && error.errors.length > 0) return describeFetchFailure(error.errors[0]);
+	if (error instanceof Error && error.cause instanceof Error) return describeFetchFailure(error.cause) || error.message;
+	return getErrorMessage(error);
+}
+function helpForStatus(status) {
+	if (status === 401 || status === 403) return "The server refused the request. Kubb sends no credentials, so serve the document without authentication or download it and set `input` to the local file.";
+	if (status === 404) return "Check the URL. Open it in a browser or with `curl` to confirm it serves the OpenAPI document.";
+	if (status >= 500) return "The server failed while serving the document. Check that it is healthy, then run Kubb again.";
+	return "Open the URL in a browser or with `curl` to see what the server returns, then point `input` at a URL that serves the OpenAPI document.";
+}
+async function fetchSource(url) {
+	try {
+		return await fetch(url);
+	} catch (error) {
+		throw new _kubb_core.Diagnostics.Error({
+			code: _kubb_core.Diagnostics.code.inputUnreachable,
+			severity: "error",
+			message: `Cannot reach ${url.href}: ${describeFetchFailure(error)}`,
+			help: "Check that the host is running and reachable from this machine. For a local server, start it and confirm the port matches the one in `input`.",
+			location: { kind: "config" },
+			cause: error instanceof Error ? error : void 0
+		});
+	}
+}
 async function readSource(sourcePath) {
 	if (urlRegExp.test(sourcePath)) {
 		const url = new URL(sourcePath);
-		const response = await fetch(url);
-		if (!response.ok) throw new Error(`Cannot fetch the OAS document at ${url.href} (HTTP ${response.status})`);
+		const response = await fetchSource(url);
+		if (!response.ok) {
+			const status = response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+			throw new _kubb_core.Diagnostics.Error({
+				code: _kubb_core.Diagnostics.code.inputRequestFailed,
+				severity: "error",
+				message: `The server at ${url.href} answered with HTTP ${status} instead of the OpenAPI document.`,
+				help: helpForStatus(response.status),
+				location: { kind: "config" }
+			});
+		}
 		return response.text();
 	}
 	return read(sourcePath);
@@ -369,7 +422,8 @@ async function resolveSource(sourcePath) {
 }
 /**
 * Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
-* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* URLs are skipped: a remote input reports `KUBB_INPUT_REQUEST_FAILED` or `KUBB_INPUT_UNREACHABLE`
+* from the request itself. A malformed but readable file is left for `parseDocument` to surface
 * its parse error instead.
 */
 async function assertInputExists(input) {
@@ -449,6 +503,24 @@ async function parseFromConfig(source) {
 	return parseDocument(resolved);
 }
 /**
+* Asserts the parsed input is an OpenAPI or Swagger document.
+*
+* {@link validateDocument} keeps spec violations non-fatal so imperfect but usable documents still
+* generate. That leniency also swallowed input that is not a document at all, which then produced
+* an empty build with a success exit code. A missing version field is the one failure that cannot
+* be a usable document, so it is fatal regardless of the `validate` option.
+*/
+function assertDocument(document) {
+	if (document && ("openapi" in document || "swagger" in document)) return;
+	throw new _kubb_core.Diagnostics.Error({
+		code: _kubb_core.Diagnostics.code.invalidDocument,
+		severity: "error",
+		message: "The resolved `input` is not an OpenAPI or Swagger document: it declares no `openapi` or `swagger` version.",
+		help: "Point `input` at a document that declares `openapi` or `swagger`. If you pass an object, pass the spec itself rather than a wrapper such as `{ path }` or `{ data }`.",
+		location: { kind: "config" }
+	});
+}
+/**
 * Validates an OpenAPI document using `@readme/openapi-parser` with colorized error output.
 *
 * @example
@@ -1623,9 +1695,9 @@ function convertObject({ schema, name, nullable, defaultValue, rawOptions, optio
 /**
 * Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
 */
-function convertTuple({ schema, name, nullable, defaultValue, rawOptions, parse }) {
+function convertTuple({ schema, name, nullable, defaultValue, rawOptions, options, parse }) {
 	const tupleItems = (schema.prefixItems ?? []).map((item) => parse({ schema: item }, rawOptions));
-	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? _kubb_ast.ast.factory.createSchema({ type: "any" }) : parse({ schema: schema.items }, rawOptions);
+	const rest = schema.items === false ? void 0 : !schema.items || schema.items === true ? _kubb_ast.ast.factory.createSchema({ type: options.unknownType }) : parse({ schema: schema.items }, rawOptions);
 	return createNode({
 		schema,
 		name,
@@ -2491,13 +2563,16 @@ const adapterOas = (0, _kubb_core.createAdapter)((options) => {
 		},
 		async validate(input, options) {
 			await assertInputExists(input);
-			await validateDocument(await parseDocument(input), options);
+			const document = await parseDocument(input);
+			assertDocument(document);
+			await validateDocument(document, options);
 		},
 		async parse(source) {
 			const cached = inputCache.get(source);
 			if (cached) return cached;
 			const promise = (async () => {
 				const document = await parseFromConfig(source);
+				assertDocument(document);
 				if (validate) await validateDocument(document);
 				parsedDocument = document;
 				const refs = createRefs(document);