@kubb/core 5.0.0-beta.98 → 5.0.0

package/dist/index.js

@@ -1,11 +1,13 @@
-import "./rolldown-runtime-C0LytTxp.js";
-import { a as isPathInside, c as write, d as toError, f as camelCase, i as clean, l as BuildError, n as FileManager, o as toFilePath, r as Hookable, s as toPosixPath, t as _usingCtx, u as getErrorMessage } from "./usingCtx-BNggxUEL.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, collect, collectUsedSchemaNames, composeMacros, narrowSchema, operationDef, resolveRefName, schemaDef, transform } from "@kubb/ast";
+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
 /**
@@ -145,163 +147,15 @@ const randomColors = [
 function randomCliColor(text) {
 	if (!text) return "";
 	const index = hash("sha256", text, "buffer").readUInt32BE(0) % randomColors.length;
-	return styleText(randomColors[index] ?? "white", text);
+	const color = randomColors[index] ?? "white";
+	return 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`.
@@ -361,14 +215,34 @@ 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",
 		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]: {
+		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]: {
+		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]: {
 		title: "Reference not found",
 		cause: "A `$ref` could not be resolved in the source document.",
@@ -709,14 +583,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 ?? (path.extname(output.path) ? "file" : "directory");
 	if (mode === "file" && group) throw new Diagnostics.Error({
 		code: 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
 	});
@@ -767,6 +645,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
@@ -774,6 +669,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",
@@ -885,28 +787,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 collect(node, { schema: (schemaNode) => {
-			const schemaRef = narrowSchema(schemaNode, "ref");
-			if (!schemaRef?.ref) return null;
-			const schemaName = resolveRefName(schemaRef);
-			if (!schemaName || seen.has(schemaName)) return null;
-			seen.add(schemaName);
-			return ast.factory.createImport({
-				name: [resolveName(schemaName)],
-				path: this.file({
-					name: schemaName,
-					extname,
-					root,
-					output,
-					group
-				}).path
-			});
-		} });
+		return collectImportedRefNames(node).map((schemaName) => 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
@@ -1027,12 +925,12 @@ var Resolver = class Resolver {
 		return segment ? 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 path.resolve(root, output.path);
+		if (output.mode !== "directory") return path.resolve(root, output.path);
 		const outputDir = path.resolve(root, output.path);
 		const result = group && (groupPath || tag) ? path.resolve(outputDir, Resolver.#resolveGroupDir(group, group.type === "path" ? groupPath : tag), baseName) : path.resolve(outputDir, baseName);
 		const outputDirWithSep = outputDir.endsWith(path.sep) ? outputDir : `${outputDir}${path.sep}`;
@@ -1286,6 +1184,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;
@@ -1307,13 +1237,6 @@ var KubbDriver = class {
 	fileManager = new 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.
 	*/
@@ -1341,15 +1264,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) {
@@ -1458,46 +1374,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
@@ -1508,21 +1408,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 });
 			}
@@ -1532,12 +1436,16 @@ var KubbDriver = class {
 				const outputRoot = 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);
@@ -1582,10 +1490,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,
@@ -1601,35 +1510,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.
@@ -1654,9 +1570,6 @@ 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;
@@ -1670,88 +1583,133 @@ var KubbDriver = class {
 			}) !== null);
 			allowedSchemaNamesByPlugin.set(plugin.name, 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 = 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 = toError(caughtError);
+					state.error = toError(caughtError);
 				}
 			}
-			if (emitsOperationHook) for (const node of operations) {
-				if (error) break;
+		}
+		for (const node of operations) {
+			const cache = 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 = toError(caughtError);
+					state.error = 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: 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 = toError(caughtError);
+				state.error = 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
 			}));
 		}
@@ -1796,10 +1754,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;
@@ -1807,21 +1762,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;
@@ -1904,6 +1855,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
@@ -1920,23 +1938,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()
 *     },
 *   }
@@ -1980,10 +1998,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
@@ -2002,7 +2021,7 @@ const fsStorage = createStorage(() => {
 	const limit = createLimiter(WRITE_CONCURRENCY);
 	return {
 		name: "fs",
-		async hasItem(key) {
+		async existsItem(key) {
 			try {
 				await access(resolve(key));
 				return true;
@@ -2010,20 +2029,20 @@ const fsStorage = createStorage(() => {
 				return false;
 			}
 		},
-		async getItem(key) {
+		async readItem(key) {
 			try {
 				return await readFile(resolve(key), "utf8");
 			} catch (_error) {
 				return null;
 			}
 		},
-		async setItem(key, value) {
+		async writeItem(key, value) {
 			await limit(() => write(resolve(key), value, { sanity: false }));
 		},
 		async removeItem(key) {
 			await rm(resolve(key), { force: true });
 		},
-		async getKeys(base) {
+		async readKeys(base) {
 			const resolvedBase = resolve(base ?? process.cwd());
 			const keys = [];
 			try {
@@ -2034,13 +2053,67 @@ const fsStorage = createStorage(() => {
 			} catch (_error) {}
 			return keys;
 		},
-		async clear(base) {
+		async empty(base) {
 			if (!base) return;
 			await clean(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 = 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 {
@@ -2059,6 +2132,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.
@@ -2080,6 +2160,7 @@ var Kubb = class {
 	config;
 	#driver = null;
 	#storage = null;
+	#manifest = null;
 	constructor(userConfig, options = {}) {
 		this.config = resolveConfig(userConfig);
 		this.hooks = options.hooks ?? new Hookable();
@@ -2097,7 +2178,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);
@@ -2108,11 +2196,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.
@@ -2151,6 +2240,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: 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();
 	}
@@ -2391,11 +2544,13 @@ const fileReporter = createReporter({
 		const { diagnostics, config } = result;
 		if (diagnostics.length === 0) return;
 		const report = buildReport(result);
-		const content = 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 = stripVTControlCharacters([header, ...sections.map((section) => section.join("\n"))].join("\n\n"));
 		const baseName = `${[
 			"kubb",
 			config.name,
@@ -2548,23 +2703,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;