@kubb/core 5.0.0-beta.11 → 5.0.0-beta.110

package/dist/index.js

@@ -1,150 +1,67 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import { a as definePlugin, c as DEFAULT_STUDIO_URL, i as defineResolver, l as logLevel, n as applyHookResult, o as DEFAULT_BANNER, r as FileManager, s as DEFAULT_EXTENSION, t as PluginDriver, u as camelCase } from "./PluginDriver-CGypdXHg.js";
-import { EventEmitter } from "node:events";
-import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import * as ast from "@kubb/ast";
-import { collectUsedSchemaNames, extractStringsFromNodes, transform, walk } from "@kubb/ast";
-import { version } from "node:process";
-//#region ../../internals/utils/src/errors.ts
+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 { createHash, hash } from "node:crypto";
+import { access, glob, readFile, rm } from "node:fs/promises";
+import path, { join, relative, resolve } from "node:path";
+import { ast, collectImportedRefNames, collectUsedSchemaNames, composeMacros, operationDef, schemaDef, transform } from "@kubb/ast";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import process$1 from "node:process";
+//#region src/createAdapter.ts
 /**
-* Thrown when one or more errors occur during a Kubb build.
-* Carries the full list of underlying errors on `errors`.
+* Defines a custom adapter that translates a spec format into Kubb's universal
+* AST, for example GraphQL, gRPC, or AsyncAPI. The built-in `@kubb/adapter-oas`
+* handles OpenAPI/Swagger documents.
 *
-* @example
-* ```ts
-* throw new BuildError('Build failed', { errors: [err1, err2] })
-* ```
-*/
-var BuildError = class extends Error {
-	errors;
-	constructor(message, options) {
-		super(message, { cause: options.cause });
-		this.name = "BuildError";
-		this.errors = options.errors;
-	}
-};
-/**
-* Coerces an unknown thrown value to an `Error` instance.
-* Returns the value as-is when it is already an `Error`; otherwise wraps it with `String(value)`.
+* Adapters must return an `InputNode` from `parse`. That node is what every
+* plugin in the build consumes.
 *
 * @example
 * ```ts
-* try { ... } catch(err) {
-*   throw new BuildError('Build failed', { cause: toError(err), errors: [] })
-* }
+* import { createAdapter, type AdapterFactoryOptions } from '@kubb/core'
+* import { ast } from '@kubb/ast'
+*
+* type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
+*
+* export const myAdapter = createAdapter<MyAdapter>((options) => ({
+*   name: 'my-adapter',
+*   options,
+*   document: null,
+*   async parse(_source) {
+*     // Convert the source (path or inline data) into an InputNode.
+*     return ast.factory.createInput()
+*   },
+*   async validate() {
+*     // Throw here when the spec is invalid.
+*   },
+* }))
 * ```
 */
-function toError(value) {
-	return value instanceof Error ? value : new Error(String(value));
+function createAdapter(build) {
+	return (options) => build(options ?? {});
 }
 //#endregion
-//#region ../../internals/utils/src/asyncEventEmitter.ts
+//#region src/applyConfigDefaults.ts
 /**
-* Typed `EventEmitter` that awaits all async listeners before resolving.
-* Wraps Node's `EventEmitter` with full TypeScript event-map inference.
-*
-* @example
-* ```ts
-* const emitter = new AsyncEventEmitter<{ build: [name: string] }>()
-* emitter.on('build', async (name) => { console.log(name) })
-* await emitter.emit('build', 'petstore') // all listeners awaited
-* ```
+* Fills in the config defaults shared by `defineConfig` and the unplugin factory: the fallback
+* adapter, `defaultOutput`'s fields, and appending the barrel plugin when it's not already
+* registered. Both entry points construct their own adapter, barrel plugin, and output defaults
+* (`barrel` is a `@kubb/plugin-barrel` extension field core doesn't know about) and pass them in,
+* so `@kubb/core` doesn't need to depend on `@kubb/adapter-oas` or `@kubb/plugin-barrel`.
 */
-var AsyncEventEmitter = class {
-	/**
-	* Maximum number of listeners per event before Node emits a memory-leak warning.
-	* @default 10
-	*/
-	constructor(maxListener = 10) {
-		this.#emitter.setMaxListeners(maxListener);
-	}
-	#emitter = new EventEmitter();
-	/**
-	* Emits `eventName` and awaits all registered listeners sequentially.
-	* Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
-	*
-	* @example
-	* ```ts
-	* await emitter.emit('build', 'petstore')
-	* ```
-	*/
-	async emit(eventName, ...eventArgs) {
-		const listeners = this.#emitter.listeners(eventName);
-		if (listeners.length === 0) return;
-		for (const listener of listeners) try {
-			await listener(...eventArgs);
-		} catch (err) {
-			let serializedArgs;
-			try {
-				serializedArgs = JSON.stringify(eventArgs);
-			} catch {
-				serializedArgs = String(eventArgs);
-			}
-			throw new Error(`Error in async listener for "${eventName}" with eventArgs ${serializedArgs}`, { cause: toError(err) });
+function applyConfigDefaults(config, { defaultAdapter, barrelPlugin, barrelPluginName, defaultOutput }) {
+	const plugins = config.plugins?.some((plugin) => plugin.name === barrelPluginName) ? config.plugins ?? [] : [...config.plugins ?? [], barrelPlugin];
+	return {
+		adapter: config.adapter ?? defaultAdapter,
+		plugins,
+		output: {
+			...defaultOutput,
+			...config.output
 		}
-	}
-	/**
-	* Registers a persistent listener for `eventName`.
-	*
-	* @example
-	* ```ts
-	* emitter.on('build', async (name) => { console.log(name) })
-	* ```
-	*/
-	on(eventName, handler) {
-		this.#emitter.on(eventName, handler);
-	}
-	/**
-	* Registers a one-shot listener that removes itself after the first invocation.
-	*
-	* @example
-	* ```ts
-	* emitter.onOnce('build', async (name) => { console.log(name) })
-	* ```
-	*/
-	onOnce(eventName, handler) {
-		const wrapper = (...args) => {
-			this.off(eventName, wrapper);
-			return handler(...args);
-		};
-		this.on(eventName, wrapper);
-	}
-	/**
-	* Removes a previously registered listener.
-	*
-	* @example
-	* ```ts
-	* emitter.off('build', handler)
-	* ```
-	*/
-	off(eventName, handler) {
-		this.#emitter.off(eventName, handler);
-	}
-	/**
-	* Returns the number of listeners registered for `eventName`.
-	*
-	* @example
-	* ```ts
-	* emitter.on('build', handler)
-	* emitter.listenerCount('build') // 1
-	* ```
-	*/
-	listenerCount(eventName) {
-		return this.#emitter.listenerCount(eventName);
-	}
-	/**
-	* Removes all listeners from every event channel.
-	*
-	* @example
-	* ```ts
-	* emitter.removeAll()
-	* ```
-	*/
-	removeAll() {
-		this.#emitter.removeAllListeners();
-	}
-};
+	};
+}
 //#endregion
 //#region ../../internals/utils/src/time.ts
 /**
@@ -179,568 +96,1899 @@ function formatMs(ms) {
 	return `${Math.round(ms)}ms`;
 }
 //#endregion
-//#region ../../internals/utils/src/fs.ts
+//#region ../../internals/utils/src/colors.ts
+/**
+* Parses a CSS hex color string (`#RGB`) into its RGB channels.
+* Falls back to `255` for any channel that cannot be parsed.
+*/
+function parseHex(color) {
+	const int = Number.parseInt(color.replace("#", ""), 16);
+	return Number.isNaN(int) ? {
+		r: 255,
+		g: 255,
+		b: 255
+	} : {
+		r: int >> 16 & 255,
+		g: int >> 8 & 255,
+		b: int & 255
+	};
+}
+/**
+* Returns a function that wraps a string in a 24-bit ANSI true-color escape sequence
+* for the given hex color.
+*/
+function hex(color) {
+	const { r, g, b } = parseHex(color);
+	return (text) => `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+}
+hex("#F55A17"), hex("#F5A217"), hex("#F58517"), hex("#B45309"), hex("#FFFFFF"), hex("#adadc6"), hex("#FDA4AF");
 /**
-* Resolves to `true` when the file or directory at `path` exists.
-* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
+* ANSI color names used by {@link randomCliColor} for deterministic terminal coloring.
+*/
+const randomColors = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"white",
+	"magenta",
+	"cyan",
+	"gray"
+];
+/**
+* Wraps `text` in a deterministic ANSI color derived from the text's SHA-256 hash.
 *
 * @example
 * ```ts
-* if (await exists('./kubb.config.ts')) {
-*   const content = await read('./kubb.config.ts')
-* }
+* randomCliColor('petstore') // '\x1b[33m' + 'petstore' + '\x1b[39m' (always the same color for 'petstore')
 * ```
 */
-async function exists(path) {
-	if (typeof Bun !== "undefined") return Bun.file(path).exists();
-	return access(path).then(() => true, () => false);
+function randomCliColor(text) {
+	if (!text) return "";
+	const index = hash("sha256", text, "buffer").readUInt32BE(0) % randomColors.length;
+	const color = randomColors[index] ?? "white";
+	return styleText(color, text);
+}
+//#endregion
+//#region src/Diagnostics.ts
+/**
+* Docs major version, derived from the package version so the link tracks the published major.
+*/
+const docsMajor = "5.0.0-beta.110".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`.
+*/
+function isKind(kind) {
+	return (diagnostic) => (diagnostic.kind ?? "problem") === kind;
 }
 /**
-* Writes `data` to `path`, trimming leading/trailing whitespace before saving.
-* Skips the write when the trimmed content is empty or identical to what is already on disk.
-* Creates any missing parent directories automatically.
-* When `sanity` is `true`, re-reads the file after writing and throws if the content does not match.
+* Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
 *
 * @example
 * ```ts
-* await write('./src/Pet.ts', source)         // writes and returns trimmed content
-* await write('./src/Pet.ts', source)         // null — file unchanged
-* await write('./src/Pet.ts', '  ')           // null — empty content skipped
+* if (isProblem(diagnostic)) {
+*   console.log(diagnostic.location)
+* }
 * ```
 */
-async function write(path, data, options = {}) {
-	const trimmed = data.trim();
-	if (trimmed === "") return null;
-	const resolved = resolve(path);
-	if (typeof Bun !== "undefined") {
-		const file = Bun.file(resolved);
-		if ((await file.exists() ? await file.text() : null) === trimmed) return null;
-		await Bun.write(resolved, trimmed);
-		return trimmed;
-	}
-	try {
-		if (await readFile(resolved, { encoding: "utf-8" }) === trimmed) return null;
-	} catch {}
-	await mkdir(dirname(resolved), { recursive: true });
-	await writeFile(resolved, trimmed, { encoding: "utf-8" });
-	if (options.sanity) {
-		const savedData = await readFile(resolved, { encoding: "utf-8" });
-		if (savedData !== trimmed) throw new Error(`Sanity check failed for ${path}\n\nData[${data.length}]:\n${data}\n\nSaved[${savedData.length}]:\n${savedData}\n`);
-		return savedData;
-	}
-	return trimmed;
-}
+const isProblem = isKind("problem");
 /**
-* Recursively removes `path`. Silently succeeds when `path` does not exist.
+* Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
 *
 * @example
 * ```ts
-* await clean('./dist')
+* const timings = diagnostics.filter(isPerformance)
 * ```
 */
-async function clean(path) {
-	return rm(path, {
-		recursive: true,
-		force: true
-	});
-}
-//#endregion
-//#region ../../internals/utils/src/reserved.ts
-/**
-* JavaScript and Java reserved words.
-* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
-*/
-const reservedWords = new Set([
-	"abstract",
-	"arguments",
-	"boolean",
-	"break",
-	"byte",
-	"case",
-	"catch",
-	"char",
-	"class",
-	"const",
-	"continue",
-	"debugger",
-	"default",
-	"delete",
-	"do",
-	"double",
-	"else",
-	"enum",
-	"eval",
-	"export",
-	"extends",
-	"false",
-	"final",
-	"finally",
-	"float",
-	"for",
-	"function",
-	"goto",
-	"if",
-	"implements",
-	"import",
-	"in",
-	"instanceof",
-	"int",
-	"interface",
-	"let",
-	"long",
-	"native",
-	"new",
-	"null",
-	"package",
-	"private",
-	"protected",
-	"public",
-	"return",
-	"short",
-	"static",
-	"super",
-	"switch",
-	"synchronized",
-	"this",
-	"throw",
-	"throws",
-	"transient",
-	"true",
-	"try",
-	"typeof",
-	"var",
-	"void",
-	"volatile",
-	"while",
-	"with",
-	"yield",
-	"Array",
-	"Date",
-	"hasOwnProperty",
-	"Infinity",
-	"isFinite",
-	"isNaN",
-	"isPrototypeOf",
-	"length",
-	"Math",
-	"name",
-	"NaN",
-	"Number",
-	"Object",
-	"prototype",
-	"String",
-	"toString",
-	"undefined",
-	"valueOf"
-]);
+const isPerformance = isKind("performance");
 /**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+* Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
 *
 * @example
 * ```ts
-* isValidVarName('status')  // true
-* isValidVarName('class')   // false (reserved word)
-* isValidVarName('42foo')   // false (starts with digit)
+* if (isUpdate(diagnostic)) {
+*   console.log(diagnostic.latestVersion)
+* }
 * ```
 */
-function isValidVarName(name) {
-	if (!name || reservedWords.has(name)) return false;
-	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
-}
-//#endregion
-//#region ../../internals/utils/src/urlPath.ts
+const isUpdate = isKind("update");
+/**
+* Accent color per severity. The color tints the `[CODE]` tag (red error, yellow warning,
+* blue info).
+*/
+const severityStyle = {
+	error: "red",
+	warning: "yellow",
+	info: "blue"
+};
+/**
+* Explanation for every {@link diagnosticCode}. Use {@link Diagnostics.explain} to look one up
+* and `Diagnostics.docsUrl` for the matching kubb.dev page.
+*/
+const diagnosticCatalog = {
+	[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]: {
+		title: "Input not found",
+		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.",
+		fix: "Add the missing definition (for example under `components.schemas`) or fix the `$ref`. Run `kubb validate` to check the spec."
+	},
+	[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]: {
+		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]: {
+		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]: {
+		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]: {
+		title: "Plugin info",
+		cause: "A plugin reported an informational message through `ctx.info`.",
+		fix: "Informational only. No action is required."
+	},
+	[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]: {
+		title: "Deprecated",
+		cause: "A referenced schema or operation is marked `deprecated`.",
+		fix: "Migrate off the deprecated definition if the warning is unwanted."
+	},
+	[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]: {
+		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]: {
+		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]: {
+		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]: {
+		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]: {
+		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]: {
+		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]: {
+		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]: {
+		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."
+	}
+};
 /**
-* Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+* Static helpers for working with {@link Diagnostic}s, plus the run-scoped sink
+* that lets deep code report a diagnostic without threading a callback.
 *
-* @example
-* const p = new URLPath('/pet/{petId}')
-* p.URL      // '/pet/:petId'
-* p.template // '`/pet/${petId}`'
+* The sink lives in a single `AsyncLocalStorage` in the `@kubb/core` bundle.
+* `Diagnostics.scope` activates it for a run, so anything inside that run (the
+* adapter parse, a generator) reports through `Diagnostics.report` and lands
+* in the same run.
 */
-var URLPath = class {
+var Diagnostics = class Diagnostics {
+	static #reporterStorage = new AsyncLocalStorage();
 	/**
-	* The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
+	* The diagnostic code catalog, exposed as `Diagnostics.code` (e.g. `Diagnostics.code.refNotFound`).
 	*/
-	path;
-	#options;
-	constructor(path, options = {}) {
-		this.path = path;
-		this.#options = options;
-	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
+	static code = diagnosticCode;
+	/**
+	* Type guard for a build {@link ProblemDiagnostic}.
+	*/
+	static isProblem = isProblem;
+	/**
+	* Type guard for a version-update {@link UpdateDiagnostic}.
+	*/
+	static isUpdate = isUpdate;
+	/**
+	* Type guard for a per-plugin {@link PerformanceDiagnostic}.
+	*/
+	static isPerformance = isPerformance;
+	/**
+	* An `Error` that carries a {@link Diagnostic}, so structured problems can flow
+	* through the existing throw/catch paths while keeping their code and location.
 	*
 	* @example
 	* ```ts
-	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
+	* throw new Diagnostics.Error({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
 	* ```
 	*/
-	get URL() {
-		return this.toURLPath();
+	static Error = class DiagnosticError extends Error {
+		diagnostic;
+		constructor(diagnostic) {
+			super(diagnostic.message, { cause: diagnostic.cause });
+			this.name = "DiagnosticError";
+			this.diagnostic = diagnostic;
+		}
+	};
+	/**
+	* Structural check for a {@link Diagnostics.Error}, including one thrown from a duplicated
+	* `@kubb/core` copy where `instanceof` fails. Matches on the `name` and a `diagnostic`
+	* that carries a `code`.
+	*/
+	static isError(error) {
+		if (error instanceof Diagnostics.Error) return true;
+		return error instanceof Error && error.name === "DiagnosticError" && "diagnostic" in error && typeof error.diagnostic === "object" && error.diagnostic !== null && typeof error.diagnostic?.code === "string";
 	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
-	*
-	* @example
-	* ```ts
-	* new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
-	* new URLPath('/pet/{petId}').isURL                       // false
-	* ```
+	/**
+	* Runs `fn` with `sink` as the active diagnostic sink for the whole async
+	* subtree, so {@link Diagnostics.report} reaches it from anywhere inside.
 	*/
-	get isURL() {
-		try {
-			return !!new URL(this.path).href;
-		} catch {
-			return false;
+	static scope(sink, fn) {
+		return Diagnostics.#reporterStorage.run(sink, fn);
+	}
+	/**
+	* Collects a diagnostic into the active build via the run-scoped sink, without throwing.
+	* Returns `true` when a run consumed it, `false` when called outside a {@link Diagnostics.scope}
+	* (so callers can fall back to throwing). Use a `warning`/`info` severity for non-fatal issues.
+	* For rendering a diagnostic live on the hook bus, use {@link Diagnostics.emit} instead.
+	*/
+	static report(diagnostic) {
+		const sink = Diagnostics.#reporterStorage.getStore();
+		if (!sink) return false;
+		sink(diagnostic);
+		return true;
+	}
+	/**
+	* Emits a diagnostic on the run's `kubb:diagnostic` hook so the loggers render it live.
+	* Use it instead of calling `hooks.callHook('kubb:diagnostic', ...)` directly. To collect a
+	* diagnostic into the build result from deep in a run, use {@link Diagnostics.report} instead.
+	*/
+	static async emit(hooks, diagnostic) {
+		await hooks.callHook("kubb:diagnostic", { diagnostic });
+	}
+	/**
+	* Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
+	* keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
+	*/
+	static from(error) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = error;
+		let root;
+		while (current instanceof Error && !seen.has(current)) {
+			if (Diagnostics.isError(current)) return current.diagnostic;
+			seen.add(current);
+			root = current;
+			current = current.cause;
 		}
+		return {
+			code: diagnosticCode.unknown,
+			severity: "error",
+			message: root ? root.message : getErrorMessage(error),
+			cause: root
+		};
 	}
 	/**
-	* Converts the OpenAPI path to a TypeScript template literal string.
-	*
-	* @example
-	* new URLPath('/pet/{petId}').template              // '`/pet/${petId}`'
-	* new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
+	* Builds a per-plugin performance record. Reporters sum these into the run total.
 	*/
-	get template() {
-		return this.toTemplateString();
+	static performance({ plugin, duration }) {
+		return {
+			kind: "performance",
+			code: diagnosticCode.performance,
+			severity: "info",
+			message: `${plugin} generated in ${Math.round(duration)}ms`,
+			plugin,
+			duration
+		};
 	}
-	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').object
-	* // { url: '/pet/:petId', params: { petId: 'petId' } }
-	* ```
+	/**
+	* Builds the version-update notice shown when a newer Kubb is published on npm.
 	*/
-	get object() {
-		return this.toObject();
+	static update({ currentVersion, latestVersion }) {
+		return {
+			kind: "update",
+			code: diagnosticCode.updateAvailable,
+			severity: "info",
+			message: `Update available: v${currentVersion} → v${latestVersion}. Run \`npm install -g @kubb/cli\` to update.`,
+			currentVersion,
+			latestVersion
+		};
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
-	* ```
+	/**
+	* True when any diagnostic is an error, the severity that fails a build. Non-error
+	* diagnostics are ignored.
 	*/
-	get params() {
-		return this.getParams();
+	static hasError(diagnostics) {
+		return diagnostics.some((diagnostic) => diagnostic.severity === "error");
 	}
-	#transformParam(raw) {
-		const param = isValidVarName(raw) ? raw : camelCase(raw);
-		return this.#options.casing === "camelcase" ? camelCase(param) : param;
+	/**
+	* Names of the plugins that failed, deduped, derived from the error diagnostics
+	* that carry a `plugin`.
+	*/
+	static failedPlugins(diagnostics) {
+		const names = /* @__PURE__ */ new Set();
+		for (const diagnostic of diagnostics) if (diagnostic.severity === "error" && diagnostic.plugin) names.add(diagnostic.plugin);
+		return [...names];
 	}
 	/**
-	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	* Counts `problem` diagnostics by severity for the run summary. `performance` and
+	* `update` diagnostics are ignored.
 	*/
-	#eachParam(fn) {
-		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
-			const raw = match[1];
-			fn(raw, this.#transformParam(raw));
+	static count(diagnostics) {
+		let errors = 0;
+		let warnings = 0;
+		let infos = 0;
+		for (const diagnostic of diagnostics) {
+			if (!isProblem(diagnostic)) continue;
+			if (diagnostic.severity === "error") errors += 1;
+			else if (diagnostic.severity === "warning") warnings += 1;
+			else infos += 1;
 		}
-	}
-	toObject({ type = "path", replacer, stringify } = {}) {
-		const object = {
-			url: type === "path" ? this.toURLPath() : this.toTemplateString({ replacer }),
-			params: this.getParams()
+		return {
+			errors,
+			warnings,
+			infos
 		};
-		if (stringify) {
-			if (type === "template") return JSON.stringify(object).replaceAll("'", "").replaceAll(`"`, "");
-			if (object.params) return `{ url: '${object.url}', params: ${JSON.stringify(object.params).replaceAll("'", "").replaceAll(`"`, "")} }`;
-			return `{ url: '${object.url}' }`;
+	}
+	/**
+	* Drops duplicate `problem` diagnostics that share a code, location pointer, and
+	* plugin, so the same issue reported across several passes is shown once. Non-problem
+	* diagnostics are always kept.
+	*/
+	static dedupe(diagnostics) {
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const diagnostic of diagnostics) {
+			if (!isProblem(diagnostic)) {
+				result.push(diagnostic);
+				continue;
+			}
+			const pointer = diagnostic.location && "pointer" in diagnostic.location ? diagnostic.location.pointer : "";
+			const key = `${diagnostic.code} ${pointer} ${diagnostic.plugin ?? ""}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			result.push(diagnostic);
 		}
-		return object;
+		return result;
 	}
 	/**
-	* Converts the OpenAPI path to a TypeScript template literal string.
-	* An optional `replacer` can transform each extracted parameter name before interpolation.
-	*
-	* @example
-	* new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
+	* Builds the kubb.dev docs URL for a diagnostic code, e.g.
+	* `KUBB_REF_NOT_FOUND` → `https://kubb.dev/docs/5.x/reference/diagnostics/kubb-ref-not-found`.
 	*/
-	toTemplateString({ prefix = "", replacer } = {}) {
-		return `\`${prefix}${this.path.split(/\{([^}]+)\}/).map((part, i) => {
-			if (i % 2 === 0) return part;
-			const param = this.#transformParam(part);
-			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("")}\``;
+	static docsUrl(code) {
+		const slug = code.toLowerCase().replaceAll("_", "-");
+		return `https://kubb.dev/docs/${docsMajor}.x/reference/diagnostics/${slug}`;
 	}
 	/**
-	* Extracts all `{param}` segments from the path and returns them as a key-value map.
-	* An optional `replacer` transforms each parameter name in both key and value positions.
-	* Returns `undefined` when no path parameters are found.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}/tag/{tagId}').getParams()
-	* // { petId: 'petId', tagId: 'tagId' }
-	* ```
+	* The catalog entry for a code: its title, cause, and fix. Mirrors the kubb.dev
+	* `/diagnostics/<slug>` page.
 	*/
-	getParams(replacer) {
-		const params = {};
-		this.#eachParam((_raw, param) => {
-			const key = replacer ? replacer(param) : param;
-			params[key] = key;
-		});
-		return Object.keys(params).length > 0 ? params : void 0;
+	static explain(code) {
+		return diagnosticCatalog[code];
+	}
+	/**
+	* Reduces a diagnostic to its JSON-safe fields plus a `docsUrl`, for machine-readable
+	* consumers. The `cause`, `kind`, and `duration` are dropped, and absent optional
+	* fields are omitted rather than set to `undefined`.
+	*/
+	static serialize(diagnostic) {
+		const problem = isProblem(diagnostic) ? diagnostic : void 0;
+		return {
+			code: diagnostic.code,
+			severity: diagnostic.severity,
+			message: diagnostic.message,
+			...problem?.location ? { location: problem.location } : {},
+			...problem?.help ? { help: problem.help } : {},
+			...problem?.plugin ? { plugin: problem.plugin } : {},
+			...diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
+		};
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax.
+	/**
+	* Renders a {@link Diagnostic} for terminal output as its parts: the `headline`
+	* (`[CODE] plugin: message`, with the code in the severity color) and the indented `details`
+	* rows (`at:` pointer, `fix:` help, `see:` docs link).
 	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
-	* ```
+	* Hosts compose these to fit their gutter: a clack logger passes `[headline, ...details]` as the
+	* message with no gutter symbol, while plain text outputs use {@link Diagnostics.formatLines}.
+	*/
+	static format(diagnostic) {
+		const { code, severity, message } = diagnostic;
+		const color = severityStyle[severity];
+		const problem = isProblem(diagnostic) ? diagnostic : void 0;
+		const tag = styleText(color, styleText("bold", `[${code}]`));
+		const headline = problem?.plugin ? `${tag} ${problem.plugin}: ${message}` : `${tag}: ${message}`;
+		const details = [];
+		if (problem?.location && "pointer" in problem.location) details.push(`  ${styleText("dim", "at:")} ${styleText("cyan", problem.location.pointer)}`);
+		if (problem?.help) details.push(`  ${styleText("cyan", "fix:")} ${problem.help}`);
+		if (code !== diagnosticCode.unknown) details.push(`  ${styleText("dim", "see:")} ${styleText("cyan", Diagnostics.docsUrl(code))}`);
+		return {
+			headline,
+			details
+		};
+	}
+	/**
+	* The self-contained block form of {@link Diagnostics.format}: the `headline` followed by the
+	* indented detail rows. Used where there is no gutter (plain and file output).
 	*/
-	toURLPath() {
-		return this.path.replace(/\{([^}]+)\}/g, ":$1");
+	static formatLines(diagnostic) {
+		const { headline, details } = Diagnostics.format(diagnostic);
+		return [headline, ...details];
 	}
 };
 //#endregion
-//#region src/createAdapter.ts
+//#region src/definePlugin.ts
 /**
-* Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
-*
-* Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
-* Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
-*
-* @note Adapters must parse their input format to Kubb's `InputNode` structure.
-*
-* @example
-* ```ts
-* export const myAdapter = createAdapter<MyAdapter>((options) => {
-*   return {
-*     name: 'my-adapter',
-*     options,
-*     async parse(source) {
-*       // Transform source format to InputNode
-*       return { ... }
-*     },
-*   }
-* })
+* 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.
 *
-* // Instantiate:
-* const adapter = myAdapter({ validate: true })
-* ```
+* 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 createAdapter(build) {
-	return (options) => build(options ?? {});
+function normalizeOutput({ output, group, pluginName }) {
+	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}" 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
+	});
+	return {
+		...output,
+		mode
+	};
 }
-//#endregion
-//#region package.json
-var version$1 = "5.0.0-beta.11";
-//#endregion
-//#region src/createStorage.ts
 /**
-* Factory for implementing custom storage backends that control where generated files are written.
-*
-* Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
-* Kubb provides filesystem and in-memory implementations out of the box.
+* Wraps a plugin factory and returns a function that accepts user options and
+* yields a typed `Plugin`. Lifecycle handlers go inside a single `hooks` object.
 *
-* @note Call the returned factory with optional options to instantiate the storage adapter.
+* Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+* `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+* convention (`plugin-react-query`, `plugin-zod`, ...).
 *
 * @example
 * ```ts
-* import { createStorage } from '@kubb/core'
+* import { definePlugin } from '@kubb/core'
 *
-* export const memoryStorage = createStorage(() => {
-*   const store = new Map<string, string>()
-*   return {
-*     name: 'memory',
-*     async hasItem(key) { return store.has(key) },
-*     async getItem(key) { return store.get(key) ?? null },
-*     async setItem(key, value) { store.set(key, value) },
-*     async removeItem(key) { store.delete(key) },
-*     async getKeys(base) {
-*       const keys = [...store.keys()]
-*       return base ? keys.filter((k) => k.startsWith(base)) : keys
+* export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
+*   name: 'plugin-ts',
+*   hooks: {
+*     'kubb:plugin:setup'(ctx) {
+*       ctx.setResolver(resolverTs)
 *     },
-*     async clear(base) { if (!base) store.clear() },
-*   }
-* })
-*
-* // Instantiate:
-* const storage = memoryStorage()
+*   },
+* }))
 * ```
 */
-function createStorage(build) {
-	return (options) => build(options ?? {});
+function definePlugin(factory) {
+	return (options) => factory(options ?? {});
 }
 //#endregion
-//#region ../../node_modules/.pnpm/yocto-queue@1.2.2/node_modules/yocto-queue/index.js
-var Node$1 = class {
-	static {
-		__name(this, "Node");
-	}
-	value;
-	next;
-	constructor(value) {
-		this.value = value;
-	}
-};
-var Queue = class {
-	#head;
-	#tail;
-	#size;
-	constructor() {
-		this.clear();
-	}
-	enqueue(value) {
-		const node = new Node$1(value);
-		if (this.#head) {
-			this.#tail.next = node;
-			this.#tail = node;
-		} else {
-			this.#head = node;
-			this.#tail = node;
-		}
-		this.#size++;
-	}
-	dequeue() {
-		const current = this.#head;
-		if (!current) return;
-		this.#head = this.#head.next;
-		this.#size--;
-		if (!this.#head) this.#tail = void 0;
-		return current.value;
-	}
-	peek() {
-		if (!this.#head) return;
-		return this.#head.value;
-	}
-	clear() {
-		this.#head = void 0;
-		this.#tail = void 0;
-		this.#size = 0;
-	}
-	get size() {
-		return this.#size;
-	}
-	*[Symbol.iterator]() {
-		let current = this.#head;
-		while (current) {
-			yield current.value;
-			current = current.next;
-		}
-	}
-	*drain() {
-		while (this.#head) yield this.dequeue();
-	}
-};
-//#endregion
-//#region ../../node_modules/.pnpm/p-limit@7.3.0/node_modules/p-limit/index.js
-function pLimit(concurrency) {
-	let rejectOnClear = false;
-	if (typeof concurrency === "object") ({concurrency, rejectOnClear = false} = concurrency);
-	validateConcurrency(concurrency);
-	if (typeof rejectOnClear !== "boolean") throw new TypeError("Expected `rejectOnClear` to be a boolean");
-	const queue = new Queue();
-	let activeCount = 0;
-	const resumeNext = () => {
-		if (activeCount < concurrency && queue.size > 0) {
-			activeCount++;
-			queue.dequeue().run();
-		}
-	};
-	const next = () => {
-		activeCount--;
-		resumeNext();
-	};
-	const run = async (function_, resolve, arguments_) => {
-		const result = (async () => function_(...arguments_))();
-		resolve(result);
-		try {
-			await result;
-		} catch {}
-		next();
-	};
-	const enqueue = (function_, resolve, reject, arguments_) => {
-		const queueItem = { reject };
-		new Promise((internalResolve) => {
-			queueItem.run = internalResolve;
-			queue.enqueue(queueItem);
-		}).then(run.bind(void 0, function_, resolve, arguments_));
-		if (activeCount < concurrency) resumeNext();
-	};
-	const generator = (function_, ...arguments_) => new Promise((resolve, reject) => {
-		enqueue(function_, resolve, reject, arguments_);
+//#region src/input.ts
+/**
+* Classifies an `input` value so callers branch on it once instead of repeating the checks.
+*
+* A non-string is a parsed spec (`object`). A string is `inline` when it holds OpenAPI content,
+* meaning it starts with `{` or `[`, spans multiple lines, or opens with a YAML `openapi:` or
+* `swagger:` key. Otherwise a string is a `url` when it parses as one, or a `file` path.
+*/
+function getInputKind(input) {
+	if (typeof input !== "string") return "object";
+	const trimmed = input.trimStart();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[") || input.includes("\n") || /^(openapi|swagger)\s*:/i.test(trimmed)) return "inline";
+	if (URL.canParse(input)) return "url";
+	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
+* local path is resolved against `config.root`, both as `{ type: 'path' }`.
+*/
+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" }
 	});
-	Object.defineProperties(generator, {
-		activeCount: { get: () => activeCount },
-		pendingCount: { get: () => queue.size },
-		clearQueue: { value() {
-			if (!rejectOnClear) {
-				queue.clear();
-				return;
-			}
-			const abortError = AbortSignal.abort().reason;
-			while (queue.size > 0) queue.dequeue().reject(abortError);
-		} },
-		concurrency: {
-			get: () => concurrency,
-			set(newConcurrency) {
-				validateConcurrency(newConcurrency);
-				concurrency = newConcurrency;
-				queueMicrotask(() => {
-					while (activeCount < concurrency && queue.size > 0) resumeNext();
-				});
-			}
-		},
-		map: { async value(iterable, function_) {
-			const promises = Array.from(iterable, (value, index) => this(function_, value, index));
-			return Promise.all(promises);
-		} }
+	if (!input) throw new Diagnostics.Error({
+		code: Diagnostics.code.inputRequired,
+		severity: "error",
+		message: "An adapter is configured without an input.",
+		help: "Set `input` to a file path, a URL, an inline spec (JSON/YAML string), or a parsed object in your Kubb config.",
+		location: { kind: "config" }
 	});
-	return generator;
+	if (typeof input !== "string") return {
+		type: "data",
+		data: input
+	};
+	const kind = getInputKind(input);
+	if (kind === "inline") return {
+		type: "data",
+		data: input
+	};
+	if (kind === "url") return {
+		type: "path",
+		path: input
+	};
+	return {
+		type: "path",
+		path: resolve(config.root, input)
+	};
+}
+//#endregion
+//#region src/Resolver.ts
+function isNamespace(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function validateConcurrency(concurrency) {
-	if (!((Number.isInteger(concurrency) || concurrency === Number.POSITIVE_INFINITY) && concurrency > 0)) throw new TypeError("Expected `concurrency` to be a number from 1 and up");
+/**
+* Shared brand for reaching a resolver's build options. `Resolver.merge` reads this instead of
+* relying on `instanceof`, which fails when a CommonJS config and the ESM CLI each load their own
+* copy of `@kubb/core`. `Symbol.for` resolves to one key across those copies, so the options stay
+* reachable and a `file` override is never dropped.
+*/
+const resolverOptions = Symbol.for("@kubb/core/resolver/options");
+/**
+* Built-in `file.baseName`: casts the identifier with `toFilePath` and appends the extension.
+*/
+function toBaseName({ name, extname }) {
+	return `${toFilePath(name)}${extname}`;
 }
+/**
+* Base constraint for all plugin resolver objects.
+*
+* The built-in machinery lives under `default`. Generators call the top-level `name`, `file`,
+* and `imports`, and a plugin overrides `name` and `file` to set its conventions. Extend with
+* top-level helpers (`typeName`, …) and/or grouped namespaces (`query`, `schema`, …).
+*
+* @example Top-level helper
+* ```ts
+* type MyResolver = Resolver & {
+*   typeName(name: string): string
+* }
+* ```
+*
+* @example Grouped namespace
+* ```ts
+* type MyResolver = Resolver & {
+*   query: {
+*     name(node: OperationNode): string
+*     keyName(node: OperationNode): string
+*   }
+* }
+* ```
+*/
+var Resolver = class Resolver {
+	static #patternCache = /* @__PURE__ */ new Map();
+	static #optionsCache = /* @__PURE__ */ new WeakMap();
+	pluginName;
+	#options;
+	#baseName;
+	#filePath;
+	constructor(options) {
+		this.pluginName = options.pluginName;
+		this.#options = options;
+		this.#baseName = options.file?.baseName ? options.file.baseName.bind(this) : toBaseName;
+		this.#filePath = options.file?.path ? options.file.path.bind(this) : void 0;
+		this.#apply(options);
+	}
+	/** Exposes the raw build options so `Resolver.merge` can read them across `@kubb/core` copies. */
+	get [resolverOptions]() {
+		return this.#options;
+	}
+	/**
+	* The built-in resolution machinery. Always reaches the untouched defaults, even when a
+	* plugin overrides the top-level `name` or `file`.
+	*/
+	get default() {
+		return {
+			name: camelCase,
+			options: this.#resolveOptions.bind(this),
+			path: this.#resolvePath.bind(this),
+			file: this.#resolveFile.bind(this),
+			banner: this.#resolveBanner.bind(this),
+			footer: this.#resolveFooter.bind(this)
+		};
+	}
+	name(name) {
+		return this.default.name(name);
+	}
+	file(options) {
+		return this.#resolveFile(options);
+	}
+	/**
+	* Builds one `ImportNode` per unique schema referenced in the tree, in first-occurrence
+	* order. Each ref's target resolves through `resolveRefName`, so collision- or macro-renamed
+	* 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));
+		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
+	* re-bound. Top-level keys replace, and a namespace (or `file`) merges per method, so overriding
+	* `query.name` keeps the base `query.keyName`. The last override wins per key. Used when applying
+	* `setResolver` partial overrides, and to compose shared resolver fragments without spreading each
+	* namespace by hand. Reads a resolver's options through the shared brand rather than `instanceof`,
+	* so a `file` override survives even when `base` and `override` come from different `@kubb/core`
+	* copies.
+	*
+	* @example Fold several partial overrides onto a resolver
+	* ```ts
+	* const resolver = Resolver.merge(defaultResolver, sharedNamingPatch, { name: (name) => name.toUpperCase() })
+	* ```
+	*/
+	static merge(base, ...overrides) {
+		const merged = overrides.reduce((acc, override) => {
+			const patch = resolverOptions in override ? override[resolverOptions] : override;
+			for (const [key, value] of Object.entries(patch)) {
+				if (value === void 0) continue;
+				const current = acc[key];
+				acc[key] = isNamespace(value) && isNamespace(current) ? {
+					...current,
+					...value
+				} : value;
+			}
+			return acc;
+		}, { ...base[resolverOptions] });
+		return new Resolver(merged);
+	}
+	/**
+	* Binds each entry of `options` onto the resolver, so `this.name`, `this.default`, and
+	* `this.file` resolve there for top-level helpers and namespace methods alike. `default`
+	* is skipped so it can't be shadowed.
+	*/
+	#apply(options) {
+		const root = this;
+		const bind = (value) => typeof value === "function" ? value.bind(root) : value;
+		for (const [key, value] of Object.entries(options)) {
+			if (key === "pluginName" || key === "default" || key === "file" || value === void 0) continue;
+			root[key] = isNamespace(value) ? Object.fromEntries(Object.entries(value).map(([method, member]) => [method, bind(member)])) : bind(value);
+		}
+	}
+	static #testPattern(value, pattern) {
+		if (typeof pattern === "string") {
+			let regex = Resolver.#patternCache.get(pattern);
+			regex ??= new RegExp(pattern);
+			Resolver.#patternCache.set(pattern, regex);
+			return regex.test(value);
+		}
+		return value.match(pattern) !== null;
+	}
+	static #matchesOperation(node, { type, pattern }) {
+		if (type === "tag") return node.tags.some((tag) => Resolver.#testPattern(tag, pattern));
+		if (type === "operationId") return Resolver.#testPattern(node.operationId, pattern);
+		if (type === "path") return node.path !== void 0 && Resolver.#testPattern(node.path, pattern);
+		if (type === "method") return node.method !== void 0 && Resolver.#testPattern(node.method.toLowerCase(), pattern);
+		if (type === "contentType") return node.requestBody?.content?.some((c) => Resolver.#testPattern(c.contentType, pattern)) ?? false;
+		return false;
+	}
+	/**
+	* Returns `null` when the filter type doesn't apply to schemas, so include rules built
+	* from operation filters (e.g. `tag`) don't exclude every schema.
+	*/
+	static #matchesSchema(node, { type, pattern }) {
+		if (type === "schemaName") return node.name ? Resolver.#testPattern(node.name, pattern) : false;
+		return null;
+	}
+	static #computeOptions(node, { options, exclude = [], include, override = [] }) {
+		if (operationDef.is(node)) {
+			if (exclude.some((filter) => Resolver.#matchesOperation(node, filter))) return null;
+			if (include && !include.some((filter) => Resolver.#matchesOperation(node, filter))) return null;
+			return {
+				...options,
+				...override.find((filter) => Resolver.#matchesOperation(node, filter))?.options
+			};
+		}
+		if (schemaDef.is(node)) {
+			if (exclude.some((filter) => Resolver.#matchesSchema(node, filter) === true)) return null;
+			if (include) {
+				const applicable = include.map((filter) => Resolver.#matchesSchema(node, filter)).filter((result) => result !== null);
+				if (applicable.length > 0 && !applicable.includes(true)) return null;
+			}
+			return {
+				...options,
+				...override.find((filter) => Resolver.#matchesSchema(node, filter) === true)?.options
+			};
+		}
+		return options;
+	}
+	/**
+	* Applies include/exclude filters and merges matching override options, caching the result
+	* per `(options, node)` pair. Returns `null` when the node is filtered out.
+	*/
+	#resolveOptions(node, context) {
+		const { options } = context;
+		if (typeof options !== "object" || options === null) return Resolver.#computeOptions(node, context);
+		let byOptions = Resolver.#optionsCache.get(options);
+		if (!byOptions) {
+			byOptions = /* @__PURE__ */ new WeakMap();
+			Resolver.#optionsCache.set(options, byOptions);
+		}
+		const cached = byOptions.get(node);
+		if (cached) return cached.value;
+		const result = Resolver.#computeOptions(node, context);
+		byOptions.set(node, { value: result });
+		return result;
+	}
+	/**
+	* A custom `group.name` wins; otherwise `tag` groups use the camelCased tag and `path`
+	* groups use the first non-traversal segment (`''` when none remain, placing the file in
+	* the output root, kept safe by the caller's boundary check).
+	*/
+	static #resolveGroupDir(group, groupValue) {
+		if (group.name) return group.name({ group: groupValue });
+		if (group.type === "tag") return camelCase(groupValue);
+		const segment = groupValue.split("/").filter((part) => part !== "" && part !== "." && part !== "..")[0];
+		return segment ? camelCase(segment) : "";
+	}
+	/**
+	* `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 !== "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}`;
+		if (result !== outputDir && !result.startsWith(outputDirWithSep)) throw new Diagnostics.Error({
+			code: Diagnostics.code.pathTraversal,
+			severity: "error",
+			message: `Resolved path "${result}" is outside the output directory "${outputDir}".`,
+			help: "This can stem from a path traversal in the OpenAPI specification or a misconfigured `group.name` function. Keep generated paths within the output directory.",
+			location: { kind: "config" }
+		});
+		return result;
+	}
+	/**
+	* Resolves a resolver-supplied full path (`file.path`) against `root`, bypassing `output.path`
+	* and `group`. The path may not escape `root`, which keeps a `file.path` that interpolates
+	* spec-derived values from writing outside the project.
+	*/
+	#resolveOverridePath(filePath, root) {
+		const resolved = path.resolve(root, filePath);
+		const rootWithSep = root.endsWith(path.sep) ? root : `${root}${path.sep}`;
+		if (resolved !== root && !resolved.startsWith(rootWithSep)) throw new Diagnostics.Error({
+			code: Diagnostics.code.pathTraversal,
+			severity: "error",
+			message: `Resolved path "${resolved}" is outside the project root "${root}".`,
+			help: "A resolver `file.path` must return a path inside the project root.",
+			location: { kind: "config" }
+		});
+		return resolved;
+	}
+	/**
+	* Builds a `FileNode`. When `#filePath` (the resolver's `file.path`) is set it owns the whole
+	* path; otherwise the base name (from `#baseName`, the resolver's `file.baseName` or the
+	* built-in `toBaseName`) is placed by the `output.path`/`group` layout. The resolved file starts
+	* with empty `sources`, `imports`, and `exports`, which consumers populate separately.
+	*/
+	#resolveFile(options) {
+		const { name, extname, tag, path: groupPath, root, output, group } = options;
+		const baseName = this.#baseName({
+			name,
+			extname
+		});
+		const filePath = this.#filePath ? this.#resolveOverridePath(this.#filePath({
+			baseName,
+			output
+		}), root) : this.#resolvePath({
+			baseName,
+			tag,
+			path: groupPath,
+			root,
+			output,
+			group
+		});
+		return ast.factory.createFile({
+			path: filePath,
+			baseName: path.basename(filePath),
+			meta: { pluginName: this.pluginName },
+			sources: [],
+			imports: [],
+			exports: []
+		});
+	}
+	/**
+	* Missing fields default to empty/`false` so the `BannerMeta` shape stays stable even when
+	* a caller (e.g. the barrel plugin) has no document metadata.
+	*/
+	static #buildBannerMeta(meta, file) {
+		return {
+			title: meta?.title,
+			description: meta?.description,
+			version: meta?.version,
+			baseURL: meta?.baseURL,
+			circularNames: meta?.circularNames ?? [],
+			enumNames: meta?.enumNames ?? [],
+			filePath: file?.path ?? "",
+			baseName: file?.baseName ?? "",
+			isBarrel: file?.isBarrel ?? false,
+			isAggregation: file?.isAggregation ?? false
+		};
+	}
+	/**
+	* Resolves a user-configured banner/footer value. `undefined` means not configured.
+	*/
+	static #resolveUserText(value, meta, file) {
+		if (typeof value === "function") return value(Resolver.#buildBannerMeta(meta, file));
+		if (typeof value === "string") return value;
+	}
+	static #buildDefaultBanner({ title, version, config }) {
+		const lines = [
+			"/**",
+			"* Generated by Kubb (https://kubb.dev/).",
+			"* Do not edit manually."
+		];
+		if (config.output.defaultBanner !== "simple") {
+			const input = config.input;
+			let source = "";
+			if (typeof input === "string") source = getInputKind(input) === "inline" ? "text content" : path.basename(input);
+			else if (input) source = "text content";
+			if (source) lines.push(`* Source: ${source}`);
+			if (title) lines.push(`* Title: ${title}`);
+			if (version) lines.push(`* OpenAPI spec version: ${version}`);
+		}
+		return `${lines.join("\n")}\n*/\n`;
+	}
+	/**
+	* A user-supplied `output.banner` overrides the default Kubb notice. When
+	* `config.output.defaultBanner` is `false` and no user banner is set, returns `null`.
+	*/
+	#resolveBanner(meta, { output, config, file }) {
+		const userBanner = Resolver.#resolveUserText(output?.banner, meta, file);
+		if (userBanner !== void 0) return userBanner;
+		if (config.output.defaultBanner === false) return null;
+		return Resolver.#buildDefaultBanner({
+			title: meta?.title,
+			version: meta?.version,
+			config
+		});
+	}
+	#resolveFooter(meta, { output, file }) {
+		return Resolver.#resolveUserText(output?.footer, meta, file) ?? null;
+	}
+};
 //#endregion
-//#region src/FileProcessor.ts
-function joinSources(file) {
-	return file.sources.map((item) => extractStringsFromNodes(item.nodes)).filter(Boolean).join("\n\n");
+//#region src/createResolver.ts
+/**
+* Defines a plugin resolver, the object that decides what every generated symbol and file
+* path is called. Override the top-level `name` and `file` to set the plugin's conventions,
+* and add your own naming helpers, top-level (`typeName`, …) or grouped in namespaces
+* (`query`, `schema`, …). Every method reaches sibling helpers and the built-in machinery
+* through `this.name`, `this.file`, and `this.default`.
+*
+* @example Custom identifier casing
+* ```ts
+* export const resolverTs = createResolver<PluginTs>({
+*   pluginName: 'plugin-ts',
+*   name(name) {
+*     return ensureValidVarName(pascalCase(name))
+*   },
+* })
+* ```
+*
+* @example Rename generated files with `file.baseName`
+* ```ts
+* export const resolverFaker = createResolver<PluginFaker>({
+*   pluginName: 'plugin-faker',
+*   name(name) {
+*     return camelCase(name, { prefix: 'create' })
+*   },
+*   file: {
+*     baseName({ name, extname }) {
+*       return `${camelCase(name, { prefix: 'create' })}${extname}`
+*     },
+*   },
+* })
+* ```
+*
+* @example Own the full path with `file.path`
+* ```ts
+* export const resolverFaker = createResolver<PluginFaker>({
+*   pluginName: 'plugin-faker',
+*   file: {
+*     path({ baseName, output }) {
+*       return `${output.path}/mocks/${baseName}`
+*     },
+*   },
+* })
+* ```
+*/
+function createResolver(options) {
+	return new Resolver(options);
 }
+//#endregion
+//#region src/Transform.ts
 /**
-* Converts a single file to a string using the registered parsers.
-* Falls back to joining source values when no matching parser is found.
+* Holds an ordered list of macros per plugin, keyed by plugin name. Each plugin's macros run in
+* isolation on the original adapter node and are composed into a single `Visitor` that the
+* `@kubb/ast` `transform` primitive applies. `applyTo` is a per-plugin lookup, not a cross-plugin
+* chain, so plugin A's macros never see plugin B's output. When a plugin has no macros, `applyTo`
+* returns the original node reference, and `transform` does the same when the composed visitor
+* leaves the tree untouched, so callers can detect a no-op by identity.
 *
-* @internal
+* Registration order matches the order setup hooks fire, which the driver has already sorted by
+* `enforce` and dependency edges. The registry preserves that order. Macro `enforce` only reorders
+* within a single plugin's list.
 */
-var FileProcessor = class {
-	events = new AsyncEventEmitter();
-	#limit = pLimit(16);
-	async parse(file, { parsers, extension } = {}) {
-		const parseExtName = extension?.[file.extname] || void 0;
-		if (!parsers || !file.extname) return joinSources(file);
-		const parser = parsers.get(file.extname);
-		if (!parser) return joinSources(file);
-		return parser.parse(file, { extname: parseExtName });
-	}
-	async run(files, { parsers, mode = "sequential", extension } = {}) {
-		await this.events.emit("start", files);
-		const total = files.length;
-		let processed = 0;
-		const processOne = async (file) => {
-			const source = await this.parse(file, {
-				extension,
-				parsers
+var Transform = class {
+	#macros = /* @__PURE__ */ new Map();
+	#composed = /* @__PURE__ */ new Map();
+	#memo = /* @__PURE__ */ new Map();
+	/**
+	* Appends `macro` to the plugin's list, after any macros already registered.
+	*/
+	add(pluginName, macro) {
+		const list = this.#macros.get(pluginName);
+		if (list) list.push(macro);
+		else this.#macros.set(pluginName, [macro]);
+		this.#invalidate(pluginName);
+	}
+	/**
+	* Replaces the plugin's macro list with `macros`.
+	*/
+	set(pluginName, macros) {
+		this.#macros.set(pluginName, [...macros]);
+		this.#invalidate(pluginName);
+	}
+	/**
+	* Runs the plugin's macros on `node`. Returns the original node reference when the plugin has no
+	* macros, so callers can compare by identity to detect a no-op.
+	*/
+	applyTo(pluginName, node) {
+		const visitor = this.#visitorFor(pluginName);
+		if (!visitor) return node;
+		let memo = this.#memo.get(pluginName);
+		if (!memo) {
+			memo = /* @__PURE__ */ new WeakMap();
+			this.#memo.set(pluginName, memo);
+		}
+		const cached = memo.get(node);
+		if (cached) return cached;
+		const result = transform(node, visitor);
+		memo.set(node, result);
+		return result;
+	}
+	/**
+	* Clears every registration. Called from the driver's `dispose()` so macros do not leak across
+	* builds.
+	*/
+	dispose() {
+		this.#macros.clear();
+		this.#composed.clear();
+		this.#memo.clear();
+	}
+	#invalidate(pluginName) {
+		this.#composed.delete(pluginName);
+		this.#memo.delete(pluginName);
+	}
+	#visitorFor(pluginName) {
+		const macros = this.#macros.get(pluginName);
+		if (!macros || macros.length === 0) return void 0;
+		let composed = this.#composed.get(pluginName);
+		if (!composed) {
+			composed = composeMacros(macros);
+			this.#composed.set(pluginName, composed);
+		}
+		return composed;
+	}
+};
+//#endregion
+//#region src/KubbDriver.ts
+const ENFORCE_ORDER = {
+	pre: -1,
+	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;
+	/**
+	* The `InputNode` produced by the adapter. Set after adapter setup.
+	*/
+	inputNode = null;
+	adapter = null;
+	/**
+	* Raw adapter source so `adapter.parse()` can run lazily.
+	* Intentionally outlives the build, cleared by `dispose()`.
+	*/
+	#adapterSource = null;
+	/**
+	* Central file store for all generated files.
+	* Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
+	* add files. This property gives direct read/write access when needed.
+	*/
+	fileManager = new FileManager();
+	plugins = /* @__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.
+	*/
+	#unhooks = [];
+	/**
+	* Transform registry. Plugins populate it during `kubb:plugin:setup` via `addMacro`/`setMacros`,
+	* and `#runGenerators` reads it once per `(plugin, node)` pair through `applyTo`.
+	*/
+	#transforms = new Transform();
+	constructor(config, options) {
+		this.config = config;
+		this.options = options;
+		this.adapter = config.adapter ?? null;
+	}
+	/**
+	* Normalizes every configured plugin, orders them, and registers their lifecycle handlers.
+	* A plugin that another lists as a dependency runs first, then `enforce: 'pre'` before
+	* `'post'`. When the config has an adapter, the adapter source is resolved from the input
+	* so `run` can parse it later.
+	*/
+	async setup() {
+		const normalized = this.#sortPlugins(this.config.plugins.map((rawPlugin) => {
+			return {
+				name: rawPlugin.name,
+				dependencies: rawPlugin.dependencies,
+				enforce: rawPlugin.enforce,
+				hooks: rawPlugin.hooks,
+				options: rawPlugin.options ?? defaultPluginOptions(),
+				resolver: createResolver({ pluginName: rawPlugin.name })
+			};
+		}));
+		for (const plugin of normalized) {
+			this.#registerPlugin(plugin);
+			this.plugins.set(plugin.name, plugin);
+		}
+		if (this.config.adapter) this.#adapterSource = inputToAdapterSource(this.config);
+	}
+	/**
+	* Orders plugins so every dependency runs before its dependents (Kahn's algorithm), with
+	* `enforce` (`'pre'` before normal before `'post'`) and declaration order as tiebreaks.
+	* A pairwise `Array.sort` comparator cannot do this: dependency relations are not transitive
+	* at the comparator level, so a chain where A depends on B and B depends on C could come out
+	* wrong when A and C are never compared directly. Dependencies on plugins missing from the
+	* config are ignored here and surface later through `requirePlugin`.
+	*/
+	#sortPlugins(plugins) {
+		const queue = [...plugins].sort((a, b) => enforceWeight(a) - enforceWeight(b));
+		const names = new Set(queue.map((plugin) => plugin.name));
+		const blockedBy = new Map(queue.map((plugin) => [plugin.name, new Set(plugin.dependencies?.filter((name) => names.has(name) && name !== plugin.name))]));
+		const sorted = [];
+		for (const _ of plugins) {
+			const index = queue.findIndex((plugin) => blockedBy.get(plugin.name)?.size === 0);
+			if (index === -1) throw new Diagnostics.Error({
+				code: Diagnostics.code.invalidPluginOptions,
+				severity: "error",
+				message: `Plugin dependencies form a cycle: ${queue.map((plugin) => plugin.name).join(" → ")}.`,
+				help: "Remove one of the `dependencies` entries so the plugins can be ordered.",
+				location: { kind: "config" }
 			});
-			const currentProcessed = ++processed;
-			const percentage = currentProcessed / total * 100;
-			await this.events.emit("update", {
-				file,
-				source,
-				processed: currentProcessed,
-				percentage,
-				total
+			const [plugin] = queue.splice(index, 1);
+			if (!plugin) break;
+			sorted.push(plugin);
+			for (const blockers of blockedBy.values()) blockers.delete(plugin.name);
+		}
+		return sorted;
+	}
+	get hooks() {
+		return this.options.hooks;
+	}
+	/**
+	* Parses the adapter source into `this.inputNode`. Idempotent, so repeated calls from
+	* `run` do not re-parse.
+	*/
+	async #parseInput() {
+		if (this.inputNode || !this.adapter || !this.#adapterSource) return;
+		this.inputNode = await this.adapter.parse(this.#adapterSource);
+	}
+	/**
+	* Registers a plugin's lifecycle hooks on the shared `Hookable` as pass-through listeners that
+	* external tooling can observe via `hooks.hook(...)`. The returned remover is tracked for
+	* `dispose`. `kubb:plugin:setup` is skipped here; `setupHooks` invokes it directly with a
+	* plugin-scoped context.
+	*
+	* @internal
+	*/
+	#registerPlugin(plugin) {
+		const { hooks } = plugin;
+		if (!hooks) return;
+		const { "kubb:plugin:setup": _setup, ...configHooks } = hooks;
+		this.#unhooks.push(this.hooks.addHooks(configHooks));
+	}
+	/**
+	* Runs each plugin's `kubb:plugin:setup` handler, in plugin order, with a context scoped to that
+	* plugin so `addGenerator`, `setResolver`, `addMacro`, `setMacros`, and `setOptions` target its
+	* `NormalizedPlugin` entry. Called once from `run` before the plugin execution loop begins, so
+	* plugins can configure generators, resolvers, macros, and options before `buildStart`.
+	*/
+	async setupHooks() {
+		for (const plugin of this.plugins.values()) {
+			const setup = plugin.hooks?.["kubb:plugin:setup"];
+			if (!setup) continue;
+			await setup({
+				config: this.config,
+				options: plugin.options ?? {},
+				addGenerator: (...generators) => {
+					for (const generator of generators) this.registerGenerator(plugin.name, generator);
+				},
+				setResolver: (resolver) => {
+					this.setPluginResolver(plugin.name, resolver);
+				},
+				addMacro: (macro) => {
+					this.#transforms.add(plugin.name, macro);
+				},
+				setMacros: (macros) => {
+					this.#transforms.set(plugin.name, macros);
+				},
+				setOptions: (opts) => {
+					plugin.options = {
+						...plugin.options,
+						...opts
+					};
+					if (plugin.options.output) {
+						const group = "group" in plugin.options ? plugin.options.group : void 0;
+						plugin.options.output = normalizeOutput({
+							output: plugin.options.output,
+							group,
+							pluginName: plugin.name
+						});
+					}
+				},
+				injectFile: (userFileNode) => {
+					this.fileManager.add(ast.factory.createFile(userFileNode));
+				}
+			});
+		}
+	}
+	/**
+	* Appends a generator to its owning plugin so the generate loop can call it directly.
+	*
+	* 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 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 run the generators
+	* for a plugin.
+	*/
+	hasHookGenerators(pluginName) {
+		return (this.plugins.get(pluginName)?.generators?.length ?? 0) > 0;
+	}
+	/**
+	* Runs the full plugin pipeline. Returns the diagnostics collected so far even
+	* when an outer hook throws, since the orchestrator preserves partial state by capturing
+	* the failure as a {@link Diagnostic} instead of propagating. Each plugin also
+	* contributes a `timing` diagnostic for the run summary.
+	*/
+	async run() {
+		const { hooks, config, fileManager } = this;
+		const diagnostics = [];
+		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: ({ file, processed, total, percentage }) => {
+				updateBuffer.push({
+					file,
+					processed,
+					total,
+					percentage,
+					config
+				});
+			},
+			end: async (files) => {
+				updateBuffer.sort((a, b) => a.processed - b.processed);
+				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer });
+				updateBuffer.length = 0;
+				await hooks.callHook("kubb:files:processing:end", { files });
+			}
+		});
+		return Diagnostics.scope((diagnostic) => diagnostics.push(diagnostic), async () => {
+			try {
+				const outputRoot = resolve(config.root, config.output.path);
+				await this.#parseInput();
+				await this.setupHooks();
+				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);
+					const hrStart = process.hrtime();
+					try {
+						await hooks.callHook("kubb:plugin:start", { plugin });
+					} catch (caughtError) {
+						const error = toError(caughtError);
+						const duration = getElapsedMs(hrStart);
+						await this.#emitPluginEnd({
+							plugin,
+							duration,
+							success: false,
+							error
+						});
+						diagnostics.push({
+							...Diagnostics.from(error),
+							plugin: plugin.name
+						}, Diagnostics.performance({
+							plugin: plugin.name,
+							duration
+						}));
+						continue;
+					}
+					if (this.hasHookGenerators(plugin.name)) {
+						generatorPlugins.push({
+							plugin,
+							context,
+							hrStart
+						});
+						continue;
+					}
+					const duration = getElapsedMs(hrStart);
+					diagnostics.push(Diagnostics.performance({
+						plugin: plugin.name,
+						duration
+					}));
+					await this.#emitPluginEnd({
+						plugin,
+						duration,
+						success: true
+					});
+				}
+				diagnostics.push(...await this.#runGenerators(generatorPlugins));
+				await hooks.callHook("kubb:plugins:end", this.#withFiles({ config }));
+				await fileManager.write(fileManager.files, {
+					storage: config.storage,
+					parsers: parsersMap,
+					manifest: this.options.manifest
+				});
+				await hooks.callHook("kubb:build:end", {
+					files: this.fileManager.files,
+					config,
+					outputDir: outputRoot
+				});
+				return { diagnostics: Diagnostics.dedupe(diagnostics) };
+			} catch (caughtError) {
+				diagnostics.push(Diagnostics.from(caughtError));
+				return { diagnostics: Diagnostics.dedupe(diagnostics) };
+			} finally {
+				unhookWrites();
+			}
+		});
+	}
+	/**
+	* 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 {
+			...extra,
+			files: this.fileManager.files,
+			upsertFile: (...files) => this.fileManager.upsert(...files)
+		};
+	}
+	#emitPluginEnd({ plugin, duration, success, error }) {
+		return this.hooks.callHook("kubb:plugin:end", this.#withFiles({
+			plugin,
+			duration,
+			success,
+			...error ? { error } : {},
+			config: this.config
+		}));
+	}
+	/**
+	* 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`.
+	*
+	* 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.
+	*/
+	async #runGenerators(entries) {
+		const diagnostics = [];
+		if (entries.length === 0) return diagnostics;
+		if (!this.inputNode) {
+			for (const { plugin, hrStart } of entries) {
+				const duration = getElapsedMs(hrStart);
+				diagnostics.push(Diagnostics.performance({
+					plugin: plugin.name,
+					duration
+				}));
+				await this.#emitPluginEnd({
+					plugin,
+					duration,
+					success: true
+				});
+			}
+			return diagnostics;
+		}
+		const transforms = this.#transforms;
+		const { schemas, operations } = this.inputNode;
+		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;
+			const resolver = this.getResolver(plugin.name);
+			const includedOps = operations.filter((operation) => resolver.default.options(operation, {
+				options: plugin.options,
+				exclude,
+				include,
+				override
+			}) !== null);
+			allowedSchemaNamesByPlugin.set(plugin.name, collectUsedSchemaNames(includedOps, schemas));
+		}
+		const states = entries.map(({ plugin, context, hrStart }) => {
+			const generatorContext = {
+				...context,
+				resolver: this.getResolver(plugin.name)
+			};
+			const { exclude, include, override } = plugin.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
+			};
+		});
+		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
+			};
 		};
-		if (mode === "sequential") for (const file of files) await processOne(file);
-		else await Promise.all(files.map((file) => this.#limit(() => processOne(file))));
-		await this.events.emit("end", files);
-		return files;
+		for (const node of schemas) {
+			const cache = createNodeCache();
+			for (const state of states) {
+				if (state.error || !state.schemaGenerators.length) continue;
+				try {
+					const resolved = resolveForPlugin(state, node);
+					if (!resolved) continue;
+					const { transformedNode, options } = resolved;
+					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) {
+					state.error = toError(caughtError);
+				}
+			}
+		}
+		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(state, node);
+					if (!resolved) continue;
+					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) {
+					state.error = toError(caughtError);
+				}
+			}
+		}
+		for (const state of states) {
+			if (state.error || !state.operationsGenerators.length) continue;
+			try {
+				const ctx = {
+					...state.generatorContext,
+					options: state.plugin.options,
+					cache: createNodeCache()
+				};
+				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) {
+				state.error = toError(caughtError);
+			}
+		}
+		for (const state of states) {
+			const duration = getElapsedMs(state.hrStart);
+			await this.#emitPluginEnd({
+				plugin: state.plugin,
+				duration,
+				success: !state.error,
+				error: state.error ?? void 0
+			});
+			if (state.error) diagnostics.push({
+				...Diagnostics.from(state.error),
+				plugin: state.plugin.name
+			});
+			diagnostics.push(Diagnostics.performance({
+				plugin: state.plugin.name,
+				duration
+			}));
+		}
+		return diagnostics;
+	}
+	/**
+	* Stores whatever a generator method or `kubb:generate:*` hook returned.
+	*
+	* - An `Array<FileNode>` goes straight into `fileManager` via `upsert`.
+	* - A renderer element runs through `renderer` (the renderer factory, e.g. JSX) and the
+	*   produced files go to `fileManager.upsert`.
+	* - A falsy result is treated as a no-op. The generator wrote files itself via
+	*   `ctx.upsertFile`.
+	*
+	* Pass `renderer` when the result may be a renderer element. Generators that only return
+	* `Array<FileNode>` do not need one.
+	*/
+	async dispatch({ result, renderer }) {
+		try {
+			var _usingCtx$2 = _usingCtx();
+			if (!result) return;
+			if (Array.isArray(result)) {
+				this.fileManager.upsert(...result);
+				return;
+			}
+			if (!renderer) return;
+			const instance = _usingCtx$2.u(renderer());
+			await instance.render(result);
+			this.fileManager.upsert(...instance.files);
+		} catch (_) {
+			_usingCtx$2.e = _;
+		} finally {
+			_usingCtx$2.d();
+		}
+	}
+	/**
+	* Removes every listener the driver added. Listeners attached directly to `hooks` from outside
+	* the driver survive. Called at the end of a build to prevent leaks across repeated builds.
+	*
+	* @internal
+	*/
+	dispose() {
+		for (const unhook of this.#unhooks) unhook();
+		this.#unhooks.length = 0;
+		this.#transforms.dispose();
+		this.fileManager.dispose();
+		this.inputNode = null;
+		this.#adapterSource = null;
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	/**
+	* 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 plugin = this.plugins.get(pluginName);
+		if (!plugin) return;
+		plugin.resolver = Resolver.merge(createResolver({ pluginName }), partial);
+	}
+	getResolver(pluginName) {
+		return this.plugins.get(pluginName)?.resolver ?? createResolver({ pluginName });
+	}
+	getContext(plugin) {
+		const driver = this;
+		const report = (diagnostic) => {
+			Diagnostics.report({
+				...diagnostic,
+				plugin: plugin.name
+			});
+		};
+		return {
+			config: driver.config,
+			get root() {
+				return resolve(driver.config.root, driver.config.output.path);
+			},
+			hooks: driver.hooks,
+			plugin,
+			getPlugin: driver.getPlugin.bind(driver),
+			requirePlugin: ((name) => driver.requirePlugin(name, { requiredBy: plugin.name })),
+			getResolver: driver.getResolver.bind(driver),
+			driver,
+			addFile: async (...files) => {
+				driver.fileManager.add(...files);
+			},
+			upsertFile: async (...files) => {
+				driver.fileManager.upsert(...files);
+			},
+			get meta() {
+				return driver.inputNode?.meta ?? {
+					circularNames: [],
+					enumNames: []
+				};
+			},
+			get adapter() {
+				return driver.adapter;
+			},
+			get resolver() {
+				return driver.getResolver(plugin.name);
+			},
+			warn(message) {
+				report({
+					code: Diagnostics.code.pluginWarning,
+					severity: "warning",
+					message
+				});
+			},
+			error(error) {
+				const cause = typeof error === "string" ? void 0 : error;
+				report({
+					code: Diagnostics.code.pluginFailed,
+					severity: "error",
+					message: typeof error === "string" ? error : error.message,
+					cause
+				});
+			},
+			info(message) {
+				report({
+					code: Diagnostics.code.pluginInfo,
+					severity: "info",
+					message
+				});
+			}
+		};
+	}
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName);
+	}
+	requirePlugin(pluginName, context) {
+		const plugin = this.getPlugin(pluginName);
+		if (plugin) return plugin;
+		const requiredBy = context?.requiredBy;
+		const by = requiredBy ? ` by "${requiredBy}"` : "";
+		const help = requiredBy ? ` (required by "${requiredBy}")` : "";
+		throw new Diagnostics.Error({
+			code: Diagnostics.code.pluginNotFound,
+			severity: "error",
+			message: `Plugin "${pluginName}" is required${by} but not found. Make sure it is included in your Kubb config.`,
+			help: `Add "${pluginName}" to the \`plugins\` array in kubb.config.ts${help}, or remove the dependency on it.`,
+			location: { kind: "config" }
+		});
 	}
 };
 //#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
+* returns a `Storage` implementation. Kubb ships with filesystem and in-memory
+* storages. A custom backend writes generated files elsewhere, such as cloud
+* storage or a database.
+*
+* @example In-memory storage (the built-in implementation)
+* ```ts
+* import { createStorage } from '@kubb/core'
+*
+* export const memoryStorage = createStorage(() => {
+*   const store = new Map<string, string>()
+*
+*   return {
+*     name: 'memory',
+*     async existsItem(key) {
+*       return store.has(key)
+*     },
+*     async readItem(key) {
+*       return store.get(key) ?? null
+*     },
+*     async writeItem(key, value) {
+*       store.set(key, value)
+*     },
+*     async removeItem(key) {
+*       store.delete(key)
+*     },
+*     async readKeys(base) {
+*       const keys = [...store.keys()]
+*       return base ? keys.filter((k) => k.startsWith(base)) : keys
+*     },
+*     async empty(base) {
+*       if (!base) store.clear()
+*     },
+*   }
+* })
+* ```
+*/
+function createStorage(build) {
+	return (options) => build(options ?? {});
+}
+//#endregion
 //#region src/storages/fsStorage.ts
+const WRITE_CONCURRENCY = 50;
+function createLimiter(concurrency) {
+	let active = 0;
+	const queue = [];
+	function next() {
+		if (active >= concurrency) return;
+		const run = queue.shift();
+		if (!run) return;
+		active++;
+		run();
+	}
+	return function limit(task) {
+		return new Promise((resolve, reject) => {
+			queue.push(() => {
+				task().then(resolve, reject).finally(() => {
+					active--;
+					next();
+				});
+			});
+			next();
+		});
+	};
+}
 /**
 * Built-in filesystem storage driver.
 *
@@ -748,11 +1996,14 @@ var FileProcessor = class {
 * Keys are resolved against `process.cwd()`, so root-relative paths such as
 * `src/gen/api/getPets.ts` are written to the correct location without extra configuration.
 *
-* Internally uses the `write` utility from `@internals/utils`, which:
-* - trims leading/trailing whitespace before writing
-* - skips the write when file content is already identical (deduplication)
-* - creates missing parent directories automatically
-* - supports Bun's native file API when running under Bun
+* Writes are deduplicated and directory-safe:
+* - leading and trailing whitespace is trimmed before writing
+* - the write is skipped when the file already holds that content, ignoring any trailing newline
+*   a formatter left behind
+* - missing parent directories are created automatically
+* - Bun's native file API is used when running under Bun
+* - concurrent `writeItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller
+*   can fire every file's write without pacing itself
 *
 * @example
 * ```ts
@@ -760,677 +2011,672 @@ var FileProcessor = class {
 * import { defineConfig } from 'kubb'
 *
 * export default defineConfig({
-*   input:  { path: './petStore.yaml' },
+*   input:  './petStore.yaml',
 *   output: { path: './src/gen' },
 *   storage: fsStorage(),
 * })
 * ```
 */
-const fsStorage = createStorage(() => ({
-	name: "fs",
-	async hasItem(key) {
-		try {
-			await access(resolve(key));
-			return true;
-		} catch (_error) {
-			return false;
-		}
-	},
-	async getItem(key) {
-		try {
-			return await readFile(resolve(key), "utf8");
-		} catch (_error) {
-			return null;
-		}
-	},
-	async setItem(key, value) {
-		await write(resolve(key), value, { sanity: false });
-	},
-	async removeItem(key) {
-		await rm(resolve(key), { force: true });
-	},
-	async getKeys(base) {
-		const keys = [];
-		const resolvedBase = resolve(base ?? process.cwd());
-		async function walk(dir, prefix) {
-			let entries;
+const fsStorage = createStorage(() => {
+	const limit = createLimiter(WRITE_CONCURRENCY);
+	return {
+		name: "fs",
+		async existsItem(key) {
 			try {
-				entries = await readdir(dir, { withFileTypes: true });
+				await access(resolve(key));
+				return true;
 			} catch (_error) {
-				return;
+				return false;
 			}
-			for (const entry of entries) {
-				const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-				if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
-				else keys.push(rel);
+		},
+		async readItem(key) {
+			try {
+				return await readFile(resolve(key), "utf8");
+			} catch (_error) {
+				return null;
 			}
+		},
+		async writeItem(key, value) {
+			await limit(() => write(resolve(key), value, { sanity: false }));
+		},
+		async removeItem(key) {
+			await rm(resolve(key), { force: true });
+		},
+		async readKeys(base) {
+			const resolvedBase = resolve(base ?? process.cwd());
+			const keys = [];
+			try {
+				for await (const entry of glob("**/*", {
+					cwd: resolvedBase,
+					withFileTypes: true
+				})) if (entry.isFile()) keys.push(toPosixPath(relative(resolvedBase, join(entry.parentPath, entry.name))));
+			} catch (_error) {}
+			return keys;
+		},
+		async empty(base) {
+			if (!base) return;
+			await clean(resolve(base));
 		}
-		await walk(resolvedBase, "");
-		return keys;
-	},
-	async clear(base) {
-		if (!base) return;
-		await clean(resolve(base));
-	}
-}));
+	};
+});
 //#endregion
-//#region src/createKubb.ts
+//#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));
+}
 /**
-* Builds a `Storage` view scoped to the file paths produced by the current build.
+* 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.
 *
-* Reads delegate to the underlying `storage` (typically `fsStorage()`) so source bytes
-* stay where they were written instead of being held in an extra in-memory map.
-* Writing via `setItem` stores the content in the underlying storage and registers the
-* key so subsequent reads and `getKeys` are scoped to this build's output.
+* @example
+* ```ts
+* const cache = cacheStorage({ root: config.root })
+* await cache.writeItem('output-manifest.json', JSON.stringify(entries))
+* ```
 */
-function createSourcesView(storage) {
-	const paths = /* @__PURE__ */ new Set();
-	return createStorage(() => ({
-		name: `${storage.name}:sources`,
-		async hasItem(key) {
-			return paths.has(key) && await storage.hasItem(key);
+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 getItem(key) {
-			return paths.has(key) ? storage.getItem(key) : null;
+		async readItem(key) {
+			return storage.readItem(toPath(key));
 		},
-		async setItem(key, value) {
-			paths.add(key);
-			await storage.setItem(key, value);
+		async writeItem(key, value) {
+			return storage.writeItem(toPath(key), value);
 		},
 		async removeItem(key) {
-			paths.delete(key);
-			await storage.removeItem(key);
+			return storage.removeItem(toPath(key));
 		},
-		async getKeys(base) {
-			if (!base) return [...paths];
-			const result = [];
-			for (const key of paths) if (key.startsWith(base)) result.push(key);
-			return result;
+		async readKeys(base) {
+			return storage.readKeys(base ? toPath(base) : dir);
 		},
-		async clear() {
-			paths.clear();
-			await storage.clear();
+		async empty(base) {
+			if (!base) return;
+			return storage.empty(toPath(base));
 		}
-	}))();
-}
-async function setup(userConfig, options = {}) {
-	const hooks = options.hooks ?? new AsyncEventEmitter();
-	const config = {
+	};
+});
+//#endregion
+//#region src/createKubb.ts
+function resolveConfig(userConfig) {
+	return {
 		...userConfig,
 		root: userConfig.root || process.cwd(),
 		parsers: userConfig.parsers ?? [],
-		adapter: userConfig.adapter,
 		output: {
 			format: false,
 			lint: false,
-			extension: DEFAULT_EXTENSION,
-			defaultBanner: DEFAULT_BANNER,
+			defaultBanner: "simple",
 			...userConfig.output
 		},
 		storage: userConfig.storage ?? fsStorage(),
-		devtools: userConfig.devtools ? {
-			studioUrl: DEFAULT_STUDIO_URL,
-			...typeof userConfig.devtools === "boolean" ? {} : userConfig.devtools
-		} : void 0,
+		reporters: userConfig.reporters ?? [],
 		plugins: userConfig.plugins ?? []
 	};
-	const driver = new PluginDriver(config, { hooks });
-	const storage = createSourcesView(config.storage);
-	const diagnosticInfo = getDiagnosticInfo();
-	await hooks.emit("kubb:debug", {
-		date: /* @__PURE__ */ new Date(),
-		logs: [
-			"Configuration:",
-			`  • Name: ${userConfig.name || "unnamed"}`,
-			`  • Root: ${userConfig.root || process.cwd()}`,
-			`  • Output: ${userConfig.output?.path || "not specified"}`,
-			`  • Plugins: ${userConfig.plugins?.length || 0}`,
-			"Output Settings:",
-			`  • Storage: ${config.storage.name}`,
-			`  • Formatter: ${userConfig.output?.format || "none"}`,
-			`  • Linter: ${userConfig.output?.lint || "none"}`,
-			"Environment:",
-			Object.entries(diagnosticInfo).map(([key, value]) => `  • ${key}: ${value}`).join("\n")
-		]
-	});
-	try {
-		if (isInputPath(userConfig) && !new URLPath(userConfig.input.path).isURL) {
-			await exists(userConfig.input.path);
-			await hooks.emit("kubb:debug", {
-				date: /* @__PURE__ */ new Date(),
-				logs: [`✓ Input file validated: ${userConfig.input.path}`]
-			});
-		}
-	} catch (caughtError) {
-		if (isInputPath(userConfig)) {
-			const error = caughtError;
-			throw new Error(`Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${userConfig.input.path}`, { cause: error });
-		}
-	}
-	if (config.output.clean) {
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: ["Cleaning output directories", `  • Output: ${config.output.path}`]
-		});
-		await config.storage.clear(resolve(config.root, config.output.path));
-	}
-	function registerMiddlewareHook(event, middlewareHooks) {
-		const handler = middlewareHooks[event];
-		if (handler) hooks.on(event, handler);
-	}
-	for (const middleware of config.middleware ?? []) for (const event of Object.keys(middleware.hooks)) registerMiddlewareHook(event, middleware.hooks);
-	if (config.adapter) {
-		const source = inputToAdapterSource(config);
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`Running adapter: ${config.adapter.name}`]
-		});
-		driver.adapter = config.adapter;
-		driver.inputNode = await config.adapter.parse(source);
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [
-				`✓ Adapter '${config.adapter.name}' resolved InputNode`,
-				`  • Schemas: ${driver.inputNode.schemas.length}`,
-				`  • Operations: ${driver.inputNode.operations.length}`
-			]
-		});
-	}
-	return {
-		config,
-		hooks,
-		driver,
-		storage
-	};
 }
 /**
-* Walks the AST and dispatches nodes to a plugin's direct AST hooks
-* (`schema`, `operation`, `operations`).
+* 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.
+*
+* `createKubb` takes a plain config object (the shape `defineConfig` produces),
+* not a fluent builder.
 *
-* When `include` contains only operation-scoped filters (`tag`, `operationId`, `path`,
-* `method`, `contentType`) and no `schemaName` filter, the function pre-computes the set
-* of top-level schema names transitively reachable from the included operations and skips
-* schemas that fall outside that set. This ensures that component schemas referenced
-* exclusively by excluded operations are not generated.
+* Attach hook listeners to `.hooks` before calling `setup()` or `build()`.
+*
+* @example
+* ```ts
+* const kubb = createKubb(userConfig)
+* kubb.hooks.hook('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
+* const { files, diagnostics } = await kubb.safeBuild()
+* ```
 */
-async function runPluginAstHooks(plugin, context) {
-	const { adapter, inputNode, resolver, driver } = context;
-	const { exclude, include, override } = plugin.options;
-	if (!adapter || !inputNode) throw new Error(`[${plugin.name}] No adapter found. Add an OAS adapter (e.g. adapterOas()) before this plugin in your Kubb config.`);
-	function resolveRenderer(gen) {
-		return gen.renderer === null ? void 0 : gen.renderer ?? plugin.renderer ?? context.config.renderer;
-	}
-	const generators = plugin.generators ?? [];
-	const collectedOperations = [];
-	const generatorContext = {
-		...context,
-		resolver: driver.getResolver(plugin.name)
-	};
-	const operationFilterTypes = new Set([
-		"tag",
-		"operationId",
-		"path",
-		"method",
-		"contentType"
-	]);
-	const hasOperationBasedIncludes = include?.some(({ type }) => operationFilterTypes.has(type)) ?? false;
-	const hasSchemaNameIncludes = include?.some(({ type }) => type === "schemaName") ?? false;
-	let allowedSchemaNames;
-	if (hasOperationBasedIncludes && !hasSchemaNameIncludes) allowedSchemaNames = collectUsedSchemaNames(inputNode.operations.filter((op) => resolver.resolveOptions(op, {
-		options: plugin.options,
-		exclude,
-		include,
-		override
-	}) !== null), inputNode.schemas);
-	await walk(inputNode, {
-		depth: "shallow",
-		async schema(node) {
-			const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node;
-			if (allowedSchemaNames !== void 0 && transformedNode.name && !allowedSchemaNames.has(transformedNode.name)) return;
-			const options = resolver.resolveOptions(transformedNode, {
-				options: plugin.options,
-				exclude,
-				include,
-				override
-			});
-			if (options === null) return;
-			const ctx = {
-				...generatorContext,
-				options
-			};
-			for (const gen of generators) {
-				if (!gen.schema) continue;
-				await applyHookResult(await gen.schema(transformedNode, ctx), driver, resolveRenderer(gen));
-			}
-			await driver.hooks.emit("kubb:generate:schema", transformedNode, ctx);
-		},
-		async operation(node) {
-			const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node;
-			const options = resolver.resolveOptions(transformedNode, {
-				options: plugin.options,
-				exclude,
-				include,
-				override
+var Kubb = class {
+	hooks;
+	config;
+	#driver = null;
+	#storage = null;
+	#manifest = null;
+	constructor(userConfig, options = {}) {
+		this.config = resolveConfig(userConfig);
+		this.hooks = options.hooks ?? new Hookable();
+	}
+	get storage() {
+		if (!this.#storage) throw new Error("[kubb] setup() must be called before accessing storage");
+		return this.#storage;
+	}
+	get driver() {
+		if (!this.#driver) throw new Error("[kubb] setup() must be called before accessing driver");
+		return this.#driver;
+	}
+	/**
+	* Initializes the driver and storage. `build()` calls this automatically.
+	*/
+	async setup() {
+		const config = this.config;
+		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);
+			if (isPathInside(config.root, cleanPath)) throw new Diagnostics.Error({
+				code: Diagnostics.code.cleanRoot,
+				severity: "error",
+				message: `output.clean cannot delete "${cleanPath}" because it is the project root or a parent of it.`,
+				help: "Point `output.path` at a subdirectory such as `./src/gen` so clean only removes generated code.",
+				location: { kind: "config" }
 			});
-			if (options !== null) {
-				collectedOperations.push(transformedNode);
-				const ctx = {
-					...generatorContext,
-					options
-				};
-				for (const gen of generators) {
-					if (!gen.operation) continue;
-					await applyHookResult(await gen.operation(transformedNode, ctx), driver, resolveRenderer(gen));
-				}
-				await driver.hooks.emit("kubb:generate:operation", transformedNode, ctx);
-			}
+			await config.storage.empty(cleanPath);
 		}
-	});
-	if (collectedOperations.length > 0) {
-		const ctx = {
-			...generatorContext,
-			options: plugin.options
-		};
-		for (const gen of generators) {
-			if (!gen.operations) continue;
-			await applyHookResult(await gen.operations(collectedOperations, ctx), driver, resolveRenderer(gen));
+		await driver.setup();
+		this.#driver = driver;
+		this.#storage = config.storage;
+		this.#manifest = manifest ?? null;
+	}
+	/**
+	* Runs the full pipeline and throws on any plugin error.
+	* Automatically calls `setup()` if needed.
+	*/
+	async build() {
+		const out = await this.safeBuild();
+		if (Diagnostics.hasError(out.diagnostics)) {
+			const errors = out.diagnostics.filter(Diagnostics.isProblem).filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.cause ?? new Diagnostics.Error(diagnostic));
+			throw new BuildError(`Build failed with ${errors.length} ${errors.length === 1 ? "error" : "errors"}`, { errors });
 		}
-		await driver.hooks.emit("kubb:generate:operations", collectedOperations, ctx);
+		return out;
 	}
-}
-async function safeBuild(setupResult) {
-	const { driver, hooks, storage } = setupResult;
-	const failedPlugins = /* @__PURE__ */ new Set();
-	const pluginTimings = /* @__PURE__ */ new Map();
-	const config = driver.config;
-	const writtenPaths = /* @__PURE__ */ new Set();
-	const parsersMap = /* @__PURE__ */ new Map();
-	for (const parser of config.parsers) if (parser.extNames) for (const extname of parser.extNames) parsersMap.set(extname, parser);
-	const fileProcessor = new FileProcessor();
-	fileProcessor.events.on("start", async (processingFiles) => {
-		await hooks.emit("kubb:files:processing:start", { files: processingFiles });
-	});
-	fileProcessor.events.on("update", async ({ file, source, processed, total, percentage }) => {
-		await hooks.emit("kubb:file:processing:update", {
-			file,
-			source,
-			processed,
-			total,
-			percentage,
-			config
-		});
-		if (source) await storage.setItem(file.path, source);
-	});
-	fileProcessor.events.on("end", async (processed) => {
-		await hooks.emit("kubb:files:processing:end", { files: processed });
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`✓ File write process completed for ${processed.length} files`]
-		});
-	});
-	async function flushPendingFiles() {
-		const files = driver.fileManager.files.filter((f) => !writtenPaths.has(f.path));
-		if (files.length === 0) return;
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`Writing ${files.length} files...`]
-		});
-		await fileProcessor.run(files, {
-			parsers: parsersMap,
-			mode: "parallel",
-			extension: config.output.extension
-		});
-		for (const file of files) writtenPaths.add(file.path);
+	/**
+	* Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
+	* Automatically calls `setup()` if needed. This is the canonical call: it never throws on
+	* plugin errors, so callers stay in control of how failures surface.
+	*/
+	async safeBuild() {
+		try {
+			var _usingCtx$1 = _usingCtx();
+			if (!this.#driver) await this.setup();
+			const self = _usingCtx$1.u(this);
+			const driver = self.driver;
+			const storage = self.storage;
+			const { diagnostics } = await driver.run();
+			return {
+				diagnostics,
+				files: driver.fileManager.files,
+				driver,
+				storage
+			};
+		} catch (_) {
+			_usingCtx$1.e = _;
+		} finally {
+			_usingCtx$1.d();
+		}
 	}
-	try {
-		await driver.emitSetupHooks();
-		if (driver.adapter && driver.inputNode) await hooks.emit("kubb:build:start", {
-			config,
-			adapter: driver.adapter,
-			inputNode: driver.inputNode,
-			getPlugin: driver.getPlugin.bind(driver),
-			get files() {
-				return driver.fileManager.files;
-			},
-			upsertFile: (...files) => driver.fileManager.upsert(...files)
-		});
-		for (const plugin of driver.plugins.values()) {
-			const context = driver.getContext(plugin);
-			const hrStart = process.hrtime();
-			try {
-				const timestamp = /* @__PURE__ */ new Date();
-				await hooks.emit("kubb:plugin:start", { plugin });
-				await hooks.emit("kubb:debug", {
-					date: timestamp,
-					logs: ["Starting plugin...", `  • Plugin Name: ${plugin.name}`]
-				});
-				if (plugin.generators?.length || driver.hasRegisteredGenerators(plugin.name)) await runPluginAstHooks(plugin, context);
-				const duration = getElapsedMs(hrStart);
-				pluginTimings.set(plugin.name, duration);
-				await hooks.emit("kubb:plugin:end", {
-					plugin,
-					duration,
-					success: true,
-					config,
-					get files() {
-						return driver.fileManager.files;
-					},
-					upsertFile: (...files) => driver.fileManager.upsert(...files)
-				});
-				await flushPendingFiles();
-				await hooks.emit("kubb:debug", {
-					date: /* @__PURE__ */ new Date(),
-					logs: [`✓ Plugin started successfully (${formatMs(duration)})`]
-				});
-			} catch (caughtError) {
-				const error = caughtError;
-				const errorTimestamp = /* @__PURE__ */ new Date();
-				const duration = getElapsedMs(hrStart);
-				await hooks.emit("kubb:plugin:end", {
-					plugin,
-					duration,
-					success: false,
-					error,
-					config,
-					get files() {
-						return driver.fileManager.files;
-					},
-					upsertFile: (...files) => driver.fileManager.upsert(...files)
-				});
-				await flushPendingFiles();
-				await hooks.emit("kubb:debug", {
-					date: errorTimestamp,
-					logs: [
-						"✗ Plugin start failed",
-						`  • Plugin Name: ${plugin.name}`,
-						`  • Error: ${error.constructor.name} - ${error.message}`,
-						"  • Stack Trace:",
-						error.stack || "No stack trace available"
-					]
-				});
-				failedPlugins.add({
-					plugin,
-					error
-				});
+	/**
+	* 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
+			};
 		}
-		await hooks.emit("kubb:plugins:end", {
+		const outputDiagnostics = options.processOutput ? await options.processOutput({
 			config,
-			get files() {
-				return driver.fileManager.files;
-			},
-			upsertFile: (...files) => driver.fileManager.upsert(...files)
-		});
-		await flushPendingFiles();
-		const files = driver.fileManager.files;
-		await hooks.emit("kubb:build:end", {
-			files,
+			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,
-			outputDir: resolve(config.root, config.output.path)
+			storage,
+			diagnostics: finalDiagnostics,
+			filesCreated: files.length,
+			status: failed ? "failed" : "success",
+			hrStart
 		});
 		return {
-			failedPlugins,
+			success: !failed,
 			files,
-			driver,
-			pluginTimings,
-			storage
-		};
-	} catch (error) {
-		return {
-			failedPlugins,
-			files: [],
-			driver,
-			pluginTimings,
-			error,
-			storage
+			diagnostics: finalDiagnostics
 		};
-	} finally {
-		driver.dispose();
 	}
-}
-async function build(setupResult) {
-	const { files, driver, failedPlugins, pluginTimings, error, storage } = await safeBuild(setupResult);
-	if (error) throw error;
-	if (failedPlugins.size > 0) {
-		const errors = [...failedPlugins].map(({ error }) => error);
-		throw new BuildError(`Build Error with ${failedPlugins.size} failed plugins`, { errors });
+	dispose() {
+		this.#driver?.dispose();
 	}
-	return {
-		failedPlugins,
-		files,
-		driver,
-		pluginTimings,
-		error: void 0,
-		storage
-	};
-}
-/**
-* Returns a snapshot of the current runtime environment.
-*
-* Useful for attaching context to debug logs and error reports so that
-* issues can be reproduced without manual information gathering.
-*/
-function getDiagnosticInfo() {
-	return {
-		nodeVersion: version,
-		KubbVersion: version$1,
-		platform: process.platform,
-		arch: process.arch,
-		cwd: process.cwd()
-	};
-}
-function isInputPath(config) {
-	return typeof config?.input === "object" && config.input !== null && "path" in config.input;
-}
-function inputToAdapterSource(config) {
-	const input = config.input;
-	if (!input) throw new Error("[kubb] input is required when using an adapter. Provide input.path or input.data in your config.");
-	if ("data" in input) return {
-		type: "data",
-		data: input.data
-	};
-	if (new URLPath(input.path).isURL) return {
-		type: "path",
-		path: input.path
-	};
-	return {
-		type: "path",
-		path: resolve(config.root, input.path)
-	};
-}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
 /**
-* Creates a Kubb instance bound to a single config entry.
-*
-* Accepts a user-facing config shape and resolves it to a full {@link Config} during
-* `setup()`. The instance then holds shared state (`hooks`, `storage`, `driver`, `config`)
-* across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
-* calling `setup()` or `build()`.
+* Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+* to `new Kubb(userConfig, options)` and the canonical public entry point.
 *
 * @example
 * ```ts
-* const kubb = createKubb(userConfig)
+* import { createKubb } from '@kubb/core'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { pluginTs } from '@kubb/plugin-ts'
 *
-* kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
-*   console.log(`${plugin.name} completed in ${duration}ms`)
+* const kubb = createKubb({
+*   input: './petStore.yaml',
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   plugins: [pluginTs()],
 * })
 *
-* const { files, failedPlugins } = await kubb.safeBuild()
+* await kubb.build()
 * ```
 */
 function createKubb(userConfig, options = {}) {
-	const hooks = options.hooks ?? new AsyncEventEmitter();
-	let setupResult;
-	const instance = {
-		get hooks() {
-			return hooks;
-		},
-		get storage() {
-			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing storage");
-			return setupResult.storage;
-		},
-		get driver() {
-			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing driver");
-			return setupResult.driver;
-		},
-		get config() {
-			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing config");
-			return setupResult.config;
-		},
-		async setup() {
-			setupResult = await setup(userConfig, { hooks });
-		},
-		async build() {
-			if (!setupResult) await instance.setup();
-			return build(setupResult);
-		},
-		async safeBuild() {
-			if (!setupResult) await instance.setup();
-			return safeBuild(setupResult);
-		}
-	};
-	return instance;
+	return new Kubb(userConfig, options);
 }
 //#endregion
-//#region src/createRenderer.ts
+//#region src/createReporter.ts
 /**
-* Creates a renderer factory for use in generator definitions.
+* Numeric log-level thresholds used internally to compare verbosity.
 *
-* Wrap your renderer factory function with this helper to register it as the
-* renderer for a generator. Core will call this factory once per render cycle
-* to obtain a fresh renderer instance.
+* Higher numbers are more verbose.
+*/
+const logLevel = {
+	silent: Number.NEGATIVE_INFINITY,
+	error: 0,
+	warn: 1,
+	info: 3,
+	verbose: 4
+};
+/**
+* Defines a reporter. The returned reporter buffers each value `report` returns in order and, when
+* the definition has a `drain`, hands the array to `drain` once and then clears it. Wiring the
+* reporter onto the run's hooks is the host's job, so the reporter only ever deals with a
+* {@link GenerationResult}.
 *
 * @example
 * ```ts
-* // packages/renderer-jsx/src/index.ts
-* export const jsxRenderer = createRenderer(() => {
-*   const runtime = new Runtime()
-*   return {
-*     async render(element) { await runtime.render(element) },
-*     get files() { return runtime.nodes },
-*     unmount(error) { runtime.unmount(error) },
-*   }
-* })
+* import { createReporter, Diagnostics } from '@kubb/core'
 *
-* // packages/plugin-zod/src/generators/zodGenerator.tsx
-* import { jsxRenderer } from '@kubb/renderer-jsx'
-* export const zodGenerator = defineGenerator<PluginZod>({
-*   name: 'zod',
-*   renderer: jsxRenderer,
-*   schema(node, options) { return <File ...>...</File> },
+* export const jsonReporter = createReporter({
+*   name: 'json',
+*   report(result) {
+*     return { status: Diagnostics.hasError(result.diagnostics) ? 'failed' : 'success', diagnostics: result.diagnostics }
+*   },
+*   drain(context, reports) {
+*     process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`)
+*   },
 * })
 * ```
 */
-function createRenderer(factory) {
-	return factory;
+function createReporter(reporter) {
+	const reports = [];
+	return {
+		name: reporter.name,
+		async report(result, context) {
+			const report = await reporter.report(result, context);
+			if (reporter.drain) reports.push(report);
+		},
+		async drain(context) {
+			await reporter.drain?.(context, [...reports]);
+			reports.length = 0;
+		},
+		[Symbol.dispose]() {
+			reports.length = 0;
+		}
+	};
 }
 //#endregion
-//#region src/defineGenerator.ts
+//#region src/reporters/report.ts
 /**
-* Defines a generator. Returns the object as-is with correct `this` typings.
-* `applyHookResult` handles renderer elements and `File[]` uniformly using
-* the generator's declared `renderer` factory.
+* Builds the normalized {@link Report} for one config from its {@link GenerationResult}. Splits the
+* diagnostics into problems and per-plugin timings (slowest first) and derives the plugin and issue
+* counts, so every reporter renders the same data.
 */
-function defineGenerator(generator) {
-	return generator;
+function buildReport(result) {
+	const { config, diagnostics, filesCreated, status, hrStart } = result;
+	const failed = Diagnostics.failedPlugins(diagnostics);
+	const total = config.plugins?.length ?? 0;
+	const counts = Diagnostics.count(diagnostics);
+	const problems = diagnostics.filter(Diagnostics.isProblem);
+	const timings = diagnostics.filter(Diagnostics.isPerformance).sort((a, b) => b.duration - a.duration).map((diagnostic) => ({
+		plugin: diagnostic.plugin,
+		durationMs: diagnostic.duration
+	}));
+	return {
+		name: config.name ?? "",
+		status,
+		plugins: {
+			passed: total - failed.length,
+			failed,
+			total
+		},
+		counts,
+		filesCreated,
+		durationMs: getElapsedMs(hrStart),
+		output: resolve(config.root, config.output.path),
+		timings,
+		diagnostics: problems.map((diagnostic) => Diagnostics.serialize(diagnostic))
+	};
+}
+//#endregion
+//#region src/reporters/cliReporter.ts
+/**
+* Builds the vitest/jest-style summary for one {@link Report}: right-aligned dim labels with
+* `N passed (total)` counts, and a per-plugin `Timings` section when `showTimings`.
+*/
+function buildSummaryLines(report, { showTimings }) {
+	const { status, plugins, counts, filesCreated, durationMs, output, timings } = report;
+	const rows = [];
+	rows.push(["Plugins", status === "success" ? `${styleText("green", `${plugins.passed} passed`)} (${plugins.total})` : `${styleText("green", `${plugins.passed} passed`)} | ${styleText("red", `${plugins.failed.length} failed`)} (${plugins.total})`]);
+	if (status === "failed" && plugins.failed.length > 0) rows.push(["Failed", plugins.failed.map((name) => randomCliColor(name)).join(", ")]);
+	if (counts.errors > 0 || counts.warnings > 0) {
+		const issues = [counts.errors > 0 ? styleText("red", `${counts.errors} ${counts.errors === 1 ? "error" : "errors"}`) : void 0, counts.warnings > 0 ? styleText("yellow", `${counts.warnings} ${counts.warnings === 1 ? "warning" : "warnings"}`) : void 0].filter(Boolean).join(" | ");
+		rows.push(["Issues", issues]);
+	}
+	rows.push(["Files", `${styleText("green", String(filesCreated))} generated`]);
+	rows.push(["Duration", styleText("green", formatMs(durationMs))]);
+	rows.push(["Output", output]);
+	const labelWidth = Math.max(...rows.map(([label]) => label.length), timings.length > 0 ? 7 : 0);
+	const lines = rows.map(([label, value]) => `${styleText("dim", label.padStart(labelWidth))}  ${value}`);
+	if (showTimings && timings.length > 0) {
+		const nameWidth = Math.max(0, ...timings.map((timing) => timing.plugin.length));
+		const indent = " ".repeat(labelWidth + 2);
+		lines.push(styleText("dim", "Timings".padStart(labelWidth)));
+		for (const timing of timings) {
+			const timeStr = formatMs(timing.durationMs);
+			const barLength = Math.min(Math.ceil(timing.durationMs / 100), 10);
+			const bar = styleText("dim", "█".repeat(barLength));
+			lines.push(`${indent}${styleText("dim", "•")} ${timing.plugin.padEnd(nameWidth)} ${bar} ${timeStr}`);
+		}
+	}
+	return lines;
+}
+/**
+* Renders the summary as plain `console.log` lines so it works in every CLI (no clack/TTY
+* dependency): a blank line, the config name colored by status, then the summary rows.
+*/
+function renderSummary(lines, { title, status }) {
+	console.log("");
+	if (title) console.log(styleText(status === "failed" ? "red" : "green", title));
+	for (const line of lines) console.log(line);
 }
+/**
+* The default `cli` reporter. Renders the {@link Report} for each config as it finishes, independent
+* of the live logger view. Suppressed at `silent`. The `verbose` level adds the per-plugin timings.
+*/
+const cliReporter = createReporter({
+	name: "cli",
+	report(result, { logLevel: logLevel$1 }) {
+		if (logLevel$1 <= logLevel.silent) return;
+		const report = buildReport(result);
+		renderSummary(buildSummaryLines(report, { showTimings: logLevel$1 >= logLevel.verbose }), {
+			title: report.name,
+			status: report.status
+		});
+	}
+});
 //#endregion
-//#region src/defineLogger.ts
+//#region src/reporters/fileReporter.ts
+/**
+* Builds the `## Summary` section: the same counts the cli and json reporters expose, as a list of
+* `label  value` rows with the labels padded to a common width.
+*/
+function buildSummarySection(report) {
+	const { status, plugins, counts, filesCreated, durationMs, output } = report;
+	const rows = [["Status", status], ["Plugins", status === "success" ? `${plugins.passed} passed (${plugins.total})` : `${plugins.passed} passed | ${plugins.failed.length} failed (${plugins.total})`]];
+	if (plugins.failed.length > 0) rows.push(["Failed", plugins.failed.join(", ")]);
+	rows.push(["Issues", `${counts.errors} errors | ${counts.warnings} warnings | ${counts.infos} infos`]);
+	rows.push(["Files", `${filesCreated} generated`]);
+	rows.push(["Duration", formatMs(durationMs)]);
+	rows.push(["Output", output]);
+	const labelWidth = Math.max(...rows.map(([label]) => label.length));
+	return [
+		"## Summary",
+		"",
+		...rows.map(([label, value]) => `  ${label.padEnd(labelWidth)}  ${value}`)
+	];
+}
+/**
+* Builds the `## Problems` section: each problem rendered in the miette block format, blocks
+* separated by a blank line. Returns an empty array when there are no problems, so the caller
+* can drop the heading.
+*/
+function buildProblemSection(diagnostics) {
+	const problems = diagnostics.filter(Diagnostics.isProblem);
+	if (problems.length === 0) return [];
+	return [
+		"## Problems",
+		"",
+		problems.map((diagnostic) => Diagnostics.formatLines(diagnostic).join("\n")).join("\n\n")
+	];
+}
 /**
-* Wraps a logger definition into a typed {@link Logger}.
+* Builds the `## Timings` section from a {@link Report}: one `plugin   duration` row per record,
+* slowest first with the plugin names left-aligned and the durations right-aligned. Returns an
+* empty array when there are no timings.
+*/
+function buildTimingSection(report) {
+	const { timings } = report;
+	if (timings.length === 0) return [];
+	const nameWidth = Math.max(...timings.map((timing) => timing.plugin.length));
+	const durations = timings.map((timing) => formatMs(timing.durationMs));
+	const durationWidth = Math.max(...durations.map((duration) => duration.length));
+	return [
+		"## Timings",
+		"",
+		...timings.map((timing, index) => `  ${timing.plugin.padEnd(nameWidth)}  ${durations[index].padStart(durationWidth)}`)
+	];
+}
+/**
+* The `file` reporter. Writes a config's {@link Report} to `.kubb/kubb-<name>-<timestamp>.log` as a
+* plain-text document: a `# <name> — <timestamp>` header, a `## Summary` with the same counts the
+* cli and json reporters expose, a `## Problems` section in the miette block format, and a
+* `## Timings` section. Selected with `--reporter file` (or `reporters: ['file']`).
 *
-* The optional second type parameter `TInstallReturn` allows loggers to return
-* a value from `install` — for example, a sink factory that the caller can
-* forward to hook execution.
+* @note It captures the collected diagnostics once a config finishes, not the live
+* `kubb:info`/`kubb:plugin` hook stream. Color is stripped so the file stays plain text even when
+* the run is attached to a TTY.
+*/
+const fileReporter = createReporter({
+	name: "file",
+	async report(result) {
+		const { diagnostics, config } = result;
+		if (diagnostics.length === 0) return;
+		const report = buildReport(result);
+		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);
+		const content = stripVTControlCharacters([header, ...sections.map((section) => section.join("\n"))].join("\n\n"));
+		const baseName = `${[
+			"kubb",
+			config.name,
+			Date.now()
+		].filter(Boolean).join("-")}.log`;
+		const pathName = resolve(process$1.cwd(), ".kubb", baseName);
+		await write(pathName, `${content}\n`);
+		console.error(`Debug log written to ${relative(process$1.cwd(), pathName)}`);
+	}
+});
+//#endregion
+//#region src/reporters/jsonReporter.ts
+/**
+* The `json` reporter. `report` returns one config's {@link Report}, which {@link createReporter}
+* buffers, and `drain` writes them as a single pretty-printed JSON array on `kubb:lifecycle:end`.
+* Buffering keeps a multi-config run one valid JSON document on stdout instead of concatenated
+* objects that would break `jq .`. The terminal reporter is suppressed while `json` is active so
+* stdout stays valid JSON.
+*/
+const jsonReporter = createReporter({
+	name: "json",
+	report(result) {
+		return buildReport(result);
+	},
+	drain(_context, reports) {
+		process$1.stdout.write(`${JSON.stringify(reports, null, 2)}\n`);
+	}
+});
+//#endregion
+//#region src/createRenderer.ts
+/**
+* Defines a renderer factory. Renderers turn the generator's return value
+* (JSX, a template string, a tree of any shape) into `FileNode`s that get
+* written to disk.
 *
-* @example Basic logger
-* ```ts
-* export const myLogger = defineLogger({
-*   name: 'my-logger',
-*   install(context, options) {
-*     context.on('kubb:info', (message) => console.log('ℹ', message))
-*     context.on('kubb:error', (error) => console.error('✗', error.message))
-*   },
-* })
-* ```
+* A renderer can target output formats beyond JSX, for instance a Handlebars
+* renderer or one that writes binary files. Plugins and generators pick the
+* renderer to use via the `renderer` field on `defineGenerator`.
 *
-* @example Logger that returns a hook sink factory
+* @example A minimal renderer that wraps a custom runtime
 * ```ts
-* export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
-*   name: 'my-logger',
-*   install(context, options) {
-*     // … register event handlers …
-*     return (commandWithArgs) => ({ onStdout: console.log })
-*   },
+* import { createRenderer } from '@kubb/core'
+*
+* export const myRenderer = createRenderer(() => {
+*   const runtime = new MyRuntime()
+*   return {
+*     async render(element) {
+*       await runtime.render(element)
+*     },
+*     get files() {
+*       return runtime.files
+*     },
+*     [Symbol.dispose]() {
+*       runtime.dispose()
+*     },
+*   }
 * })
 * ```
 */
-function defineLogger(logger) {
-	return logger;
+function createRenderer(factory) {
+	return factory;
 }
 //#endregion
-//#region src/defineMiddleware.ts
+//#region src/defineGenerator.ts
 /**
-* Creates a middleware factory using the hook-style `hooks` API.
-*
-* Middleware handlers fire after all plugin handlers for any given event, making them ideal for post-processing, logging, and auditing.
-* Per-build state (such as accumulators) belongs inside the factory closure so each `createKubb` invocation gets its own isolated instance.
+* Defines a generator: a unit of work that runs during the plugin's AST walk
+* and produces files. Plugins register generators via `ctx.addGenerator()`
+* inside `kubb:plugin:setup`.
 *
-* @note The factory can accept typed options. See examples for using options and per-build state patterns.
+* The returned object is the input as-is, but with `this` types preserved so
+* `schema`/`operation`/`operations` methods are correctly typed against the
+* plugin's `PluginFactoryOptions`. Renderer elements and `FileNode[]` returns
+* are both handled by the runtime, so pick whichever style fits.
 *
-* @example
-* ```ts
-* import { defineMiddleware } from '@kubb/core'
+* @example JSX-based schema generator
+* ```tsx
+* import { defineGenerator } from '@kubb/core'
+* import { jsxRenderer } from '@kubb/renderer-jsx'
 *
-* // Stateless middleware
-* export const logMiddleware = defineMiddleware(() => ({
-*   name: 'log-middleware',
-*   hooks: {
-*     'kubb:build:end'({ files }) {
-*       console.log(`Build complete with ${files.length} files`)
-*     },
+* export const typeGenerator = defineGenerator({
+*   name: 'typescript',
+*   renderer: jsxRenderer,
+*   schema(node, ctx) {
+*     return (
+*       <File path={`${ctx.root}/${node.name}.ts`}>
+*         <Type node={node} resolver={ctx.resolver} />
+*       </File>
+*     )
 *   },
-* }))
-*
-* // Middleware with options and per-build state
-* export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
-*   const seen = new Set<string>()
-*   return {
-*     name: 'prefix-middleware',
-*     hooks: {
-*       'kubb:plugin:end'({ plugin }) {
-*         seen.add(`${options.prefix}${plugin.name}`)
-*       },
-*     },
-*   }
 * })
 * ```
 */
-function defineMiddleware(factory) {
-	return (options) => factory(options ?? {});
+function defineGenerator(generator) {
+	return generator;
 }
 //#endregion
 //#region src/defineParser.ts
 /**
-* Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
+* Wraps a parser factory and returns a function that accepts user options and
+* yields a typed {@link Parser}. Mirrors {@link definePlugin}: the factory
+* receives the caller's options, and calling the returned function without
+* options passes an empty object.
 *
-* @note Call the returned factory with optional options to instantiate the parser.
+* Register the result in the `parsers` array on `defineConfig`, calling it to
+* apply options (`parserTs({ extension: { '.ts': '.js' } })`).
 *
 * @example
 * ```ts
 * import { defineParser } from '@kubb/core'
+* import { extractStringsFromNodes } from '@kubb/ast'
 *
-* export const jsonParser = defineParser({
+* export const parserJson = defineParser((options: { pretty?: boolean } = {}) => ({
 *   name: 'json',
 *   extNames: ['.json'],
 *   parse(file) {
-*     const { extractStringsFromNodes } = await import('@kubb/ast')
-*     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+*     const source = file.sources.map((source) => extractStringsFromNodes(source.nodes ?? [])).join('\n')
+*     return options.pretty ? JSON.stringify(JSON.parse(source), null, 2) : source
 *   },
-* })
+*   print(...nodes) {
+*     return nodes.map(String).join('\n')
+*   },
+* }))
 * ```
 */
-function defineParser(parser) {
-	return parser;
+function defineParser(factory) {
+	return (options) => factory(options ?? {});
 }
 //#endregion
 //#region src/storages/memoryStorage.ts
@@ -1447,7 +2693,7 @@ function defineParser(parser) {
 * import { defineConfig } from 'kubb'
 *
 * export default defineConfig({
-*   input:  { path: './petStore.yaml' },
+*   input:  './petStore.yaml',
 *   output: { path: './src/gen' },
 *   storage: memoryStorage(),
 * })
@@ -1457,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;
@@ -1483,6 +2729,6 @@ const memoryStorage = createStorage(() => {
 	};
 });
 //#endregion
-export { AsyncEventEmitter, FileManager, FileProcessor, PluginDriver, URLPath, ast, createAdapter, createKubb, createRenderer, createStorage, defineGenerator, defineLogger, defineMiddleware, defineParser, definePlugin, defineResolver, fsStorage, isInputPath, logLevel, memoryStorage };
+export { Diagnostics, Hookable, KubbDriver, Resolver, applyConfigDefaults, cliReporter, createAdapter, createKubb, createRenderer, createReporter, createResolver, createStorage, defineGenerator, defineParser, definePlugin, fileReporter, fsStorage, getInputKind, jsonReporter, logLevel, memoryStorage };
 
 //# sourceMappingURL=index.js.map