@kubb/core 5.0.0-beta.107 → 5.0.0-beta.109

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
-import { $ as PluginFactoryOptions, A as Kubb, At as DiagnosticDoc, B as Exclude, Bt as Hookable, C as KubbWarnContext, Ct as Reporter, D as CreateKubbOptions, Dt as createReporter, E as UserConfig, Et as UserReporter, F as NodeCache, Ft as PerformanceDiagnostic, G as KubbPluginSetupContext, H as Group, Ht as AdapterFactoryOptions, I as KubbDriver, It as ProblemCode, J as Output, K as KubbPluginStartContext, L as FileManagerHooks, Lt as ProblemDiagnostic, M as Generator, Mt as DiagnosticLocation, N as GeneratorContext, Nt as DiagnosticSeverity, O as GenerateOptions, Ot as logLevel, P as defineGenerator, Pt as Diagnostics, Q as Plugin, R as Parser, Rt as SerializedDiagnostic, S as KubbSuccessContext, St as GenerationResult, T as PostGenerateCommand, Tt as ReporterName, U as Include, Ut as AdapterSource, V as Filter, Vt as Adapter, W as KubbPluginEndContext, Wt as createAdapter, X as OutputOptions, Y as OutputMode, Z as Override, _ as KubbHookStartContext, _t as Renderer, a as KubbBuildEndContext, at as ResolveBannerFile, b as KubbLifecycleStartContext, bt as Storage, c as KubbErrorContext, ct as ResolveOptionsContext, d as KubbFilesProcessingStartContext, dt as ResolverDefault, et as PluginName, f as KubbFilesProcessingUpdateContext, ft as ResolverFile, g as KubbHookLineContext, gt as ResolverPathParams, h as KubbHookEndContext, ht as ResolverPatch, i as Input, it as ResolveBannerContext, j as createKubb, jt as DiagnosticKind, k as GenerateResult, kt as Diagnostic, l as KubbFileProcessingUpdate, lt as ResolvePathOptions, m as KubbGenerationStartContext, mt as ResolverFilePathParams, n as CLIOptions, nt as definePlugin, o as KubbBuildStartContext, ot as ResolveFileOptions, p as KubbGenerationEndContext, pt as ResolverFileParams, q as NormalizedPlugin, r as Config, rt as BannerMeta, s as KubbDiagnosticContext, st as ResolveImportsOptions, t as BuildOutput, tt as ResolvePluginOptions, u as KubbFilesProcessingEndContext, ut as Resolver, v as KubbHooks, vt as RendererFactory, w as PossibleConfig, wt as ReporterContext, x as KubbPluginsEndContext, xt as createStorage, y as KubbInfoContext, yt as createRenderer, z as defineParser, zt as UpdateDiagnostic } from "./types-Dtisidv5.js";
+import { $ as PluginFactoryOptions, A as Kubb, At as DiagnosticDoc, B as Exclude, Bt as Hookable, C as KubbWarnContext, Ct as Reporter, D as CreateKubbOptions, Dt as createReporter, E as UserConfig, Et as UserReporter, F as NodeCache, Ft as PerformanceDiagnostic, G as KubbPluginSetupContext, H as Group, Ht as AdapterFactoryOptions, I as KubbDriver, It as ProblemCode, J as Output, K as KubbPluginStartContext, L as FileManagerHooks, Lt as ProblemDiagnostic, M as Generator, Mt as DiagnosticLocation, N as GeneratorContext, Nt as DiagnosticSeverity, O as GenerateOptions, Ot as logLevel, P as defineGenerator, Pt as Diagnostics, Q as Plugin, R as Parser, Rt as SerializedDiagnostic, S as KubbSuccessContext, St as GenerationResult, T as PostGenerateCommand, Tt as ReporterName, U as Include, Ut as AdapterSource, V as Filter, Vt as Adapter, W as KubbPluginEndContext, Wt as createAdapter, X as OutputOptions, Y as OutputMode, Z as Override, _ as KubbHookStartContext, _t as Renderer, a as KubbBuildEndContext, at as ResolveBannerFile, b as KubbLifecycleStartContext, bt as Storage, c as KubbErrorContext, ct as ResolveOptionsContext, d as KubbFilesProcessingStartContext, dt as ResolverDefault, et as PluginName, f as KubbFilesProcessingUpdateContext, ft as ResolverFile, g as KubbHookLineContext, gt as ResolverPathParams, h as KubbHookEndContext, ht as ResolverPatch, i as Input, it as ResolveBannerContext, j as createKubb, jt as DiagnosticKind, k as GenerateResult, kt as Diagnostic, l as KubbFileProcessingUpdate, lt as ResolvePathOptions, m as KubbGenerationStartContext, mt as ResolverFilePathParams, n as CLIOptions, nt as definePlugin, o as KubbBuildStartContext, ot as ResolveFileOptions, p as KubbGenerationEndContext, pt as ResolverFileParams, q as NormalizedPlugin, r as Config, rt as BannerMeta, s as KubbDiagnosticContext, st as ResolveImportsOptions, t as BuildOutput, tt as ResolvePluginOptions, u as KubbFilesProcessingEndContext, ut as Resolver, v as KubbHooks, vt as RendererFactory, w as PossibleConfig, wt as ReporterContext, x as KubbPluginsEndContext, xt as createStorage, y as KubbInfoContext, yt as createRenderer, z as defineParser, zt as UpdateDiagnostic } from "./types-TqpVzVtY.js";
 //#region src/applyConfigDefaults.d.ts
 type ApplyConfigDefaultsOptions<TOutput> = {
   defaultAdapter: Adapter;
@@ -141,7 +141,8 @@ declare function getInputKind(input: NonNullable<Input>): InputKind;
  *
  * Writes are deduplicated and directory-safe:
  * - leading and trailing whitespace is trimmed before writing
- * - the write is skipped when the file content is already identical
+ * - the write is skipped when the file already holds that content, ignoring any trailing newline
+ *   a formatter left behind
  * - missing parent directories are created automatically
  * - Bun's native file API is used when running under Bun
  * - concurrent `writeItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller

package/dist/index.js

@@ -1,11 +1,13 @@
-import "./rolldown-runtime-C0LytTxp.js";
-import { a as clean, c as toPosixPath, d as getErrorMessage, f as toError, i as Hookable, l as write, n as createNodeCache, o as isPathInside, p as camelCase, r as FileManager, s as toFilePath, t as _usingCtx, u as BuildError } from "./usingCtx-D9_Ee6kn.js";
+import { t as __name } from "./rolldown-runtime-C0LytTxp.js";
+import { a as OPERATION_FILTER_TYPES, c as clean, d as toPosixPath, f as write, g as camelCase, h as toError, i as Hookable, l as isPathInside, m as getErrorMessage, n as createNodeCache, o as diagnosticCode, p as BuildError, r as FileManager, s as inParallel, t as _usingCtx, u as toFilePath } from "./usingCtx-njZUKKsY.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { stripVTControlCharacters, styleText } from "node:util";
-import { hash } from "node:crypto";
+import { createHash, hash } from "node:crypto";
 import { access, glob, readFile, rm } from "node:fs/promises";
 import path, { join, relative, resolve } from "node:path";
 import { ast, collectImportedRefNames, collectUsedSchemaNames, composeMacros, operationDef, schemaDef, transform } from "@kubb/ast";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
 import process$1 from "node:process";
 //#region src/createAdapter.ts
 /**
@@ -149,130 +151,11 @@ function randomCliColor(text) {
 	return styleText(color, text);
 }
 //#endregion
-//#region package.json
-var version = "5.0.0-beta.107";
-//#endregion
-//#region src/constants.ts
-/**
-* Plugin `include` filter types that select operations directly. When one of these is set
-* without a `schemaName` include, the generate phase pre-scans operations to compute the set
-* of schemas they reach, so unreachable schemas can be pruned for that plugin.
-*/
-const OPERATION_FILTER_TYPES = /* @__PURE__ */ new Set([
-	"tag",
-	"operationId",
-	"path",
-	"method",
-	"contentType"
-]);
-/**
-* Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
-* and stays stable so it can be referenced in tooling and (later) docs. Reference
-* these instead of inlining the string at a throw site.
-*/
-const diagnosticCode = {
-	/**
-	* Fallback for an unstructured error with no specific code.
-	*/
-	unknown: "KUBB_UNKNOWN",
-	/**
-	* The file or URL set as `input` could not be read.
-	*/
-	inputNotFound: "KUBB_INPUT_NOT_FOUND",
-	/**
-	* An adapter was configured without an `input`.
-	*/
-	inputRequired: "KUBB_INPUT_REQUIRED",
-	/**
-	* `input` uses the v4 `{ path }` / `{ data }` wrapper, which v5 reads as a parsed
-	* document instead of a pointer to one.
-	*/
-	legacyInput: "KUBB_LEGACY_INPUT",
-	/**
-	* The parsed `input` carries no `openapi` or `swagger` version, so it is not a
-	* document the adapter can read.
-	*/
-	invalidDocument: "KUBB_INVALID_DOCUMENT",
-	/**
-	* A `$ref` (or equivalent reference) could not be resolved in the source document.
-	*/
-	refNotFound: "KUBB_REF_NOT_FOUND",
-	/**
-	* A server variable value is not allowed by its `enum`.
-	*/
-	invalidServerVariable: "KUBB_INVALID_SERVER_VARIABLE",
-	/**
-	* A required plugin is missing from the config.
-	*/
-	pluginNotFound: "KUBB_PLUGIN_NOT_FOUND",
-	/**
-	* A plugin threw while generating.
-	*/
-	pluginFailed: "KUBB_PLUGIN_FAILED",
-	/**
-	* A plugin reported a non-fatal warning through `ctx.warn`.
-	*/
-	pluginWarning: "KUBB_PLUGIN_WARNING",
-	/**
-	* A plugin reported an informational message through `ctx.info`.
-	*/
-	pluginInfo: "KUBB_PLUGIN_INFO",
-	/**
-	* A schema uses a `format` Kubb does not map to a specific type. Reserved for
-	* adapters to emit as a `warning`.
-	*/
-	unsupportedFormat: "KUBB_UNSUPPORTED_FORMAT",
-	/**
-	* A referenced schema or operation is marked `deprecated`. Reserved for adapters
-	* to emit as an `info`.
-	*/
-	deprecated: "KUBB_DEPRECATED",
-	/**
-	* An adapter is required but the config has none. The build cannot read the input
-	* without one.
-	*/
-	adapterRequired: "KUBB_ADAPTER_REQUIRED",
-	/**
-	* A resolved output path escapes the output directory, which can stem from a path
-	* traversal in the spec or a misconfigured `group.name`.
-	*/
-	pathTraversal: "KUBB_PATH_TRAVERSAL",
-	/**
-	* `output.clean` is enabled but `output.path` resolves to the project root or a parent of it,
-	* so cleaning would delete kubb.config and every source file.
-	*/
-	cleanRoot: "KUBB_CLEAN_ROOT",
-	/**
-	* A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
-	*/
-	invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS",
-	/**
-	* A post-generate command (`output.postGenerate`) exited with a failure.
-	*/
-	postGenerateFailed: "KUBB_POST_GENERATE_FAILED",
-	/**
-	* The formatter pass over the generated files failed.
-	*/
-	formatFailed: "KUBB_FORMAT_FAILED",
-	/**
-	* The linter pass over the generated files failed.
-	*/
-	lintFailed: "KUBB_LINT_FAILED",
-	/**
-	* Not a failure. Carries a plugin's elapsed time, summed into the run total.
-	*/
-	performance: "KUBB_PERFORMANCE",
-	/**
-	* Not a failure. A newer Kubb version is available on npm.
-	*/
-	updateAvailable: "KUBB_UPDATE_AVAILABLE"
-};
-//#endregion
 //#region src/Diagnostics.ts
 /**
 * Docs major version, derived from the package version so the link tracks the published major.
 */
-const docsMajor = version.split(".")[0] ?? "5";
+const docsMajor = "5.0.0-beta.109".split(".")[0] ?? "5";
 /**
 * Builds a type guard that narrows a {@link Diagnostic} to the variant for `kind`. A diagnostic
 * with no `kind` is treated as a `problem`.
@@ -332,8 +215,18 @@ const diagnosticCatalog = {
 	},
 	[diagnosticCode.inputNotFound]: {
 		title: "Input not found",
-		cause: "The file or URL set as `input` (or passed as `kubb generate PATH`) could not be read.",
-		fix: "Check that the path or URL exists and is readable, then set it as `input` or pass it on the CLI."
+		cause: "The file set as `input` (or passed as `kubb generate PATH`) could not be read. A URL reports `KUBB_INPUT_REQUEST_FAILED` or `KUBB_INPUT_UNREACHABLE` instead.",
+		fix: "Check that the path exists and is readable, then set it as `input` or pass it on the CLI."
+	},
+	[diagnosticCode.inputRequestFailed]: {
+		title: "Input request failed",
+		cause: "A URL set as `input` (or reached through a `$ref`) answered with a 4xx or 5xx status instead of the document.",
+		fix: "Open the URL to see what the server returns. A 401 or 403 needs credentials Kubb does not send, so download the document and point `input` at the local file. A 404 means the path is wrong, and a 5xx means the server itself failed."
+	},
+	[diagnosticCode.inputUnreachable]: {
+		title: "Input unreachable",
+		cause: "A URL set as `input` (or reached through a `$ref`) never answered, so the request failed before a status came back. A refused connection, an unknown host, an expired certificate, and a timeout all land here.",
+		fix: "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`."
 	},
 	[diagnosticCode.inputRequired]: {
 		title: "Input required",
@@ -1511,22 +1404,25 @@ var KubbDriver = class {
 	async run() {
 		const { hooks, config, fileManager } = this;
 		const diagnostics = [];
-		const updateBuffer = [];
 		const parsersMap = /* @__PURE__ */ new Map();
 		for (const parser of config.parsers) if (parser.extNames) for (const ext of parser.extNames) parsersMap.set(ext, parser);
+		const updateBuffer = [];
 		const unhookWrites = fileManager.hooks.addHooks({
 			start: async (files) => {
 				await hooks.callHook("kubb:files:processing:start", { files });
 			},
-			update: (item) => {
-				updateBuffer.push(item);
+			update: ({ file, processed, total, percentage }) => {
+				updateBuffer.push({
+					file,
+					processed,
+					total,
+					percentage,
+					config
+				});
 			},
 			end: async (files) => {
 				updateBuffer.sort((a, b) => a.processed - b.processed);
-				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer.map((item) => ({
-					...item,
-					config
-				})) });
+				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer });
 				updateBuffer.length = 0;
 				await hooks.callHook("kubb:files:processing:end", { files });
 			}
@@ -1593,7 +1489,8 @@ var KubbDriver = class {
 				await hooks.callHook("kubb:plugins:end", this.#withFiles({ config }));
 				await fileManager.write(fileManager.files, {
 					storage: config.storage,
-					parsers: parsersMap
+					parsers: parsersMap,
+					manifest: this.options.manifest
 				});
 				await hooks.callHook("kubb:build:end", {
 					files: this.fileManager.files,
@@ -1954,6 +1851,73 @@ var KubbDriver = class {
 	}
 };
 //#endregion
+//#region src/outputManifest.ts
+/**
+* Bumped when the stored shape changes, so an older cache is discarded instead of misread.
+*/
+const VERSION = 1;
+function hash$1(value) {
+	return createHash("sha256").update(value).digest("hex");
+}
+__name(hash$1, "hash");
+const MANIFEST_KEY = "output-manifest.json";
+async function loadEntries({ cache }) {
+	try {
+		const stored = await cache.readItem(MANIFEST_KEY);
+		if (stored === null) return {};
+		const data = JSON.parse(stored);
+		if (data.version !== VERSION) return {};
+		if (typeof data.entries !== "object" || data.entries === null || Array.isArray(data.entries)) return {};
+		return data.entries;
+	} catch {
+		return {};
+	}
+}
+/**
+* Loads the stored manifest, starting empty when it is missing, unreadable, or from an older
+* version. `storage` holds the generated files, `cache` holds the manifest itself.
+*
+* @example
+* ```ts
+* const manifest = await createOutputManifest({ storage: config.storage, cache: cacheStorage({ root: config.root }) })
+* ```
+*/
+async function createOutputManifest({ storage, cache }) {
+	const entries = await loadEntries({ cache });
+	const tracked = /* @__PURE__ */ new Map();
+	return {
+		isUpToDate({ key, source, disk }) {
+			const entry = entries[key];
+			if (!entry) return false;
+			return entry.source === hash$1(source) && entry.output === hash$1(disk);
+		},
+		track({ key, source }) {
+			tracked.set(key, hash$1(source));
+		},
+		async commit() {
+			try {
+				const next = { ...entries };
+				await inParallel({
+					items: [...tracked],
+					limit: 50,
+					run: async ([key, source]) => {
+						const stored = await storage.readItem(key);
+						if (stored === null) return;
+						next[key] = {
+							source,
+							output: hash$1(stored)
+						};
+					}
+				});
+				await cache.writeItem(MANIFEST_KEY, JSON.stringify({
+					version: VERSION,
+					entries: next
+				}));
+			} catch {}
+		}
+	};
+}
+//#endregion
 //#region src/createStorage.ts
 /**
 * Defines a custom storage backend. The builder receives user options and
@@ -2030,7 +1994,8 @@ function createLimiter(concurrency) {
 *
 * Writes are deduplicated and directory-safe:
 * - leading and trailing whitespace is trimmed before writing
-* - the write is skipped when the file content is already identical
+* - the write is skipped when the file already holds that content, ignoring any trailing newline
+*   a formatter left behind
 * - missing parent directories are created automatically
 * - Bun's native file API is used when running under Bun
 * - concurrent `writeItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller
@@ -2091,6 +2056,60 @@ const fsStorage = createStorage(() => {
 	};
 });
 //#endregion
+//#region src/storages/cacheStorage.ts
+/**
+* Directory Kubb keeps build caches in. A project with a `node_modules` gets
+* `node_modules/.cache/kubb`, the convention babel and eslint already use, so the cache stays out
+* of version control. Without one it falls back to the OS temp directory, keyed by root so two
+* projects sharing that directory keep their own cache.
+*
+* @example Inside a project
+* `resolveCacheDir('/project') // '/project/node_modules/.cache/kubb'`
+*/
+function resolveCacheDir(root) {
+	const nodeModules = join(root, "node_modules");
+	if (existsSync(nodeModules)) return join(nodeModules, ".cache", "kubb");
+	return join(tmpdir(), "kubb", createHash("sha256").update(root).digest("hex").slice(0, 16));
+}
+/**
+* Filesystem storage for build caches rather than generated code. Keys are plain names resolved
+* inside {@link resolveCacheDir}, so a caller stores `'x.json'` without knowing where the cache
+* lives. Kept apart from the configured output storage, which may not be a local disk at all.
+*
+* @example
+* ```ts
+* const cache = cacheStorage({ root: config.root })
+* await cache.writeItem('output-manifest.json', JSON.stringify(entries))
+* ```
+*/
+const cacheStorage = createStorage(({ root = process.cwd() }) => {
+	const dir = resolveCacheDir(root);
+	const storage = fsStorage();
+	const toPath = (key) => join(dir, key);
+	return {
+		name: "cache",
+		async existsItem(key) {
+			return storage.existsItem(toPath(key));
+		},
+		async readItem(key) {
+			return storage.readItem(toPath(key));
+		},
+		async writeItem(key, value) {
+			return storage.writeItem(toPath(key), value);
+		},
+		async removeItem(key) {
+			return storage.removeItem(toPath(key));
+		},
+		async readKeys(base) {
+			return storage.readKeys(base ? toPath(base) : dir);
+		},
+		async empty(base) {
+			if (!base) return;
+			return storage.empty(toPath(base));
+		}
+	};
+});
+//#endregion
 //#region src/createKubb.ts
 function resolveConfig(userConfig) {
 	return {
@@ -2109,6 +2128,13 @@ function resolveConfig(userConfig) {
 	};
 }
 /**
+* Whether anything runs over the output directory after the files are written. Only then can the
+* bytes on disk stop matching what Kubb wrote, which is what the manifest exists to track.
+*/
+function hasOutputPasses(output) {
+	return Boolean(output.format || output.lint || output.postGenerate?.length);
+}
+/**
 * Kubb code-generation instance bound to a single config entry. Resolves the user
 * config in the constructor, so `config` is available right away, and shares `hooks`,
 * `storage`, and `driver` across the `setup → build` lifecycle.
@@ -2130,6 +2156,7 @@ var Kubb = class {
 	config;
 	#driver = null;
 	#storage = null;
+	#manifest = null;
 	constructor(userConfig, options = {}) {
 		this.config = resolveConfig(userConfig);
 		this.hooks = options.hooks ?? new Hookable();
@@ -2147,7 +2174,14 @@ var Kubb = class {
 	*/
 	async setup() {
 		const config = this.config;
-		const driver = new KubbDriver(config, { hooks: this.hooks });
+		const manifest = hasOutputPasses(config.output) ? await createOutputManifest({
+			storage: config.storage,
+			cache: cacheStorage({ root: config.root })
+		}) : void 0;
+		const driver = new KubbDriver(config, {
+			hooks: this.hooks,
+			manifest
+		});
 		this.hooks.setMaxListeners(Math.max(10, config.plugins.length * 4));
 		if (config.output.clean) {
 			const cleanPath = resolve(config.root, config.output.path);
@@ -2163,6 +2197,7 @@ var Kubb = class {
 		await driver.setup();
 		this.#driver = driver;
 		this.#storage = config.storage;
+		this.#manifest = manifest ?? null;
 	}
 	/**
 	* Runs the full pipeline and throws on any plugin error.
@@ -2250,6 +2285,7 @@ var Kubb = class {
 		}) : [];
 		const finalDiagnostics = [...diagnostics, ...outputDiagnostics];
 		const failed = Diagnostics.hasError(outputDiagnostics);
+		if (!failed) await this.#manifest?.commit();
 		await hooks.callHook("kubb:generation:end", {
 			config,
 			storage,