@kubb/core 5.0.0-beta.98 → 5.0.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_usingCtx = require("./usingCtx-CZyLSqds.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
@@ -147,163 +149,15 @@ const randomColors = [
 function randomCliColor(text) {
 	if (!text) return "";
 	const index = (0, node_crypto.hash)("sha256", text, "buffer").readUInt32BE(0) % randomColors.length;
-	return (0, node_util.styleText)(randomColors[index] ?? "white", text);
+	const color = randomColors[index] ?? "white";
+	return (0, node_util.styleText)(color, text);
 }
 //#endregion
-//#region ../../internals/utils/src/promise.ts
-/**
-* Wraps `factory` with a keyed cache backed by the provided store.
-*
-* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
-* collected) or a `Map` for primitive keys. For multi-argument functions,
-* nest two `memoize` calls — the outer keyed by the first argument, the
-* inner (created once per outer miss) keyed by the second.
-*
-* Because the cache is owned by the caller, it can be shared, inspected, or
-* cleared independently of the memoized function.
-*
-* @example Single WeakMap key
-* ```ts
-* const cache = new WeakMap<SchemaNode, Set<string>>()
-* const getRefs = memoize(cache, (node) => collectRefs(node))
-* ```
-*
-* @example Single Map key (primitive)
-* ```ts
-* const cache = new Map<string, Resolver>()
-* const getResolver = memoize(cache, (name) => buildResolver(name))
-* ```
-*
-* @example Two-level (object + primitive)
-* ```ts
-* const outer = new WeakMap<Params[], Map<string, Params[]>>()
-* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
-* fn(params)('camelcase')
-* ```
-*/
-function memoize(store, factory) {
-	return (key) => {
-		if (store.has(key)) return store.get(key);
-		const value = factory(key);
-		store.set(key, value);
-		return value;
-	};
-}
-//#endregion
-//#region package.json
-var version = "5.0.0-beta.98";
-//#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",
-	/**
-	* 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".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`.
@@ -356,102 +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."
 	},
-	[diagnosticCode.inputRequired]: {
+	[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`."
+	},
+	[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.refNotFound]: {
+	[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`."
+	},
+	[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."
+	},
+	[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."
@@ -471,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}.
 	*/
@@ -552,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
@@ -564,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,
@@ -577,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,
@@ -670,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) }
 		};
 	}
 	/**
@@ -690,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
@@ -711,14 +585,18 @@ var Diagnostics = class Diagnostics {
 * Merges the `output.mode` default into the output config and validates the combination.
 * Throws `KUBB_INVALID_PLUGIN_OPTIONS` when `mode: 'file'` is paired with a `group` option,
 * since a single-file output has nothing to group.
+*
+* An omitted `mode` follows the shape of `path`: an extension means a single file, anything
+* else is a directory. Plugin defaults such as `path: 'types'` name a directory, so they
+* generate without the caller spelling out `mode`.
 */
 function normalizeOutput({ output, group, pluginName }) {
-	const mode = output.mode ?? "directory";
+	const mode = output.mode ?? (node_path.default.extname(output.path) ? "file" : "directory");
 	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.",
+		message: `Plugin "${pluginName}" resolves \`output.mode\` to 'file' but also configures a \`group\` option.`,
+		help: "A single-file output has nothing to group. Remove the `group` option, give `output.path` an extensionless directory name, or set `output.mode: 'directory'` explicitly.",
 		location: { kind: "config" },
 		plugin: pluginName
 	});
@@ -769,6 +647,23 @@ function getInputKind(input) {
 	return "file";
 }
 /**
+* The v4 `input` wrapper keys. v4 typed `input` as `{ path }` or `{ data }`; v5 takes the value
+* directly, so the wrapper now matches the "already-parsed document" branch and silently yields
+* an empty build.
+*/
+const legacyInputKeys = ["path", "data"];
+/**
+* Detects the v4 `{ path }` / `{ data }` wrapper so it fails loudly instead of being read as a
+* document. A real spec always carries more than these keys, so an object whose keys are drawn
+* only from them is the old shape rather than a document that happens to have a `path` property.
+*/
+function isLegacyInput(input) {
+	if (Array.isArray(input)) return input.some(isLegacyInput);
+	if (typeof input !== "object" || input === null) return false;
+	const keys = Object.keys(input);
+	return keys.length > 0 && keys.every((key) => legacyInputKeys.includes(key));
+}
+/**
 * Normalizes `config.input` into an `AdapterSource` the adapter can parse.
 *
 * A parsed object and inline content become `{ type: 'data' }`; a URL is kept verbatim and a
@@ -776,6 +671,13 @@ function getInputKind(input) {
 */
 function inputToAdapterSource(config) {
 	const input = config.input;
+	if (input && isLegacyInput(input)) throw new Diagnostics.Error({
+		code: Diagnostics.code.legacyInput,
+		severity: "error",
+		message: "The `input` option uses the v4 `{ path }` / `{ data }` wrapper.",
+		help: "Unwrap it: `input: { path: \"./petStore.yaml\" }` becomes `input: \"./petStore.yaml\"`, and `input: { data: spec }` becomes `input: spec`.",
+		location: { kind: "config" }
+	});
 	if (!input) throw new Diagnostics.Error({
 		code: Diagnostics.code.inputRequired,
 		severity: "error",
@@ -887,28 +789,24 @@ var Resolver = class Resolver {
 	* schemas (`targetName`) import the emitted name. Names and paths go through the top-level
 	* `name` and `file`, so import entries follow the plugin's conventions, and a per-call
 	* `name` override wins over both.
+	*
+	* The subtree scan runs through `collectImportedRefNames`, which memoizes by node identity, so a
+	* schema shared across the ts, zod, and faker plugins is walked once and every plugin's resolver
+	* reads the same ref set instead of re-scanning it per plugin.
 	*/
 	imports(options) {
 		const { node, root, output, group, extname = ".ts", name } = options;
 		const resolveName = name ?? ((schemaName) => this.name(schemaName));
-		const seen = /* @__PURE__ */ new Set();
-		return (0, _kubb_ast.collect)(node, { schema: (schemaNode) => {
-			const schemaRef = (0, _kubb_ast.narrowSchema)(schemaNode, "ref");
-			if (!schemaRef?.ref) return null;
-			const schemaName = (0, _kubb_ast.resolveRefName)(schemaRef);
-			if (!schemaName || seen.has(schemaName)) return null;
-			seen.add(schemaName);
-			return _kubb_ast.ast.factory.createImport({
-				name: [resolveName(schemaName)],
-				path: this.file({
-					name: schemaName,
-					extname,
-					root,
-					output,
-					group
-				}).path
-			});
-		} });
+		return (0, _kubb_ast.collectImportedRefNames)(node).map((schemaName) => _kubb_ast.ast.factory.createImport({
+			name: [resolveName(schemaName)],
+			path: this.file({
+				name: schemaName,
+				extname,
+				root,
+				output,
+				group
+			}).path
+		}));
 	}
 	/**
 	* Folds each `override` over `base`, left to right, and returns a new resolver with helpers
@@ -1029,12 +927,12 @@ var Resolver = class Resolver {
 		return segment ? require_usingCtx.camelCase(segment) : "";
 	}
 	/**
-	* `mode: 'file'` resolves directly to `output.path`. `mode: 'directory'` (default) resolves
+	* `mode: 'file'` (default) resolves directly to `output.path`. `mode: 'directory'` resolves
 	* to `output.path/{baseName}`, or into a subdirectory when `group` and a `tag`/`path` value
 	* are provided.
 	*/
 	#resolvePath({ baseName, tag, path: groupPath, root, output, group }) {
-		if (output.mode === "file") return node_path.default.resolve(root, output.path);
+		if (output.mode !== "directory") return node_path.default.resolve(root, output.path);
 		const outputDir = node_path.default.resolve(root, output.path);
 		const result = group && (groupPath || tag) ? node_path.default.resolve(outputDir, Resolver.#resolveGroupDir(group, group.type === "path" ? groupPath : tag), baseName) : node_path.default.resolve(outputDir, baseName);
 		const outputDirWithSep = outputDir.endsWith(node_path.default.sep) ? outputDir : `${outputDir}${node_path.default.sep}`;
@@ -1288,6 +1186,38 @@ const ENFORCE_ORDER = {
 	post: 1
 };
 const enforceWeight = (plugin) => plugin.enforce ? ENFORCE_ORDER[plugin.enforce] : 0;
+/**
+* The options bag a `NormalizedPlugin` starts with before a plugin refines it: a directory output
+* at the plugin root and empty filter lists.
+*/
+function defaultPluginOptions() {
+	return {
+		output: {
+			path: ".",
+			mode: "directory"
+		},
+		exclude: [],
+		override: []
+	};
+}
+/**
+* Fills in the `output`, `exclude`, and `override` a `NormalizedPlugin` needs from a plugin's raw
+* options, running `output` through `normalizeOutput`. Idempotent, so the driver can apply it after
+* `setOptions` has already run without disturbing an already-normalized bag.
+*/
+function normalizePluginOptions(rawOptions, pluginName) {
+	const options = {
+		...defaultPluginOptions(),
+		...rawOptions ?? {}
+	};
+	const group = "group" in options ? options.group : void 0;
+	options.output = normalizeOutput({
+		output: options.output,
+		group,
+		pluginName
+	});
+	return options;
+}
 var KubbDriver = class {
 	config;
 	options;
@@ -1309,13 +1239,6 @@ var KubbDriver = class {
 	fileManager = new require_usingCtx.FileManager();
 	plugins = /* @__PURE__ */ new Map();
 	/**
-	* Tracks which plugins have generators registered via `addGenerator()` (hook-based path).
-	* Used by the build loop to decide whether to emit generator hooks for a given plugin.
-	*/
-	#hookGeneratorPlugins = /* @__PURE__ */ new Set();
-	#resolvers = /* @__PURE__ */ new Map();
-	#defaultResolvers = /* @__PURE__ */ new Map();
-	/**
 	* Removers for every listener the driver added (plugin, generator) so `dispose()` can detach
 	* them in one pass. External `hooks.hook(...)` listeners are not tracked.
 	*/
@@ -1343,15 +1266,8 @@ var KubbDriver = class {
 				dependencies: rawPlugin.dependencies,
 				enforce: rawPlugin.enforce,
 				hooks: rawPlugin.hooks,
-				options: rawPlugin.options ?? {
-					output: {
-						path: ".",
-						mode: "directory"
-					},
-					exclude: [],
-					override: []
-				},
-				resolver: this.#getDefaultResolver(rawPlugin.name)
+				options: rawPlugin.options ?? defaultPluginOptions(),
+				resolver: createResolver({ pluginName: rawPlugin.name })
 			};
 		}));
 		for (const plugin of normalized) {
@@ -1460,46 +1376,30 @@ var KubbDriver = class {
 		}
 	}
 	/**
-	* Registers a generator for the given plugin on the shared hook emitter.
-	*
-	* The generator's `schema`, `operation`, and `operations` methods are registered as
-	* listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
-	* respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
-	* so that generators from different plugins do not cross-fire.
+	* Appends a generator to its owning plugin so the generate loop can call it directly.
 	*
-	* The renderer comes from `generator.renderer`. Set `generator.renderer = null` (or leave it
-	* unset) to opt out of rendering.
+	* The generator's `schema`, `operation`, and `operations` methods run per node during the AST
+	* walk in `#runGenerators`, and their result is routed through `dispatch`. Because a generator is
+	* bound to a plugin, generators from different plugins never cross-fire without a name check. The
+	* renderer comes from `generator.renderer`; set it to `null` (or leave it unset) to opt out of
+	* rendering.
 	*
 	* Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
 	*/
 	registerGenerator(pluginName, generator) {
-		const wrap = (method) => {
-			if (!method) return void 0;
-			return async (node, ctx) => {
-				if (ctx.plugin.name !== pluginName) return;
-				const result = await method(node, ctx);
-				await this.dispatch({
-					result,
-					renderer: generator.renderer
-				});
-			};
-		};
-		this.#unhooks.push(this.hooks.addHooks({
-			"kubb:generate:schema": wrap(generator.schema),
-			"kubb:generate:operation": wrap(generator.operation),
-			"kubb:generate:operations": wrap(generator.operations)
-		}));
-		this.#hookGeneratorPlugins.add(pluginName);
+		const plugin = this.plugins.get(pluginName);
+		if (!plugin) return;
+		plugin.generators = plugin.generators ? [...plugin.generators, generator] : [generator];
 	}
 	/**
 	* Returns `true` when at least one generator was registered for the given plugin
 	* via `addGenerator()` in `kubb:plugin:setup`.
 	*
-	* Used by the build loop to decide whether to walk the AST and emit generator hooks
+	* Used by the build loop to decide whether to walk the AST and run the generators
 	* for a plugin.
 	*/
 	hasHookGenerators(pluginName) {
-		return this.#hookGeneratorPlugins.has(pluginName);
+		return (this.plugins.get(pluginName)?.generators?.length ?? 0) > 0;
 	}
 	/**
 	* Runs the full plugin pipeline. Returns the diagnostics collected so far even
@@ -1510,21 +1410,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) => {
-				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer.map((item) => ({
-					...item,
-					config
-				})) });
+				updateBuffer.sort((a, b) => a.processed - b.processed);
+				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer });
 				updateBuffer.length = 0;
 				await hooks.callHook("kubb:files:processing:end", { files });
 			}
@@ -1534,12 +1438,16 @@ var KubbDriver = class {
 				const outputRoot = (0, node_path.resolve)(config.root, config.output.path);
 				await this.#parseInput();
 				await this.setupHooks();
-				if (this.adapter && this.inputNode) await hooks.callHook("kubb:build:start", Object.assign({
-					config,
-					adapter: this.adapter,
-					meta: this.inputNode.meta,
-					getPlugin: this.getPlugin.bind(this)
-				}, this.#filesPayload()));
+				for (const plugin of this.plugins.values()) plugin.options = normalizePluginOptions(plugin.options, plugin.name);
+				if (this.adapter && this.inputNode) {
+					const buildStartContext = this.#withFiles({
+						config,
+						adapter: this.adapter,
+						meta: this.inputNode.meta,
+						getPlugin: this.getPlugin.bind(this)
+					});
+					await hooks.callHook("kubb:build:start", buildStartContext);
+				}
 				const generatorPlugins = [];
 				for (const plugin of this.plugins.values()) {
 					const context = this.getContext(plugin);
@@ -1584,10 +1492,11 @@ var KubbDriver = class {
 					});
 				}
 				diagnostics.push(...await this.#runGenerators(generatorPlugins));
-				await hooks.callHook("kubb:plugins:end", Object.assign({ config }, this.#filesPayload()));
+				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,
@@ -1603,35 +1512,42 @@ var KubbDriver = class {
 			}
 		});
 	}
-	#filesPayload() {
-		const driver = this;
+	/**
+	* Widens `extra` with the files present at emit time and a bound `upsertFile`, the shape every
+	* file-carrying hook context shares. Building it here in one place keeps the `files` and
+	* `upsertFile` keys from being dropped by a stray spread at the call site.
+	*/
+	#withFiles(extra) {
 		return {
-			get files() {
-				return driver.fileManager.files;
-			},
-			upsertFile: (...files) => driver.fileManager.upsert(...files)
+			...extra,
+			files: this.fileManager.files,
+			upsertFile: (...files) => this.fileManager.upsert(...files)
 		};
 	}
 	#emitPluginEnd({ plugin, duration, success, error }) {
-		return this.hooks.callHook("kubb:plugin:end", Object.assign({
+		return this.hooks.callHook("kubb:plugin:end", this.#withFiles({
 			plugin,
 			duration,
 			success,
 			...error ? { error } : {},
 			config: this.config
-		}, this.#filesPayload()));
+		}));
 	}
 	/**
-	* Runs schemas and operations through every plugin's generators. Each node is run
-	* through the plugin's macros (from `this.#transforms`) before the generator sees it,
-	* so plugins stay isolated and the hot path stays per-node. Schemas run before operations
-	* so file output stays deterministic across runs.
-	* A failing plugin contributes an error diagnostic so the rest of the build continues.
-	* Every plugin also contributes a `timing` diagnostic.
+	* Runs schemas and operations through every plugin's generators. The walk is node-outer: each
+	* schema is visited once and each operation once, and the node fans out to the matching
+	* generators of every plugin in dependency order. A per-node cache (`createNodeCache`) is created
+	* once per node and shared by all of that node's plugins, so node-derived work is computed once
+	* and reused instead of recomputed per plugin. Each node still runs through the plugin's macros
+	* (from `this.#transforms`) and its exclude/include/override filters before that plugin's
+	* generator sees it, so plugins stay isolated. Schemas run before operations so file output
+	* stays deterministic across runs. A generator with a `match` predicate that resolves `false`
+	* for a node is skipped for that node, without calling `schema`/`operation`.
 	*
-	* Plugins are processed one at a time, in full, so `kubb:plugin:end` fires as each one
-	* completes rather than all at once at the end. That ordering drives the CLI's
-	* `Plugins N/M` counter.
+	* A failing plugin is dropped from the remaining walk, contributes an error diagnostic, and no
+	* longer aborts the other plugins. `kubb:plugin:end` and each plugin's `timing` diagnostic fire
+	* in dependency order once the walk finishes, driving the CLI's `Plugins N/M` counter. The
+	* `operations` batch fires once per plugin after the single operation walk.
 	*
 	* When `this.inputNode` is `null`, every entry still gets a `kubb:plugin:end` so
 	* post-plugin listeners (the barrel writer and friends) complete.
@@ -1656,13 +1572,10 @@ var KubbDriver = class {
 		}
 		const transforms = this.#transforms;
 		const { schemas, operations } = this.inputNode;
-		const emitsSchemaHook = this.hooks.listenerCount("kubb:generate:schema") > 0;
-		const emitsOperationHook = this.hooks.listenerCount("kubb:generate:operation") > 0;
-		const emitsOperationsHook = this.hooks.listenerCount("kubb:generate:operations") > 0;
 		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,
@@ -1672,88 +1585,133 @@ var KubbDriver = class {
 			}) !== null);
 			allowedSchemaNamesByPlugin.set(plugin.name, (0, _kubb_ast.collectUsedSchemaNames)(includedOps, schemas));
 		}
-		for (const { plugin, context, hrStart } of entries) {
+		const states = entries.map(({ plugin, context, hrStart }) => {
 			const generatorContext = {
 				...context,
 				resolver: this.getResolver(plugin.name)
 			};
 			const { exclude, include, override } = plugin.options;
-			const optionsAreStatic = !exclude?.length && !include?.length && !override?.length;
-			const allowedSchemaNames = allowedSchemaNamesByPlugin.get(plugin.name) ?? null;
-			let error = null;
-			const resolveForPlugin = (node) => {
-				const transformedNode = transforms.applyTo(plugin.name, node);
-				if (optionsAreStatic) return {
-					transformedNode,
-					options: plugin.options
-				};
-				const options = generatorContext.resolver.default.options(transformedNode, {
-					options: plugin.options,
-					exclude,
-					include,
-					override
-				});
-				if (options === null) return null;
-				return {
-					transformedNode,
-					options
-				};
+			const generators = plugin.generators ?? [];
+			return {
+				plugin,
+				hrStart,
+				generatorContext,
+				exclude,
+				include,
+				override,
+				optionsAreStatic: !exclude?.length && !include?.length && !override?.length,
+				allowedSchemaNames: allowedSchemaNamesByPlugin.get(plugin.name) ?? null,
+				schemaGenerators: generators.filter((generator) => generator.schema),
+				operationGenerators: generators.filter((generator) => generator.operation),
+				operationsGenerators: generators.filter((generator) => generator.operations),
+				pluginOperations: [],
+				error: null
 			};
-			if (emitsSchemaHook) for (const node of schemas) {
-				if (error) break;
+		});
+		const resolveForPlugin = (state, node) => {
+			const transformedNode = transforms.applyTo(state.plugin.name, node);
+			if (state.optionsAreStatic) return {
+				transformedNode,
+				options: state.plugin.options
+			};
+			const options = state.generatorContext.resolver.default.options(transformedNode, {
+				options: state.plugin.options,
+				exclude: state.exclude,
+				include: state.include,
+				override: state.override
+			});
+			if (options === null) return null;
+			return {
+				transformedNode,
+				options
+			};
+		};
+		for (const node of schemas) {
+			const cache = require_usingCtx.createNodeCache();
+			for (const state of states) {
+				if (state.error || !state.schemaGenerators.length) continue;
 				try {
-					const resolved = resolveForPlugin(node);
+					const resolved = resolveForPlugin(state, node);
 					if (!resolved) continue;
 					const { transformedNode, options } = resolved;
-					if (allowedSchemaNames !== null && transformedNode.name && !allowedSchemaNames.has(transformedNode.name)) continue;
-					await this.hooks.callHook("kubb:generate:schema", transformedNode, {
-						...generatorContext,
-						options
-					});
+					if (state.allowedSchemaNames !== null && transformedNode.name && !state.allowedSchemaNames.has(transformedNode.name)) continue;
+					const ctx = {
+						...state.generatorContext,
+						options,
+						cache
+					};
+					for (const generator of state.schemaGenerators) {
+						if (!(generator.match ? await generator.match(transformedNode, ctx) : true)) continue;
+						await this.dispatch({
+							result: await generator.schema(transformedNode, ctx),
+							renderer: generator.renderer
+						});
+					}
+					await this.hooks.callHook("kubb:generate:schema", transformedNode, ctx);
 				} catch (caughtError) {
-					error = require_usingCtx.toError(caughtError);
+					state.error = require_usingCtx.toError(caughtError);
 				}
 			}
-			if (emitsOperationHook) for (const node of operations) {
-				if (error) break;
+		}
+		for (const node of operations) {
+			const cache = require_usingCtx.createNodeCache();
+			for (const state of states) {
+				if (state.error || !state.operationGenerators.length && !state.operationsGenerators.length) continue;
 				try {
-					const resolved = resolveForPlugin(node);
+					const resolved = resolveForPlugin(state, node);
 					if (!resolved) continue;
-					await this.hooks.callHook("kubb:generate:operation", resolved.transformedNode, {
-						...generatorContext,
-						options: resolved.options
-					});
+					state.pluginOperations.push(resolved.transformedNode);
+					if (state.operationGenerators.length) {
+						const ctx = {
+							...state.generatorContext,
+							options: resolved.options,
+							cache
+						};
+						for (const generator of state.operationGenerators) {
+							if (!(generator.match ? await generator.match(resolved.transformedNode, ctx) : true)) continue;
+							await this.dispatch({
+								result: await generator.operation(resolved.transformedNode, ctx),
+								renderer: generator.renderer
+							});
+						}
+						await this.hooks.callHook("kubb:generate:operation", resolved.transformedNode, ctx);
+					}
 				} catch (caughtError) {
-					error = require_usingCtx.toError(caughtError);
+					state.error = require_usingCtx.toError(caughtError);
 				}
 			}
-			if (!error && emitsOperationsHook) try {
+		}
+		for (const state of states) {
+			if (state.error || !state.operationsGenerators.length) continue;
+			try {
 				const ctx = {
-					...generatorContext,
-					options: plugin.options
+					...state.generatorContext,
+					options: state.plugin.options,
+					cache: require_usingCtx.createNodeCache()
 				};
-				const pluginOperations = operations.reduce((acc, node) => {
-					const resolved = resolveForPlugin(node);
-					if (resolved) acc.push(resolved.transformedNode);
-					return acc;
-				}, []);
-				await this.hooks.callHook("kubb:generate:operations", pluginOperations, ctx);
+				for (const generator of state.operationsGenerators) await this.dispatch({
+					result: await generator.operations(state.pluginOperations, ctx),
+					renderer: generator.renderer
+				});
+				await this.hooks.callHook("kubb:generate:operations", state.pluginOperations, ctx);
 			} catch (caughtError) {
-				error = require_usingCtx.toError(caughtError);
+				state.error = require_usingCtx.toError(caughtError);
 			}
-			const duration = getElapsedMs(hrStart);
+		}
+		for (const state of states) {
+			const duration = getElapsedMs(state.hrStart);
 			await this.#emitPluginEnd({
-				plugin,
+				plugin: state.plugin,
 				duration,
-				success: !error,
-				error: error ?? void 0
+				success: !state.error,
+				error: state.error ?? void 0
 			});
-			if (error) diagnostics.push({
-				...Diagnostics.from(error),
-				plugin: plugin.name
+			if (state.error) diagnostics.push({
+				...Diagnostics.from(state.error),
+				plugin: state.plugin.name
 			});
 			diagnostics.push(Diagnostics.performance({
-				plugin: plugin.name,
+				plugin: state.plugin.name,
 				duration
 			}));
 		}
@@ -1798,10 +1756,7 @@ var KubbDriver = class {
 	dispose() {
 		for (const unhook of this.#unhooks) unhook();
 		this.#unhooks.length = 0;
-		this.#hookGeneratorPlugins.clear();
 		this.#transforms.dispose();
-		this.#resolvers.clear();
-		this.#defaultResolvers.clear();
 		this.fileManager.dispose();
 		this.inputNode = null;
 		this.#adapterSource = null;
@@ -1809,21 +1764,17 @@ var KubbDriver = class {
 	[Symbol.dispose]() {
 		this.dispose();
 	}
-	#getDefaultResolver = memoize(this.#defaultResolvers, (pluginName) => createResolver({ pluginName }));
 	/**
-	* Merges `partial` with the plugin's default resolver and stores the result.
-	* Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
-	* get the up-to-date resolver without going through `getResolver()`.
+	* Merges `partial` onto a fresh default resolver and stores the result on `plugin.resolver`,
+	* which is the single source `getResolver` and `getPlugin(name).resolver` both read.
 	*/
 	setPluginResolver(pluginName, partial) {
-		const defaultResolver = this.#getDefaultResolver(pluginName);
-		const merged = Resolver.merge(defaultResolver, partial);
-		this.#resolvers.set(pluginName, merged);
 		const plugin = this.plugins.get(pluginName);
-		if (plugin) plugin.resolver = merged;
+		if (!plugin) return;
+		plugin.resolver = Resolver.merge(createResolver({ pluginName }), partial);
 	}
 	getResolver(pluginName) {
-		return this.#resolvers.get(pluginName) ?? this.#getDefaultResolver(pluginName);
+		return this.plugins.get(pluginName)?.resolver ?? createResolver({ pluginName });
 	}
 	getContext(plugin) {
 		const driver = this;
@@ -1906,6 +1857,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
@@ -1922,23 +1939,23 @@ var KubbDriver = class {
 *
 *   return {
 *     name: 'memory',
-*     async hasItem(key) {
+*     async existsItem(key) {
 *       return store.has(key)
 *     },
-*     async getItem(key) {
+*     async readItem(key) {
 *       return store.get(key) ?? null
 *     },
-*     async setItem(key, value) {
+*     async writeItem(key, value) {
 *       store.set(key, value)
 *     },
 *     async removeItem(key) {
 *       store.delete(key)
 *     },
-*     async getKeys(base) {
+*     async readKeys(base) {
 *       const keys = [...store.keys()]
 *       return base ? keys.filter((k) => k.startsWith(base)) : keys
 *     },
-*     async clear(base) {
+*     async empty(base) {
 *       if (!base) store.clear()
 *     },
 *   }
@@ -1982,10 +1999,11 @@ 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 `setItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller
+* - concurrent `writeItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller
 *   can fire every file's write without pacing itself
 *
 * @example
@@ -2004,7 +2022,7 @@ const fsStorage = createStorage(() => {
 	const limit = createLimiter(WRITE_CONCURRENCY);
 	return {
 		name: "fs",
-		async hasItem(key) {
+		async existsItem(key) {
 			try {
 				await (0, node_fs_promises.access)((0, node_path.resolve)(key));
 				return true;
@@ -2012,20 +2030,20 @@ const fsStorage = createStorage(() => {
 				return false;
 			}
 		},
-		async getItem(key) {
+		async readItem(key) {
 			try {
 				return await (0, node_fs_promises.readFile)((0, node_path.resolve)(key), "utf8");
 			} catch (_error) {
 				return null;
 			}
 		},
-		async setItem(key, value) {
+		async writeItem(key, value) {
 			await limit(() => require_usingCtx.write((0, node_path.resolve)(key), value, { sanity: false }));
 		},
 		async removeItem(key) {
 			await (0, node_fs_promises.rm)((0, node_path.resolve)(key), { force: true });
 		},
-		async getKeys(base) {
+		async readKeys(base) {
 			const resolvedBase = (0, node_path.resolve)(base ?? process.cwd());
 			const keys = [];
 			try {
@@ -2036,13 +2054,67 @@ const fsStorage = createStorage(() => {
 			} catch (_error) {}
 			return keys;
 		},
-		async clear(base) {
+		async empty(base) {
 			if (!base) return;
 			await require_usingCtx.clean((0, node_path.resolve)(base));
 		}
 	};
 });
 //#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 {
@@ -2061,6 +2133,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.
@@ -2082,6 +2161,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();
@@ -2099,7 +2179,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);
@@ -2110,11 +2197,12 @@ var Kubb = class {
 				help: "Point `output.path` at a subdirectory such as `./src/gen` so clean only removes generated code.",
 				location: { kind: "config" }
 			});
-			await config.storage.clear(cleanPath);
+			await config.storage.empty(cleanPath);
 		}
 		await driver.setup();
 		this.#driver = driver;
 		this.#storage = config.storage;
+		this.#manifest = manifest ?? null;
 	}
 	/**
 	* Runs the full pipeline and throws on any plugin error.
@@ -2153,6 +2241,70 @@ var Kubb = class {
 			_usingCtx$1.d();
 		}
 	}
+	/**
+	* Run one build and its output passes end to end, emitting the surrounding `kubb:generation:*`
+	* hooks. Never throws on a build error: the outcome comes back in {@link GenerateResult} so the
+	* host decides how failures surface. Telemetry and progress narration stay with the host, which
+	* reads the result and subscribes to the `kubb:*` hooks.
+	*
+	* @example
+	* ```ts
+	* const result = await createKubb(config, { hooks }).generate()
+	* if (!result.success) process.exitCode = 1
+	* ```
+	*/
+	async generate(options = {}) {
+		const { hooks, config } = this;
+		const hrStart = process.hrtime();
+		await hooks.callHook("kubb:generation:start", { config });
+		await hooks.callHook("kubb:setup:start");
+		await this.setup();
+		await hooks.callHook("kubb:setup:end");
+		const { files, diagnostics, storage } = await this.safeBuild();
+		for (const diagnostic of diagnostics) {
+			if (!Diagnostics.isProblem(diagnostic)) continue;
+			if (diagnostic.code === Diagnostics.code.unknown) {
+				await hooks.callHook("kubb:error", { error: diagnostic.cause ?? new Error(diagnostic.message) });
+				continue;
+			}
+			await Diagnostics.emit(hooks, diagnostic);
+		}
+		if (Diagnostics.hasError(diagnostics)) {
+			await hooks.callHook("kubb:generation:end", {
+				config,
+				storage,
+				diagnostics,
+				filesCreated: files.length,
+				status: "failed",
+				hrStart
+			});
+			return {
+				success: false,
+				files,
+				diagnostics
+			};
+		}
+		const outputDiagnostics = options.processOutput ? await options.processOutput({
+			config,
+			outputPath: (0, node_path.resolve)(config.root, config.output.path)
+		}) : [];
+		const finalDiagnostics = [...diagnostics, ...outputDiagnostics];
+		const failed = Diagnostics.hasError(outputDiagnostics);
+		if (!failed) await this.#manifest?.commit();
+		await hooks.callHook("kubb:generation:end", {
+			config,
+			storage,
+			diagnostics: finalDiagnostics,
+			filesCreated: files.length,
+			status: failed ? "failed" : "success",
+			hrStart
+		});
+		return {
+			success: !failed,
+			files,
+			diagnostics: finalDiagnostics
+		};
+	}
 	dispose() {
 		this.#driver?.dispose();
 	}
@@ -2393,11 +2545,13 @@ const fileReporter = createReporter({
 		const { diagnostics, config } = result;
 		if (diagnostics.length === 0) return;
 		const report = buildReport(result);
-		const content = (0, node_util.stripVTControlCharacters)([config.name ? `# ${config.name} — ${(/* @__PURE__ */ new Date()).toISOString()}` : `# ${(/* @__PURE__ */ new Date()).toISOString()}`, ...[
+		const header = config.name ? `# ${config.name} — ${(/* @__PURE__ */ new Date()).toISOString()}` : `# ${(/* @__PURE__ */ new Date()).toISOString()}`;
+		const sections = [
 			buildSummarySection(report),
 			buildProblemSection(diagnostics),
 			buildTimingSection(report)
-		].filter((section) => section.length > 0).map((section) => section.join("\n"))].join("\n\n"));
+		].filter((section) => section.length > 0);
+		const content = (0, node_util.stripVTControlCharacters)([header, ...sections.map((section) => section.join("\n"))].join("\n\n"));
 		const baseName = `${[
 			"kubb",
 			config.name,
@@ -2550,23 +2704,23 @@ const memoryStorage = createStorage(() => {
 	const store = /* @__PURE__ */ new Map();
 	return {
 		name: "memory",
-		async hasItem(key) {
+		async existsItem(key) {
 			return store.has(key);
 		},
-		async getItem(key) {
+		async readItem(key) {
 			return store.get(key) ?? null;
 		},
-		async setItem(key, value) {
+		async writeItem(key, value) {
 			store.set(key, value);
 		},
 		async removeItem(key) {
 			store.delete(key);
 		},
-		async getKeys(base) {
+		async readKeys(base) {
 			const keys = [...store.keys()];
 			return base ? keys.filter((k) => k.startsWith(base)) : keys;
 		},
-		async clear(base) {
+		async empty(base) {
 			if (!base) {
 				store.clear();
 				return;