@kubb/adapter-oas 5.14.4 → 5.14.6

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let _kubb_core = require("@kubb/core");
 let _kubb_kit = require("@kubb/kit");
+let node_path = require("node:path");
 let node_fs_promises = require("node:fs/promises");
 let _scalar_openapi_upgrader = require("@scalar/openapi-upgrader");
 let api_ref_bundler = require("api-ref-bundler");
@@ -36,7 +37,7 @@ var compatibility = {
 };
 //#endregion
 //#region package.json
-var version = "5.14.4";
+var version = "5.14.6";
 //#endregion
 //#region src/constants.ts
 /**
@@ -714,6 +715,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`.
 *
@@ -727,33 +752,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 (0, api_ref_bundler.bundle)(pathOrUrl, resolver);
+	return await (0, api_ref_bundler.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: _kubb_kit.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 (!_kubb_kit.Diagnostics.report(diagnostic) && diagnostic.severity === "error") throw new _kubb_kit.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`.
 *
@@ -763,14 +810,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((0, node_path.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;
@@ -2905,6 +2958,7 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 	}),
 	build({ validate, contentType, server, discriminator, enums, ...parserOptions }) {
 		let parsedDocument = null;
+		let sources = [];
 		const pendingValidations = [];
 		const inputCache = /* @__PURE__ */ new WeakMap();
 		/**
@@ -3038,6 +3092,9 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 			get document() {
 				return parsedDocument;
 			},
+			get sources() {
+				return sources;
+			},
 			locate,
 			async validate(input, options) {
 				const document = await parseFromConfig({
@@ -3053,9 +3110,14 @@ const adapterOas = (0, _kubb_core.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));
@@ -3075,7 +3137,10 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 						})
 					});
 				})();
-				inputCache.set(source, promise);
+				inputCache.set(source, {
+					promise,
+					sources: read
+				});
 				return promise.catch((error) => {
 					if (signal?.aborted) inputCache.delete(source);
 					throw error;