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

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_usingCtx = require("./usingCtx-lve4tKsy.cjs");
+const require_usingCtx = require("./usingCtx-BdYw7ICK.cjs");
 let node_async_hooks = require("node:async_hooks");
 let node_util = require("node:util");
 let node_crypto = require("node:crypto");
@@ -7,6 +7,8 @@ let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = require_usingCtx.__toESM(node_path, 1);
 let _kubb_ast = require("@kubb/ast");
+let node_fs = require("node:fs");
+let node_os = require("node:os");
 let node_process = require("node:process");
 node_process = require_usingCtx.__toESM(node_process, 1);
 //#region src/createAdapter.ts
@@ -151,130 +153,11 @@ function randomCliColor(text) {
 	return (0, node_util.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`.
@@ -327,112 +210,122 @@ const severityStyle = {
 * and `Diagnostics.docsUrl` for the matching kubb.dev page.
 */
 const diagnosticCatalog = {
-	[diagnosticCode.unknown]: {
+	[require_usingCtx.diagnosticCode.unknown]: {
 		title: "Unknown error",
 		cause: "An error was thrown without a stable Kubb code, so it is reported as-is.",
 		fix: "Read the underlying message and stack. If it comes from a plugin or adapter, check its configuration; otherwise report it as a possible Kubb bug."
 	},
-	[diagnosticCode.inputNotFound]: {
+	[require_usingCtx.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."
+	},
+	[require_usingCtx.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."
+	},
+	[require_usingCtx.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]: {
+	[require_usingCtx.diagnosticCode.inputRequired]: {
 		title: "Input required",
 		cause: "An adapter is configured but no `input` was provided.",
 		fix: "Set `input` to a file path, a URL, an inline spec (JSON/YAML string), or a parsed object in your Kubb config."
 	},
-	[diagnosticCode.legacyInput]: {
+	[require_usingCtx.diagnosticCode.legacyInput]: {
 		title: "Legacy input shape",
 		cause: "`input` is a `{ path }` or `{ data }` wrapper, which v4 used to point at a document and v5 reads as the document itself.",
 		fix: "Unwrap it: `input: { path: \"./petStore.yaml\" }` becomes `input: \"./petStore.yaml\"`, and `input: { data: spec }` becomes `input: spec`."
 	},
-	[diagnosticCode.invalidDocument]: {
+	[require_usingCtx.diagnosticCode.invalidDocument]: {
 		title: "Invalid document",
 		cause: "The parsed `input` has no `openapi` or `swagger` version field, so it is not an OpenAPI or Swagger document.",
 		fix: "Point `input` at a document that declares `openapi` or `swagger`, and check that a passed object is the spec itself rather than a wrapper around it."
 	},
-	[diagnosticCode.refNotFound]: {
+	[require_usingCtx.diagnosticCode.refNotFound]: {
 		title: "Reference not found",
 		cause: "A `$ref` could not be resolved in the source document.",
 		fix: "Add the missing definition (for example under `components.schemas`) or fix the `$ref`. Run `kubb validate` to check the spec."
 	},
-	[diagnosticCode.invalidServerVariable]: {
+	[require_usingCtx.diagnosticCode.invalidServerVariable]: {
 		title: "Invalid server variable",
 		cause: "A server variable value is not allowed by its `enum`.",
 		fix: "Use one of the values listed in the server variable `enum`, or update the spec."
 	},
-	[diagnosticCode.pluginNotFound]: {
+	[require_usingCtx.diagnosticCode.pluginNotFound]: {
 		title: "Plugin not found",
 		cause: "A plugin that another plugin depends on is missing from the config.",
 		fix: "Add the required plugin to the `plugins` array in kubb.config.ts, or remove the dependency on it."
 	},
-	[diagnosticCode.pluginFailed]: {
+	[require_usingCtx.diagnosticCode.pluginFailed]: {
 		title: "Plugin failed",
 		cause: "A plugin threw while generating, or reported an error through `ctx.error`.",
 		fix: "Read the underlying error and check the plugin options and the schema or operation it failed on."
 	},
-	[diagnosticCode.pluginWarning]: {
+	[require_usingCtx.diagnosticCode.pluginWarning]: {
 		title: "Plugin warning",
 		cause: "A plugin reported a non-fatal warning through `ctx.warn`.",
 		fix: "Review the message. It does not fail the build; adjust the plugin options or input if the warning is unwanted."
 	},
-	[diagnosticCode.pluginInfo]: {
+	[require_usingCtx.diagnosticCode.pluginInfo]: {
 		title: "Plugin info",
 		cause: "A plugin reported an informational message through `ctx.info`.",
 		fix: "Informational only. No action is required."
 	},
-	[diagnosticCode.unsupportedFormat]: {
+	[require_usingCtx.diagnosticCode.unsupportedFormat]: {
 		title: "Unsupported format",
 		cause: "A schema uses a `format` Kubb does not map to a specific type, so it falls back to the base type.",
 		fix: "Use a format Kubb supports, or handle the custom format with a parser or plugin."
 	},
-	[diagnosticCode.deprecated]: {
+	[require_usingCtx.diagnosticCode.deprecated]: {
 		title: "Deprecated",
 		cause: "A referenced schema or operation is marked `deprecated`.",
 		fix: "Migrate off the deprecated definition if the warning is unwanted."
 	},
-	[diagnosticCode.adapterRequired]: {
+	[require_usingCtx.diagnosticCode.adapterRequired]: {
 		title: "Adapter required",
 		cause: "An action needs an adapter but none is configured.",
 		fix: "Set `adapter` in kubb.config.ts, for example `adapterOas()`."
 	},
-	[diagnosticCode.pathTraversal]: {
+	[require_usingCtx.diagnosticCode.pathTraversal]: {
 		title: "Path traversal",
 		cause: "A resolved output path escaped the output directory, which can stem from a path traversal in the spec or a misconfigured `group.name`.",
 		fix: "Keep generated paths within the output directory. Review the `group.name` function and the names coming from the spec."
 	},
-	[diagnosticCode.cleanRoot]: {
+	[require_usingCtx.diagnosticCode.cleanRoot]: {
 		title: "Clean targets the project root",
 		cause: "`output.clean` is enabled and `output.path` resolves to the project root or a parent of it, so cleaning would delete `kubb.config` and every source file.",
 		fix: "Point `output.path` at a subdirectory such as `./src/gen` so clean only removes generated code, or disable `output.clean`."
 	},
-	[diagnosticCode.invalidPluginOptions]: {
+	[require_usingCtx.diagnosticCode.invalidPluginOptions]: {
 		title: "Invalid plugin options",
 		cause: "A plugin was configured with options that cannot be honored, for example `output.mode: 'file'` paired with a `group` option.",
 		fix: "Fix the plugin options. A single-file output has nothing to group, so remove the `group` option or use `output.mode: 'directory'`."
 	},
-	[diagnosticCode.postGenerateFailed]: {
+	[require_usingCtx.diagnosticCode.postGenerateFailed]: {
 		title: "Post-generate command failed",
 		cause: "A post-generate command (`output.postGenerate`) exited with a non-zero status.",
 		fix: "Check the command is installed and correct, and run it manually to see the error."
 	},
-	[diagnosticCode.formatFailed]: {
+	[require_usingCtx.diagnosticCode.formatFailed]: {
 		title: "Format failed",
 		cause: "The formatter pass over the generated files failed.",
 		fix: "Check the formatter (oxfmt, biome, or prettier) is installed and its config is valid, then run it manually on the output."
 	},
-	[diagnosticCode.lintFailed]: {
+	[require_usingCtx.diagnosticCode.lintFailed]: {
 		title: "Lint failed",
 		cause: "The linter pass over the generated files failed.",
 		fix: "Check the linter (oxlint, biome, or eslint) is installed and its config is valid, then run it manually on the output."
 	},
-	[diagnosticCode.performance]: {
+	[require_usingCtx.diagnosticCode.performance]: {
 		title: "Performance",
 		cause: "Not a failure. Records a plugin’s elapsed time, summed into the run total.",
 		fix: "No action. This is an informational metric."
 	},
-	[diagnosticCode.updateAvailable]: {
+	[require_usingCtx.diagnosticCode.updateAvailable]: {
 		title: "Update available",
 		cause: "A newer Kubb version is published on npm than the one running.",
 		fix: "Update the `@kubb/*` packages, for example `npm install -g @kubb/cli`, to get the latest fixes."
@@ -452,7 +345,7 @@ var Diagnostics = class Diagnostics {
 	/**
 	* The diagnostic code catalog, exposed as `Diagnostics.code` (e.g. `Diagnostics.code.refNotFound`).
 	*/
-	static code = diagnosticCode;
+	static code = require_usingCtx.diagnosticCode;
 	/**
 	* Type guard for a build {@link ProblemDiagnostic}.
 	*/
@@ -533,7 +426,7 @@ var Diagnostics = class Diagnostics {
 			current = current.cause;
 		}
 		return {
-			code: diagnosticCode.unknown,
+			code: require_usingCtx.diagnosticCode.unknown,
 			severity: "error",
 			message: root ? root.message : require_usingCtx.getErrorMessage(error),
 			cause: root
@@ -545,7 +438,7 @@ var Diagnostics = class Diagnostics {
 	static performance({ plugin, duration }) {
 		return {
 			kind: "performance",
-			code: diagnosticCode.performance,
+			code: require_usingCtx.diagnosticCode.performance,
 			severity: "info",
 			message: `${plugin} generated in ${Math.round(duration)}ms`,
 			plugin,
@@ -558,7 +451,7 @@ var Diagnostics = class Diagnostics {
 	static update({ currentVersion, latestVersion }) {
 		return {
 			kind: "update",
-			code: diagnosticCode.updateAvailable,
+			code: require_usingCtx.diagnosticCode.updateAvailable,
 			severity: "info",
 			message: `Update available: v${currentVersion} → v${latestVersion}. Run \`npm install -g @kubb/cli\` to update.`,
 			currentVersion,
@@ -651,7 +544,7 @@ var Diagnostics = class Diagnostics {
 			...problem?.location ? { location: problem.location } : {},
 			...problem?.help ? { help: problem.help } : {},
 			...problem?.plugin ? { plugin: problem.plugin } : {},
-			...diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
+			...diagnostic.code === require_usingCtx.diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
 		};
 	}
 	/**
@@ -671,7 +564,7 @@ var Diagnostics = class Diagnostics {
 		const details = [];
 		if (problem?.location && "pointer" in problem.location) details.push(`  ${(0, node_util.styleText)("dim", "at:")} ${(0, node_util.styleText)("cyan", problem.location.pointer)}`);
 		if (problem?.help) details.push(`  ${(0, node_util.styleText)("cyan", "fix:")} ${problem.help}`);
-		if (code !== diagnosticCode.unknown) details.push(`  ${(0, node_util.styleText)("dim", "see:")} ${(0, node_util.styleText)("cyan", Diagnostics.docsUrl(code))}`);
+		if (code !== require_usingCtx.diagnosticCode.unknown) details.push(`  ${(0, node_util.styleText)("dim", "see:")} ${(0, node_util.styleText)("cyan", Diagnostics.docsUrl(code))}`);
 		return {
 			headline,
 			details
@@ -696,7 +589,7 @@ var Diagnostics = class Diagnostics {
 function normalizeOutput({ output, group, pluginName }) {
 	const mode = output.mode ?? "file";
 	if (mode === "file" && group) throw new Diagnostics.Error({
-		code: diagnosticCode.invalidPluginOptions,
+		code: require_usingCtx.diagnosticCode.invalidPluginOptions,
 		severity: "error",
 		message: `Plugin "${pluginName}" sets \`output.mode: 'file'\` but also configures a \`group\` option.`,
 		help: "A single-file output has nothing to group. Remove the `group` option, or use `output.mode: 'directory'` to organize files into subdirectories.",
@@ -1513,22 +1406,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 });
 			}
@@ -1595,7 +1491,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,
@@ -1674,7 +1571,7 @@ var KubbDriver = class {
 		const allowedSchemaNamesByPlugin = /* @__PURE__ */ new Map();
 		for (const { plugin } of entries) {
 			const { exclude, include, override } = plugin.options;
-			if (!((include?.some(({ type }) => OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === "schemaName") ?? false))) continue;
+			if (!((include?.some(({ type }) => require_usingCtx.OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === "schemaName") ?? false))) continue;
 			const resolver = this.getResolver(plugin.name);
 			const includedOps = operations.filter((operation) => resolver.default.options(operation, {
 				options: plugin.options,
@@ -1956,6 +1853,72 @@ 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(value) {
+	return (0, node_crypto.createHash)("sha256").update(value).digest("hex");
+}
+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(source) && entry.output === hash(disk);
+		},
+		track({ key, source }) {
+			tracked.set(key, hash(source));
+		},
+		async commit() {
+			try {
+				const next = { ...entries };
+				await require_usingCtx.inParallel({
+					items: [...tracked],
+					limit: 50,
+					run: async ([key, source]) => {
+						const stored = await storage.readItem(key);
+						if (stored === null) return;
+						next[key] = {
+							source,
+							output: hash(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
@@ -2032,7 +1995,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
@@ -2093,6 +2057,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 = (0, node_path.join)(root, "node_modules");
+	if ((0, node_fs.existsSync)(nodeModules)) return (0, node_path.join)(nodeModules, ".cache", "kubb");
+	return (0, node_path.join)((0, node_os.tmpdir)(), "kubb", (0, node_crypto.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) => (0, node_path.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 {
@@ -2111,6 +2129,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.
@@ -2132,6 +2157,7 @@ var Kubb = class {
 	config;
 	#driver = null;
 	#storage = null;
+	#manifest = null;
 	constructor(userConfig, options = {}) {
 		this.config = resolveConfig(userConfig);
 		this.hooks = options.hooks ?? new require_usingCtx.Hookable();
@@ -2149,7 +2175,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 = (0, node_path.resolve)(config.root, config.output.path);
@@ -2165,6 +2198,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.
@@ -2252,6 +2286,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,