@kubb/adapter-oas 5.14.4 → 5.14.6

package/dist/index.js

@@ -1,5 +1,6 @@
 import { defineExtension } from "@kubb/core";
 import { Diagnostics, ast, childName, enumPrimitive, enumPropName, extractRefName, macroDiscriminatorEnum, macroEnumName, macroSimplifyUnion, mergeAdjacentObjectsLazy } from "@kubb/kit";
+import { join } from "node:path";
 import { access, readFile } from "node:fs/promises";
 import { upgrade } from "@scalar/openapi-upgrader";
 import { bundle } from "api-ref-bundler";
@@ -20,7 +21,7 @@ var compatibility = {
 };
 //#endregion
 //#region package.json
-var version = "5.14.4";
+var version = "5.14.6";
 //#endregion
 //#region src/constants.ts
 /**
@@ -698,6 +699,30 @@ function inlinePathRefs(node, resolve, visiting = []) {
 	for (const [key, value] of Object.entries(node)) node[key] = inlinePathRefs(value, resolve, visiting);
 	return node;
 }
+const namedEntryKeys = /* @__PURE__ */ new Set([
+	"properties",
+	"patternProperties",
+	"headers",
+	"schemas",
+	"responses",
+	"parameters",
+	"requestBodies",
+	"examples",
+	"links",
+	"callbacks",
+	"securitySchemes",
+	"securityDefinitions",
+	"pathItems",
+	"definitions",
+	"$defs"
+]);
+/**
+* True when `path` runs through an `x-` vendor extension. Kubb never reads an extension, so a `$ref`
+* Kubb cannot read inside one cannot change the output.
+*/
+function isExtensionPath(path) {
+	return path.some((token, index) => String(token).startsWith("x-") && !namedEntryKeys.has(String(path[index - 1])));
+}
 /**
 * Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
 *
@@ -711,33 +736,55 @@ function inlinePathRefs(node, resolve, visiting = []) {
 * 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
+* `KUBB_REF_NOT_FOUND` at the key that holds it, as a warning when it sits inside an `x-` extension.
+*
 * @example Local file
 * `const document = await bundleDocument('./openapi.yaml')`
 *
 * @example Remote URL
 * `const document = await bundleDocument('https://example.com/openapi.yaml')`
 */
-async function bundleDocument(pathOrUrl) {
+async function bundleDocument(pathOrUrl, { document, sources = [] } = {}) {
 	const cache = /* @__PURE__ */ new Map();
+	const toKey = (sourcePath) => urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath;
 	const resolver = (sourcePath) => {
-		const key = urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath;
+		if (document && sourcePath === pathOrUrl) return Promise.resolve(document);
+		const key = toKey(sourcePath);
 		const cached = cache.get(key);
 		if (cached) return cached;
+		sources.push(key);
 		const result = resolveSource(sourcePath);
 		cache.set(key, result);
 		return result;
 	};
 	const root = await resolver(pathOrUrl);
 	if (typeof root === "object" && root !== null && !hasExternalRef(root)) return root;
-	return await bundle(pathOrUrl, resolver);
+	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;
+		const diagnostic = {
+			code: Diagnostics.code.refNotFound,
+			severity: isExtensionPath(path) ? "warning" : "error",
+			message: `Could not bundle an external \`$ref\`. ${message}.`,
+			help: "Check that the file or URL the `$ref` points at exists and is readable, or fix the `$ref`.",
+			...pointer && { location: {
+				kind: "schema",
+				pointer
+			} }
+		};
+		if (!Diagnostics.report(diagnostic) && diagnostic.severity === "error") throw new Diagnostics.Error(diagnostic);
+	} } });
 }
+const inlineInputName = "<inline input>";
 /**
 * Creates a `Document` from an `AdapterSource`.
 *
 * - `{ type: 'path' }` bundles an absolute file path (core resolves `input`) or remote URL via
 *   `api-ref-bundler`, hoisting external file schemas into named `components.schemas` entries so
 *   generators can emit named types and imports.
-* - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
+* - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object, then bundles its
+*   external `$ref`s from `root` when it has any. Each file or URL read lands in `sources`.
 *
 * Swagger 2.0 and OpenAPI 3.0 documents are up-converted to OpenAPI 3.1 via `@scalar/openapi-upgrader`.
 *
@@ -747,14 +794,20 @@ async function bundleDocument(pathOrUrl) {
 * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
 * ```
 */
-async function parseFromConfig(source) {
+async function parseFromConfig(source, sources = []) {
 	const raw = await (async () => {
-		if (source.type === "data") return typeof source.data === "string" ? parseYaml(source.data, {
-			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);
+		if (source.type === "data") {
+			const data = typeof source.data === "string" ? parseYaml(source.data, {
+				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), {
+				document: data,
+				sources
+			}) : data;
+		}
 		await assertInputExists(source.path);
-		return bundleDocument(source.path);
+		return bundleDocument(source.path, { sources });
 	})();
 	if (raw && typeof raw === "object") {
 		const document = raw;
@@ -2890,6 +2943,7 @@ const adapterOas = defineExtension({
 	}),
 	build({ validate, contentType, server, discriminator, enums, ...parserOptions }) {
 		let parsedDocument = null;
+		let sources = [];
 		const pendingValidations = [];
 		const inputCache = /* @__PURE__ */ new WeakMap();
 		/**
@@ -3023,6 +3077,9 @@ const adapterOas = defineExtension({
 			get document() {
 				return parsedDocument;
 			},
+			get sources() {
+				return sources;
+			},
 			locate,
 			async validate(input, options) {
 				const document = await parseFromConfig({
@@ -3038,9 +3095,14 @@ const adapterOas = defineExtension({
 			async parse(source, { signal } = {}) {
 				signal?.throwIfAborted();
 				const cached = inputCache.get(source);
-				if (cached) return cached;
+				if (cached) {
+					sources = cached.sources;
+					return cached.promise;
+				}
+				const read = [];
+				sources = read;
 				const promise = (async () => {
-					const document = await parseFromConfig(source);
+					const document = await parseFromConfig(source, read);
 					signal?.throwIfAborted();
 					assertDocument(document);
 					if (validate) pendingValidations.push(validateDocumentInWorker(document));
@@ -3060,7 +3122,10 @@ const adapterOas = defineExtension({
 						})
 					});
 				})();
-				inputCache.set(source, promise);
+				inputCache.set(source, {
+					promise,
+					sources: read
+				});
 				return promise.catch((error) => {
 					if (signal?.aborted) inputCache.delete(source);
 					throw error;