@kubb/core 5.0.0-beta.1 → 5.0.0-beta.100

package/dist/index.cjs

@@ -1,150 +1,67 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_PluginDriver = require("./PluginDriver-BXibeQk-.cjs");
-let node_events = require("node:events");
+const require_usingCtx = require("./usingCtx-CZyLSqds.cjs");
+let node_async_hooks = require("node:async_hooks");
+let node_util = require("node:util");
+let node_crypto = require("node:crypto");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
+node_path = require_usingCtx.__toESM(node_path, 1);
 let _kubb_ast = require("@kubb/ast");
-_kubb_ast = require_PluginDriver.__toESM(_kubb_ast, 1);
 let node_process = require("node:process");
-//#region ../../internals/utils/src/errors.ts
+node_process = require_usingCtx.__toESM(node_process, 1);
+//#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 node_events.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,554 +96,1853 @@ function formatMs(ms) {
 	return `${Math.round(ms)}ms`;
 }
 //#endregion
-//#region ../../internals/utils/src/fs.ts
+//#region ../../internals/utils/src/colors.ts
 /**
-* Resolves to `true` when the file or directory at `path` exists.
-* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
-*
-* @example
-* ```ts
-* if (await exists('./kubb.config.ts')) {
-*   const content = await read('./kubb.config.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.
 */
-async function exists(path) {
-	if (typeof Bun !== "undefined") return Bun.file(path).exists();
-	return (0, node_fs_promises.access)(path).then(() => true, () => false);
+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");
+/**
+* ANSI color names used by {@link randomCliColor} for deterministic terminal coloring.
+*/
+const randomColors = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"white",
+	"magenta",
+	"cyan",
+	"gray"
+];
 /**
-* 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.
+* Wraps `text` in a deterministic ANSI color derived from the text's SHA-256 hash.
 *
 * @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
+* randomCliColor('petstore') // '\x1b[33m' + 'petstore' + '\x1b[39m' (always the same color for 'petstore')
 * ```
 */
-async function write(path, data, options = {}) {
-	const trimmed = data.trim();
-	if (trimmed === "") return null;
-	const resolved = (0, node_path.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 (0, node_fs_promises.readFile)(resolved, { encoding: "utf-8" }) === trimmed) return null;
-	} catch {}
-	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(resolved), { recursive: true });
-	await (0, node_fs_promises.writeFile)(resolved, trimmed, { encoding: "utf-8" });
-	if (options.sanity) {
-		const savedData = await (0, node_fs_promises.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;
+function randomCliColor(text) {
+	if (!text) return "";
+	const index = (0, node_crypto.hash)("sha256", text, "buffer").readUInt32BE(0) % randomColors.length;
+	return (0, node_util.styleText)(randomColors[index] ?? "white", text);
 }
+//#endregion
+//#region ../../internals/utils/src/promise.ts
 /**
-* Recursively removes `path`. Silently succeeds when `path` does not exist.
+* Wraps `factory` with a keyed cache backed by the provided store.
 *
-* @example
+* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
+* collected) or a `Map` for primitive keys. For multi-argument functions,
+* nest two `memoize` calls — the outer keyed by the first argument, the
+* inner (created once per outer miss) keyed by the second.
+*
+* Because the cache is owned by the caller, it can be shared, inspected, or
+* cleared independently of the memoized function.
+*
+* @example Single WeakMap key
 * ```ts
-* await clean('./dist')
+* const cache = new WeakMap<SchemaNode, Set<string>>()
+* const getRefs = memoize(cache, (node) => collectRefs(node))
+* ```
+*
+* @example Single Map key (primitive)
+* ```ts
+* const cache = new Map<string, Resolver>()
+* const getResolver = memoize(cache, (name) => buildResolver(name))
+* ```
+*
+* @example Two-level (object + primitive)
+* ```ts
+* const outer = new WeakMap<Params[], Map<string, Params[]>>()
+* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
+* fn(params)('camelcase')
 * ```
 */
-async function clean(path) {
-	return (0, node_fs_promises.rm)(path, {
-		recursive: true,
-		force: true
-	});
+function memoize(store, factory) {
+	return (key) => {
+		if (store.has(key)) return store.get(key);
+		const value = factory(key);
+		store.set(key, value);
+		return value;
+	};
 }
 //#endregion
-//#region ../../internals/utils/src/reserved.ts
+//#region package.json
+var version = "5.0.0-beta.100";
+//#endregion
+//#region src/constants.ts
 /**
-* JavaScript and Java reserved words.
-* @link https://github.com/jonschlinkert/reserved/blob/master/index.js
+* Plugin `include` filter types that select operations directly. When one of these is set
+* without a `schemaName` include, the generate phase pre-scans operations to compute the set
+* of schemas they reach, so unreachable schemas can be pruned for that plugin.
 */
-const 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 OPERATION_FILTER_TYPES = /* @__PURE__ */ new Set([
+	"tag",
+	"operationId",
+	"path",
+	"method",
+	"contentType"
 ]);
 /**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+* Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
+* and stays stable so it can be referenced in tooling and (later) docs. Reference
+* these instead of inlining the string at a throw site.
+*/
+const diagnosticCode = {
+	/**
+	* Fallback for an unstructured error with no specific code.
+	*/
+	unknown: "KUBB_UNKNOWN",
+	/**
+	* The file or URL set as `input` could not be read.
+	*/
+	inputNotFound: "KUBB_INPUT_NOT_FOUND",
+	/**
+	* An adapter was configured without an `input`.
+	*/
+	inputRequired: "KUBB_INPUT_REQUIRED",
+	/**
+	* A `$ref` (or equivalent reference) could not be resolved in the source document.
+	*/
+	refNotFound: "KUBB_REF_NOT_FOUND",
+	/**
+	* A server variable value is not allowed by its `enum`.
+	*/
+	invalidServerVariable: "KUBB_INVALID_SERVER_VARIABLE",
+	/**
+	* A required plugin is missing from the config.
+	*/
+	pluginNotFound: "KUBB_PLUGIN_NOT_FOUND",
+	/**
+	* A plugin threw while generating.
+	*/
+	pluginFailed: "KUBB_PLUGIN_FAILED",
+	/**
+	* A plugin reported a non-fatal warning through `ctx.warn`.
+	*/
+	pluginWarning: "KUBB_PLUGIN_WARNING",
+	/**
+	* A plugin reported an informational message through `ctx.info`.
+	*/
+	pluginInfo: "KUBB_PLUGIN_INFO",
+	/**
+	* A schema uses a `format` Kubb does not map to a specific type. Reserved for
+	* adapters to emit as a `warning`.
+	*/
+	unsupportedFormat: "KUBB_UNSUPPORTED_FORMAT",
+	/**
+	* A referenced schema or operation is marked `deprecated`. Reserved for adapters
+	* to emit as an `info`.
+	*/
+	deprecated: "KUBB_DEPRECATED",
+	/**
+	* An adapter is required but the config has none. The build cannot read the input
+	* without one.
+	*/
+	adapterRequired: "KUBB_ADAPTER_REQUIRED",
+	/**
+	* A resolved output path escapes the output directory, which can stem from a path
+	* traversal in the spec or a misconfigured `group.name`.
+	*/
+	pathTraversal: "KUBB_PATH_TRAVERSAL",
+	/**
+	* `output.clean` is enabled but `output.path` resolves to the project root or a parent of it,
+	* so cleaning would delete kubb.config and every source file.
+	*/
+	cleanRoot: "KUBB_CLEAN_ROOT",
+	/**
+	* A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
+	*/
+	invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS",
+	/**
+	* A post-generate command (`output.postGenerate`) exited with a failure.
+	*/
+	postGenerateFailed: "KUBB_POST_GENERATE_FAILED",
+	/**
+	* The formatter pass over the generated files failed.
+	*/
+	formatFailed: "KUBB_FORMAT_FAILED",
+	/**
+	* The linter pass over the generated files failed.
+	*/
+	lintFailed: "KUBB_LINT_FAILED",
+	/**
+	* Not a failure. Carries a plugin's elapsed time, summed into the run total.
+	*/
+	performance: "KUBB_PERFORMANCE",
+	/**
+	* Not a failure. A newer Kubb version is available on npm.
+	*/
+	updateAvailable: "KUBB_UPDATE_AVAILABLE"
+};
+//#endregion
+//#region src/Diagnostics.ts
+/**
+* Docs major version, derived from the package version so the link tracks the published major.
+*/
+const docsMajor = version.split(".")[0] ?? "5";
+/**
+* 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;
+}
+/**
+* Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
 *
 * @example
 * ```ts
-* isValidVarName('status')  // true
-* isValidVarName('class')   // false (reserved word)
-* isValidVarName('42foo')   // false (starts with digit)
+* if (isProblem(diagnostic)) {
+*   console.log(diagnostic.location)
+* }
 * ```
 */
-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 isProblem = isKind("problem");
+/**
+* Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
+*
+* @example
+* ```ts
+* const timings = diagnostics.filter(isPerformance)
+* ```
+*/
+const isPerformance = isKind("performance");
 /**
-* Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+* Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
 *
 * @example
-* const p = new URLPath('/pet/{petId}')
-* p.URL      // '/pet/:petId'
-* p.template // '`/pet/${petId}`'
+* ```ts
+* if (isUpdate(diagnostic)) {
+*   console.log(diagnostic.latestVersion)
+* }
+* ```
+*/
+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 or URL set as `input` (or passed as `kubb generate PATH`) could not be read.",
+		fix: "Check that the path or URL exists and is readable, then set it as `input` or pass it on the CLI."
+	},
+	[diagnosticCode.inputRequired]: {
+		title: "Input required",
+		cause: "An adapter is configured but no `input` was provided.",
+		fix: "Set `input` to a file path, a URL, an inline spec (JSON/YAML string), or a parsed object in your Kubb config."
+	},
+	[diagnosticCode.refNotFound]: {
+		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."
+	}
+};
+/**
+* Static helpers for working with {@link Diagnostic}s, plus the run-scoped sink
+* that lets deep code report a diagnostic without threading a callback.
+*
+* 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 node_async_hooks.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`.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
-	* ```
+	static code = diagnosticCode;
+	/**
+	* Type guard for a build {@link ProblemDiagnostic}.
 	*/
-	get URL() {
-		return this.toURLPath();
-	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
+	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('https://petstore.swagger.io/v2/pet').isURL // true
-	* new URLPath('/pet/{petId}').isURL                       // false
+	* throw new Diagnostics.Error({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
 	* ```
 	*/
-	get isURL() {
-		try {
-			return !!new URL(this.path).href;
-		} catch {
-			return false;
+	static Error = class DiagnosticError extends Error {
+		diagnostic;
+		constructor(diagnostic) {
+			super(diagnostic.message, { cause: diagnostic.cause });
+			this.name = "DiagnosticError";
+			this.diagnostic = diagnostic;
 		}
-	}
+	};
 	/**
-	* 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}`'
+	* 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`.
 	*/
-	get template() {
-		return this.toTemplateString();
+	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 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' } }
-	* ```
+	/**
+	* Runs `fn` with `sink` as the active diagnostic sink for the whole async
+	* subtree, so {@link Diagnostics.report} reaches it from anywhere inside.
 	*/
-	get object() {
-		return this.toObject();
+	static scope(sink, fn) {
+		return Diagnostics.#reporterStorage.run(sink, fn);
 	}
-	/** 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
-	* ```
+	/**
+	* 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.
 	*/
-	get params() {
-		return this.getParams();
+	static report(diagnostic) {
+		const sink = Diagnostics.#reporterStorage.getStore();
+		if (!sink) return false;
+		sink(diagnostic);
+		return true;
 	}
-	#transformParam(raw) {
-		const param = isValidVarName(raw) ? raw : require_PluginDriver.camelCase(raw);
-		return this.#options.casing === "camelcase" ? require_PluginDriver.camelCase(param) : param;
+	/**
+	* 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 });
 	}
 	/**
-	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	* Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
+	* keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
 	*/
-	#eachParam(fn) {
-		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
-			const raw = match[1];
-			fn(raw, this.#transformParam(raw));
+	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 : require_usingCtx.getErrorMessage(error),
+			cause: root
+		};
+	}
+	/**
+	* Builds a per-plugin performance record. Reporters sum these into the run total.
+	*/
+	static performance({ plugin, duration }) {
+		return {
+			kind: "performance",
+			code: diagnosticCode.performance,
+			severity: "info",
+			message: `${plugin} generated in ${Math.round(duration)}ms`,
+			plugin,
+			duration
+		};
 	}
-	toObject({ type = "path", replacer, stringify } = {}) {
-		const object = {
-			url: type === "path" ? this.toURLPath() : this.toTemplateString({ replacer }),
-			params: this.getParams()
+	/**
+	* Builds the version-update notice shown when a newer Kubb is published on npm.
+	*/
+	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
 		};
-		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}' }`;
+	}
+	/**
+	* True when any diagnostic is an error, the severity that fails a build. Non-error
+	* diagnostics are ignored.
+	*/
+	static hasError(diagnostics) {
+		return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+	}
+	/**
+	* 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];
+	}
+	/**
+	* Counts `problem` diagnostics by severity for the run summary. `performance` and
+	* `update` diagnostics are ignored.
+	*/
+	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;
 		}
-		return object;
+		return {
+			errors,
+			warnings,
+			infos
+		};
 	}
 	/**
-	* 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}`'
+	* 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.
 	*/
-	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 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 result;
 	}
 	/**
-	* 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' }
-	* ```
+	* 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`.
 	*/
-	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 docsUrl(code) {
+		const slug = code.toLowerCase().replaceAll("_", "-");
+		return `https://kubb.dev/docs/${docsMajor}.x/reference/diagnostics/${slug}`;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
-	* ```
+	/**
+	* The catalog entry for a code: its title, cause, and fix. Mirrors the kubb.dev
+	* `/diagnostics/<slug>` page.
 	*/
-	toURLPath() {
-		return this.path.replace(/\{([^}]+)\}/g, ":$1");
+	static explain(code) {
+		return diagnosticCatalog[code];
 	}
-};
-//#endregion
-//#region src/createAdapter.ts
+	/**
+	* 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) }
+		};
+	}
+	/**
+	* 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).
+	*
+	* 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 = (0, node_util.styleText)(color, (0, node_util.styleText)("bold", `[${code}]`));
+		const headline = problem?.plugin ? `${tag} ${problem.plugin}: ${message}` : `${tag}: ${message}`;
+		const details = [];
+		if (problem?.location && "pointer" in problem.location) details.push(`  ${(0, node_util.styleText)("dim", "at:")} ${(0, node_util.styleText)("cyan", problem.location.pointer)}`);
+		if (problem?.help) details.push(`  ${(0, node_util.styleText)("cyan", "fix:")} ${problem.help}`);
+		if (code !== diagnosticCode.unknown) details.push(`  ${(0, node_util.styleText)("dim", "see:")} ${(0, node_util.styleText)("cyan", Diagnostics.docsUrl(code))}`);
+		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).
+	*/
+	static formatLines(diagnostic) {
+		const { headline, details } = Diagnostics.format(diagnostic);
+		return [headline, ...details];
+	}
+};
+//#endregion
+//#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.
+* 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.
+*/
+function normalizeOutput({ output, group, pluginName }) {
+	const mode = output.mode ?? "file";
+	if (mode === "file" && group) throw new Diagnostics.Error({
+		code: diagnosticCode.invalidPluginOptions,
+		severity: "error",
+		message: `Plugin "${pluginName}" sets \`output.mode: 'file'\` but also configures a \`group\` option.`,
+		help: "A single-file output has nothing to group. Remove the `group` option, or use `output.mode: 'directory'` to organize files into subdirectories.",
+		location: { kind: "config" },
+		plugin: pluginName
+	});
+	return {
+		...output,
+		mode
+	};
+}
+/**
+* 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 Adapters must parse their input format to Kubb's `InputNode` structure.
+* 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
-* export const myAdapter = createAdapter<MyAdapter>((options) => {
-*   return {
-*     name: 'my-adapter',
-*     options,
-*     async parse(source) {
-*       // Transform source format to InputNode
-*       return { ... }
+* import { definePlugin } from '@kubb/core'
+*
+* export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
+*   name: 'plugin-ts',
+*   hooks: {
+*     'kubb:plugin:setup'(ctx) {
+*       ctx.setResolver(resolverTs)
 *     },
+*   },
+* }))
+* ```
+*/
+function definePlugin(factory) {
+	return (options) => factory(options ?? {});
+}
+//#endregion
+//#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";
+}
+/**
+* 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) 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" }
+	});
+	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: (0, node_path.resolve)(config.root, input)
+	};
+}
+//#endregion
+//#region src/Resolver.ts
+function isNamespace(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 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 `${require_usingCtx.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: require_usingCtx.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.
+	*/
+	imports(options) {
+		const { node, root, output, group, extname = ".ts", name } = options;
+		const resolveName = name ?? ((schemaName) => this.name(schemaName));
+		const seen = /* @__PURE__ */ new Set();
+		return (0, _kubb_ast.collectSync)(node, { schema: (schemaNode) => {
+			const schemaRef = (0, _kubb_ast.narrowSchema)(schemaNode, "ref");
+			if (!schemaRef?.ref) return null;
+			const schemaName = (0, _kubb_ast.resolveRefName)(schemaRef);
+			if (!schemaName || seen.has(schemaName)) return null;
+			seen.add(schemaName);
+			return _kubb_ast.ast.factory.createImport({
+				name: [resolveName(schemaName)],
+				path: this.file({
+					name: schemaName,
+					extname,
+					root,
+					output,
+					group
+				}).path
+			});
+		} });
+	}
+	/**
+	* 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 (_kubb_ast.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 (_kubb_ast.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 require_usingCtx.camelCase(groupValue);
+		const segment = groupValue.split("/").filter((part) => part !== "" && part !== "." && part !== "..")[0];
+		return segment ? require_usingCtx.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 node_path.default.resolve(root, output.path);
+		const outputDir = node_path.default.resolve(root, output.path);
+		const result = group && (groupPath || tag) ? node_path.default.resolve(outputDir, Resolver.#resolveGroupDir(group, group.type === "path" ? groupPath : tag), baseName) : node_path.default.resolve(outputDir, baseName);
+		const outputDirWithSep = outputDir.endsWith(node_path.default.sep) ? outputDir : `${outputDir}${node_path.default.sep}`;
+		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 = node_path.default.resolve(root, filePath);
+		const rootWithSep = root.endsWith(node_path.default.sep) ? root : `${root}${node_path.default.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 _kubb_ast.ast.factory.createFile({
+			path: filePath,
+			baseName: node_path.default.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" : node_path.default.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/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))
+*   },
 * })
+* ```
 *
-* // Instantiate:
-* const adapter = myAdapter({ validate: true })
+* @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 createAdapter(build) {
-	return (options) => build(options ?? {});
+function createResolver(options) {
+	return new Resolver(options);
 }
 //#endregion
-//#region ../../node_modules/.pnpm/yocto-queue@1.2.2/node_modules/yocto-queue/index.js
-var Node = class {
-	value;
-	next;
-	constructor(value) {
-		this.value = value;
+//#region src/Transform.ts
+/**
+* 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.
+*
+* 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 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);
 	}
-};
-var Queue = class {
-	#head;
-	#tail;
-	#size;
-	constructor() {
-		this.clear();
-	}
-	enqueue(value) {
-		const node = new Node(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;
+	/**
+	* 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 = (0, _kubb_ast.transform)(node, visitor);
+		memo.set(node, result);
+		return result;
 	}
-	*drain() {
-		while (this.#head) yield this.dequeue();
+	/**
+	* 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 = (0, _kubb_ast.composeMacros)(macros);
+			this.#composed.set(pluginName, composed);
+		}
+		return composed;
 	}
 };
 //#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();
+//#region src/KubbDriver.ts
+const ENFORCE_ORDER = {
+	pre: -1,
+	post: 1
+};
+const enforceWeight = (plugin) => plugin.enforce ? ENFORCE_ORDER[plugin.enforce] : 0;
+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 require_usingCtx.FileManager();
+	plugins = /* @__PURE__ */ new Map();
+	/**
+	* Tracks which plugins have generators registered via `addGenerator()` (hook-based path).
+	* Used by the build loop to decide whether to emit generator hooks for a given plugin.
+	*/
+	#hookGeneratorPlugins = /* @__PURE__ */ new Set();
+	#resolvers = /* @__PURE__ */ new Map();
+	#defaultResolvers = /* @__PURE__ */ new Map();
+	/**
+	* Removers for every listener the driver added (plugin, generator) so `dispose()` can detach
+	* them in one pass. External `hooks.hook(...)` listeners are not tracked.
+	*/
+	#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 ?? {
+					output: {
+						path: ".",
+						mode: "directory"
+					},
+					exclude: [],
+					override: []
+				},
+				resolver: this.#getDefaultResolver(rawPlugin.name)
+			};
+		}));
+		for (const plugin of normalized) {
+			this.#registerPlugin(plugin);
+			this.plugins.set(plugin.name, plugin);
 		}
-	};
-	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_);
-	});
-	Object.defineProperties(generator, {
-		activeCount: { get: () => activeCount },
-		pendingCount: { get: () => queue.size },
-		clearQueue: { value() {
-			if (!rejectOnClear) {
-				queue.clear();
-				return;
+		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 [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(_kubb_ast.ast.factory.createFile(userFileNode));
+				}
+			});
+		}
+	}
+	/**
+	* Registers a generator for the given plugin on the shared hook emitter.
+	*
+	* The generator's `schema`, `operation`, and `operations` methods are registered as
+	* listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
+	* respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
+	* so that generators from different plugins do not cross-fire.
+	*
+	* The renderer comes from `generator.renderer`. Set `generator.renderer = null` (or leave it
+	* unset) to opt out of rendering.
+	*
+	* Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
+	*/
+	registerGenerator(pluginName, generator) {
+		const wrap = (method) => {
+			if (!method) return void 0;
+			return async (node, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				const result = await method(node, ctx);
+				await this.dispatch({
+					result,
+					renderer: generator.renderer
+				});
+			};
+		};
+		this.#unhooks.push(this.hooks.addHooks({
+			"kubb:generate:schema": wrap(generator.schema),
+			"kubb:generate:operation": wrap(generator.operation),
+			"kubb:generate:operations": wrap(generator.operations)
+		}));
+		this.#hookGeneratorPlugins.add(pluginName);
+	}
+	/**
+	* Returns `true` when at least one generator was registered for the given plugin
+	* via `addGenerator()` in `kubb:plugin:setup`.
+	*
+	* Used by the build loop to decide whether to walk the AST and emit generator hooks
+	* for a plugin.
+	*/
+	hasHookGenerators(pluginName) {
+		return this.#hookGeneratorPlugins.has(pluginName);
+	}
+	/**
+	* 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 updateBuffer = [];
+		const parsersMap = /* @__PURE__ */ new Map();
+		for (const parser of config.parsers) if (parser.extNames) for (const ext of parser.extNames) parsersMap.set(ext, parser);
+		const unhookWrites = fileManager.hooks.addHooks({
+			start: async (files) => {
+				await hooks.callHook("kubb:files:processing:start", { files });
+			},
+			update: (item) => {
+				updateBuffer.push(item);
+			},
+			end: async (files) => {
+				await hooks.callHook("kubb:files:processing:update", { files: updateBuffer.map((item) => ({
+					...item,
+					config
+				})) });
+				updateBuffer.length = 0;
+				await hooks.callHook("kubb:files:processing:end", { files });
 			}
-			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();
+		});
+		return Diagnostics.scope((diagnostic) => diagnostics.push(diagnostic), async () => {
+			try {
+				const outputRoot = (0, node_path.resolve)(config.root, config.output.path);
+				await this.#parseInput();
+				await this.setupHooks();
+				if (this.adapter && this.inputNode) await hooks.callHook("kubb:build:start", Object.assign({
+					config,
+					adapter: this.adapter,
+					meta: this.inputNode.meta,
+					getPlugin: this.getPlugin.bind(this)
+				}, this.#filesPayload()));
+				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 = require_usingCtx.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", Object.assign({ config }, this.#filesPayload()));
+				await fileManager.write(fileManager.files, {
+					storage: config.storage,
+					parsers: parsersMap
+				});
+				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();
 			}
-		},
-		map: { async value(iterable, function_) {
-			const promises = Array.from(iterable, (value, index) => this(function_, value, index));
-			return Promise.all(promises);
-		} }
-	});
-	return generator;
-}
-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");
-}
-//#endregion
-//#region src/FileProcessor.ts
-function joinSources(file) {
-	return file.sources.map((item) => (0, _kubb_ast.extractStringsFromNodes)(item.nodes)).filter(Boolean).join("\n\n");
-}
-/**
-* Converts a single file to a string using the registered parsers.
-* Falls back to joining source values when no matching parser is found.
-*
-* @internal
-*/
-var FileProcessor = class {
-	#limit = pLimit(100);
-	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, onStart, onEnd, onUpdate } = {}) {
-		await onStart?.(files);
-		const total = files.length;
-		let processed = 0;
-		const processOne = async (file) => {
-			const source = await this.parse(file, {
-				extension,
-				parsers
+		});
+	}
+	#filesPayload() {
+		const driver = this;
+		return {
+			get files() {
+				return driver.fileManager.files;
+			},
+			upsertFile: (...files) => driver.fileManager.upsert(...files)
+		};
+	}
+	#emitPluginEnd({ plugin, duration, success, error }) {
+		return this.hooks.callHook("kubb:plugin:end", Object.assign({
+			plugin,
+			duration,
+			success,
+			...error ? { error } : {},
+			config: this.config
+		}, this.#filesPayload()));
+	}
+	/**
+	* Runs schemas and operations through every plugin's generators. Each node is run
+	* through the plugin's macros (from `this.#transforms`) before the generator sees it,
+	* so plugins stay isolated and the hot path stays per-node. Schemas run before operations
+	* so file output stays deterministic across runs.
+	* A failing plugin contributes an error diagnostic so the rest of the build continues.
+	* Every plugin also contributes a `timing` diagnostic.
+	*
+	* Plugins are processed one at a time, in full, so `kubb:plugin:end` fires as each one
+	* completes rather than all at once at the end. That ordering drives the CLI's
+	* `Plugins N/M` counter.
+	*
+	* 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 emitsSchemaHook = this.hooks.listenerCount("kubb:generate:schema") > 0;
+		const emitsOperationHook = this.hooks.listenerCount("kubb:generate:operation") > 0;
+		const emitsOperationsHook = this.hooks.listenerCount("kubb:generate:operations") > 0;
+		const allowedSchemaNamesByPlugin = /* @__PURE__ */ new Map();
+		for (const { plugin } of entries) {
+			const { exclude, include, override } = plugin.options;
+			if (!((include?.some(({ type }) => OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === "schemaName") ?? false))) continue;
+			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, (0, _kubb_ast.collectUsedSchemaNames)(includedOps, schemas));
+		}
+		for (const { plugin, context, hrStart } of entries) {
+			const generatorContext = {
+				...context,
+				resolver: this.getResolver(plugin.name)
+			};
+			const { exclude, include, override } = plugin.options;
+			const optionsAreStatic = !exclude?.length && !include?.length && !override?.length;
+			const allowedSchemaNames = allowedSchemaNamesByPlugin.get(plugin.name) ?? null;
+			let error = null;
+			const resolveForPlugin = (node) => {
+				const transformedNode = transforms.applyTo(plugin.name, node);
+				if (optionsAreStatic) return {
+					transformedNode,
+					options: plugin.options
+				};
+				const options = generatorContext.resolver.default.options(transformedNode, {
+					options: plugin.options,
+					exclude,
+					include,
+					override
+				});
+				if (options === null) return null;
+				return {
+					transformedNode,
+					options
+				};
+			};
+			if (emitsSchemaHook) for (const node of schemas) {
+				if (error) break;
+				try {
+					const resolved = resolveForPlugin(node);
+					if (!resolved) continue;
+					const { transformedNode, options } = resolved;
+					if (allowedSchemaNames !== null && transformedNode.name && !allowedSchemaNames.has(transformedNode.name)) continue;
+					await this.hooks.callHook("kubb:generate:schema", transformedNode, {
+						...generatorContext,
+						options
+					});
+				} catch (caughtError) {
+					error = require_usingCtx.toError(caughtError);
+				}
+			}
+			if (emitsOperationHook) for (const node of operations) {
+				if (error) break;
+				try {
+					const resolved = resolveForPlugin(node);
+					if (!resolved) continue;
+					await this.hooks.callHook("kubb:generate:operation", resolved.transformedNode, {
+						...generatorContext,
+						options: resolved.options
+					});
+				} catch (caughtError) {
+					error = require_usingCtx.toError(caughtError);
+				}
+			}
+			if (!error && emitsOperationsHook) try {
+				const ctx = {
+					...generatorContext,
+					options: plugin.options
+				};
+				const pluginOperations = operations.reduce((acc, node) => {
+					const resolved = resolveForPlugin(node);
+					if (resolved) acc.push(resolved.transformedNode);
+					return acc;
+				}, []);
+				await this.hooks.callHook("kubb:generate:operations", pluginOperations, ctx);
+			} catch (caughtError) {
+				error = require_usingCtx.toError(caughtError);
+			}
+			const duration = getElapsedMs(hrStart);
+			await this.#emitPluginEnd({
+				plugin,
+				duration,
+				success: !error,
+				error: error ?? void 0
+			});
+			if (error) diagnostics.push({
+				...Diagnostics.from(error),
+				plugin: plugin.name
 			});
-			const currentProcessed = ++processed;
-			const percentage = currentProcessed / total * 100;
-			await onUpdate?.({
-				file,
-				source,
-				processed: currentProcessed,
-				percentage,
-				total
+			diagnostics.push(Diagnostics.performance({
+				plugin: 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 = require_usingCtx._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.#hookGeneratorPlugins.clear();
+		this.#transforms.dispose();
+		this.#resolvers.clear();
+		this.#defaultResolvers.clear();
+		this.fileManager.dispose();
+		this.inputNode = null;
+		this.#adapterSource = null;
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+	#getDefaultResolver = memoize(this.#defaultResolvers, (pluginName) => createResolver({ pluginName }));
+	/**
+	* Merges `partial` with the plugin's default resolver and stores the result.
+	* Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
+	* get the up-to-date resolver without going through `getResolver()`.
+	*/
+	setPluginResolver(pluginName, partial) {
+		const defaultResolver = this.#getDefaultResolver(pluginName);
+		const merged = Resolver.merge(defaultResolver, partial);
+		this.#resolvers.set(pluginName, merged);
+		const plugin = this.plugins.get(pluginName);
+		if (plugin) plugin.resolver = merged;
+	}
+	getResolver(pluginName) {
+		return this.#resolvers.get(pluginName) ?? this.#getDefaultResolver(pluginName);
+	}
+	getContext(plugin) {
+		const driver = this;
+		const report = (diagnostic) => {
+			Diagnostics.report({
+				...diagnostic,
+				plugin: plugin.name
 			});
 		};
-		if (mode === "sequential") for (const file of files) await processOne(file);
-		else await Promise.all(files.map((file) => this.#limit(() => processOne(file))));
-		await onEnd?.(files);
-		return files;
+		return {
+			config: driver.config,
+			get root() {
+				return (0, node_path.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/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.
+* 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.
 *
-* @note Call the returned factory with optional options to instantiate the storage adapter.
-*
-* @example
+* @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 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 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
 *     },
-*     async clear(base) { if (!base) store.clear() },
+*     async clear(base) {
+*       if (!base) store.clear()
+*     },
 *   }
 * })
-*
-* // Instantiate:
-* const storage = memoryStorage()
 * ```
 */
 function createStorage(build) {
@@ -734,11 +1950,28 @@ function createStorage(build) {
 }
 //#endregion
 //#region src/storages/fsStorage.ts
-/**
-* Detects the filesystem error used to indicate that a path does not exist.
-*/
-function isMissingPathError(error) {
-	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+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.
@@ -747,11 +1980,13 @@ function isMissingPathError(error) {
 * 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 content is already identical
+* - missing parent directories are created automatically
+* - Bun's native file API is used when running under Bun
+* - concurrent `setItem` calls are capped at {@link WRITE_CONCURRENCY} in flight, so a caller
+*   can fire every file's write without pacing itself
 *
 * @example
 * ```ts
@@ -759,634 +1994,535 @@ function isMissingPathError(error) {
 * 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 (0, node_fs_promises.access)((0, node_path.resolve)(key));
-			return true;
-		} catch (error) {
-			if (isMissingPathError(error)) return false;
-			throw new Error(`Failed to access storage item "${key}"`, { cause: error });
-		}
-	},
-	async getItem(key) {
-		try {
-			return await (0, node_fs_promises.readFile)((0, node_path.resolve)(key), "utf8");
-		} catch (error) {
-			if (isMissingPathError(error)) return null;
-			throw new Error(`Failed to read storage item "${key}"`, { cause: error });
-		}
-	},
-	async setItem(key, value) {
-		await write((0, node_path.resolve)(key), value, { sanity: false });
-	},
-	async removeItem(key) {
-		await (0, node_fs_promises.rm)((0, node_path.resolve)(key), { force: true });
-	},
-	async getKeys(base) {
-		const keys = [];
-		const resolvedBase = (0, node_path.resolve)(base ?? process.cwd());
-		async function walk(dir, prefix) {
-			let entries;
+const fsStorage = createStorage(() => {
+	const limit = createLimiter(WRITE_CONCURRENCY);
+	return {
+		name: "fs",
+		async hasItem(key) {
 			try {
-				entries = await (0, node_fs_promises.readdir)(dir, { withFileTypes: true });
-			} catch (error) {
-				if (isMissingPathError(error)) return;
-				throw new Error(`Failed to list storage keys under "${resolvedBase}"`, { cause: error });
+				await (0, node_fs_promises.access)((0, node_path.resolve)(key));
+				return true;
+			} catch (_error) {
+				return false;
 			}
-			for (const entry of entries) {
-				const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-				if (entry.isDirectory()) await walk((0, node_path.join)(dir, entry.name), rel);
-				else keys.push(rel);
+		},
+		async getItem(key) {
+			try {
+				return await (0, node_fs_promises.readFile)((0, node_path.resolve)(key), "utf8");
+			} catch (_error) {
+				return null;
 			}
+		},
+		async setItem(key, value) {
+			await limit(() => require_usingCtx.write((0, node_path.resolve)(key), value, { sanity: false }));
+		},
+		async removeItem(key) {
+			await (0, node_fs_promises.rm)((0, node_path.resolve)(key), { force: true });
+		},
+		async getKeys(base) {
+			const resolvedBase = (0, node_path.resolve)(base ?? process.cwd());
+			const keys = [];
+			try {
+				for await (const entry of (0, node_fs_promises.glob)("**/*", {
+					cwd: resolvedBase,
+					withFileTypes: true
+				})) if (entry.isFile()) keys.push(require_usingCtx.toPosixPath((0, node_path.relative)(resolvedBase, (0, node_path.join)(entry.parentPath, entry.name))));
+			} catch (_error) {}
+			return keys;
+		},
+		async clear(base) {
+			if (!base) return;
+			await require_usingCtx.clean((0, node_path.resolve)(base));
 		}
-		await walk(resolvedBase, "");
-		return keys;
-	},
-	async clear(base) {
-		if (!base) return;
-		await clean((0, node_path.resolve)(base));
-	}
-}));
-//#endregion
-//#region package.json
-var version = "5.0.0-beta.1";
-//#endregion
-//#region src/utils/diagnostics.ts
-/**
-* 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: node_process.version,
-		KubbVersion: version,
-		platform: process.platform,
-		arch: process.arch,
-		cwd: process.cwd()
 	};
-}
-//#endregion
-//#region src/utils/isInputPath.ts
-function isInputPath(config) {
-	return typeof config?.input === "object" && config.input !== null && "path" in config.input;
-}
+});
 //#endregion
 //#region src/createKubb.ts
-async function setup(userConfig, options = {}) {
-	const hooks = options.hooks ?? new AsyncEventEmitter();
-	const sources = /* @__PURE__ */ new Map();
-	const diagnosticInfo = getDiagnosticInfo();
-	if (Array.isArray(userConfig.input)) await hooks.emit("kubb:warn", { message: "This feature is still under development — use with caution" });
-	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: ${userConfig.storage ? `custom(${userConfig.storage.name})` : userConfig.output?.write === false ? "disabled" : "filesystem (default)"}`,
-			`  • 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 (!userConfig.adapter) throw new Error("Adapter should be defined");
-	const config = {
+function resolveConfig(userConfig) {
+	return {
 		...userConfig,
 		root: userConfig.root || process.cwd(),
 		parsers: userConfig.parsers ?? [],
-		adapter: userConfig.adapter,
 		output: {
 			format: false,
 			lint: false,
-			write: true,
-			extension: require_PluginDriver.DEFAULT_EXTENSION,
-			defaultBanner: require_PluginDriver.DEFAULT_BANNER,
+			defaultBanner: "simple",
 			...userConfig.output
 		},
-		devtools: userConfig.devtools ? {
-			studioUrl: require_PluginDriver.DEFAULT_STUDIO_URL,
-			...typeof userConfig.devtools === "boolean" ? {} : userConfig.devtools
-		} : void 0,
-		plugins: userConfig.plugins
-	};
-	const storage = config.output.write === false ? null : config.storage ?? fsStorage();
-	if (config.output.clean) {
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: ["Cleaning output directories", `  • Output: ${config.output.path}`]
-		});
-		await storage?.clear((0, node_path.resolve)(config.root, config.output.path));
-	}
-	const driver = new require_PluginDriver.PluginDriver(config, { hooks });
-	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);
-	const adapter = config.adapter;
-	if (!adapter) throw new Error("No adapter configured. Please provide an adapter in your kubb.config.ts.");
-	const source = inputToAdapterSource(config);
-	await hooks.emit("kubb:debug", {
-		date: /* @__PURE__ */ new Date(),
-		logs: [`Running adapter: ${adapter.name}`]
-	});
-	driver.adapter = adapter;
-	driver.inputNode = await adapter.parse(source);
-	await hooks.emit("kubb:debug", {
-		date: /* @__PURE__ */ new Date(),
-		logs: [
-			`✓ Adapter '${adapter.name}' resolved InputNode`,
-			`  • Schemas: ${driver.inputNode.schemas.length}`,
-			`  • Operations: ${driver.inputNode.operations.length}`
-		]
-	});
-	return {
-		config,
-		hooks,
-		driver,
-		sources,
-		storage
+		storage: userConfig.storage ?? fsStorage(),
+		reporters: userConfig.reporters ?? [],
+		plugins: userConfig.plugins ?? []
 	};
 }
 /**
-* Walks the AST and dispatches nodes to a plugin's direct AST hooks
-* (`schema`, `operation`, `operations`).
+* 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.
+*
+* 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. pluginOas()) 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)
-	};
-	await (0, _kubb_ast.walk)(inputNode, {
-		depth: "shallow",
-		async schema(node) {
-			const transformedNode = plugin.transformer ? (0, _kubb_ast.transform)(node, plugin.transformer) : node;
-			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 require_PluginDriver.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 ? (0, _kubb_ast.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;
+	constructor(userConfig, options = {}) {
+		this.config = resolveConfig(userConfig);
+		this.hooks = options.hooks ?? new require_usingCtx.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 driver = new KubbDriver(config, { hooks: this.hooks });
+		this.hooks.setMaxListeners(Math.max(10, config.plugins.length * 4));
+		if (config.output.clean) {
+			const cleanPath = (0, node_path.resolve)(config.root, config.output.path);
+			if (require_usingCtx.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 require_PluginDriver.applyHookResult(await gen.operation(transformedNode, ctx), driver, resolveRenderer(gen));
-				}
-				await driver.hooks.emit("kubb:generate:operation", transformedNode, ctx);
-			}
+			await config.storage.clear(cleanPath);
 		}
-	});
-	if (collectedOperations.length > 0) {
-		const ctx = {
-			...generatorContext,
-			options: plugin.options
-		};
-		for (const gen of generators) {
-			if (!gen.operations) continue;
-			await require_PluginDriver.applyHookResult(await gen.operations(collectedOperations, ctx), driver, resolveRenderer(gen));
+		await driver.setup();
+		this.#driver = driver;
+		this.#storage = config.storage;
+	}
+	/**
+	* 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 require_usingCtx.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, sources, storage } = setupResult;
-	const failedPlugins = /* @__PURE__ */ new Set();
-	const pluginTimings = /* @__PURE__ */ new Map();
-	const config = driver.config;
-	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 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 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
-				});
-			}
+	/**
+	* 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 = require_usingCtx._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();
 		}
-		await hooks.emit("kubb:plugins:end", {
-			config,
-			get files() {
-				return driver.fileManager.files;
-			},
-			upsertFile: (...files) => driver.fileManager.upsert(...files)
-		});
-		const files = driver.fileManager.files;
-		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();
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`Writing ${files.length} files...`]
-		});
-		await fileProcessor.run(files, {
-			parsers: parsersMap,
-			extension: config.output.extension,
-			onStart: async (processingFiles) => {
-				await hooks.emit("kubb:files:processing:start", { files: processingFiles });
-			},
-			onUpdate: 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);
-					sources.set(file.path, source);
-				}
-			},
-			onEnd: async (processedFiles) => {
-				await hooks.emit("kubb:files:processing:end", { files: processedFiles });
-				await hooks.emit("kubb:debug", {
-					date: /* @__PURE__ */ new Date(),
-					logs: [`✓ File write process completed for ${processedFiles.length} files`]
-				});
-			}
-		});
-		await hooks.emit("kubb:build:end", {
-			files,
-			config,
-			outputDir: (0, node_path.resolve)(config.root, config.output.path)
-		});
-		return {
-			failedPlugins,
-			files,
-			driver,
-			pluginTimings,
-			sources
-		};
-	} catch (error) {
-		return {
-			failedPlugins,
-			files: [],
-			driver,
-			pluginTimings,
-			error,
-			sources
-		};
-	} finally {
-		driver.dispose();
 	}
-}
-async function build(setupResult) {
-	const { files, driver, failedPlugins, pluginTimings, error, sources } = 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,
-		sources
-	};
-}
-function inputToAdapterSource(config) {
-	if (Array.isArray(config.input)) return {
-		type: "paths",
-		paths: config.input.map((i) => new URLPath(i.path).isURL ? i.path : (0, node_path.resolve)(config.root, i.path))
-	};
-	if ("data" in config.input) return {
-		type: "data",
-		data: config.input.data
-	};
-	if (new URLPath(config.input.path).isURL) return {
-		type: "path",
-		path: config.input.path
-	};
-	return {
-		type: "path",
-		path: (0, node_path.resolve)(config.root, config.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`, `sources`, `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 sources() {
-			return setupResult?.sources ?? /* @__PURE__ */ new Map();
-		},
-		get driver() {
-			return setupResult?.driver;
-		},
-		get 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: (0, node_path.resolve)(config.root, config.output.path),
+		timings,
+		diagnostics: problems.map((diagnostic) => Diagnostics.serialize(diagnostic))
+	};
 }
 //#endregion
-//#region src/defineLogger.ts
+//#region src/reporters/cliReporter.ts
 /**
-* Wraps a logger definition into a typed {@link Logger}.
-*
-* @example
-* ```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))
-*   },
-* })
-* ```
+* 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" ? `${(0, node_util.styleText)("green", `${plugins.passed} passed`)} (${plugins.total})` : `${(0, node_util.styleText)("green", `${plugins.passed} passed`)} | ${(0, node_util.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 ? (0, node_util.styleText)("red", `${counts.errors} ${counts.errors === 1 ? "error" : "errors"}`) : void 0, counts.warnings > 0 ? (0, node_util.styleText)("yellow", `${counts.warnings} ${counts.warnings === 1 ? "warning" : "warnings"}`) : void 0].filter(Boolean).join(" | ");
+		rows.push(["Issues", issues]);
+	}
+	rows.push(["Files", `${(0, node_util.styleText)("green", String(filesCreated))} generated`]);
+	rows.push(["Duration", (0, node_util.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]) => `${(0, node_util.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((0, node_util.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 = (0, node_util.styleText)("dim", "█".repeat(barLength));
+			lines.push(`${indent}${(0, node_util.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 defineLogger(logger) {
-	return logger;
+function renderSummary(lines, { title, status }) {
+	console.log("");
+	if (title) console.log((0, node_util.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/defineMiddleware.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")
+	];
+}
 /**
-* Creates a middleware factory using the hook-style `hooks` API.
+* 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']`).
 *
-* 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.
+* @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 content = (0, node_util.stripVTControlCharacters)([config.name ? `# ${config.name} — ${(/* @__PURE__ */ new Date()).toISOString()}` : `# ${(/* @__PURE__ */ new Date()).toISOString()}`, ...[
+			buildSummarySection(report),
+			buildProblemSection(diagnostics),
+			buildTimingSection(report)
+		].filter((section) => section.length > 0).map((section) => section.join("\n"))].join("\n\n"));
+		const baseName = `${[
+			"kubb",
+			config.name,
+			Date.now()
+		].filter(Boolean).join("-")}.log`;
+		const pathName = (0, node_path.resolve)(node_process.default.cwd(), ".kubb", baseName);
+		await require_usingCtx.write(pathName, `${content}\n`);
+		console.error(`Debug log written to ${(0, node_path.relative)(node_process.default.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) {
+		node_process.default.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.
 *
-* @note The factory can accept typed options. See examples for using options and per-build state patterns.
+* 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
+* @example A minimal renderer that wraps a custom runtime
 * ```ts
-* import { defineMiddleware } from '@kubb/core'
+* import { createRenderer } from '@kubb/core'
 *
-* // Stateless middleware
-* export const logMiddleware = defineMiddleware(() => ({
-*   name: 'log-middleware',
-*   hooks: {
-*     'kubb:build:end'({ files }) {
-*       console.log(`Build complete with ${files.length} files`)
-*     },
-*   },
-* }))
-*
-* // Middleware with options and per-build state
-* export const prefixMiddleware = defineMiddleware((options: { prefix: string } = { prefix: '' }) => {
-*   const seen = new Set<string>()
+* export const myRenderer = createRenderer(() => {
+*   const runtime = new MyRuntime()
 *   return {
-*     name: 'prefix-middleware',
-*     hooks: {
-*       'kubb:plugin:end'({ plugin }) {
-*         seen.add(`${options.prefix}${plugin.name}`)
-*       },
+*     async render(element) {
+*       await runtime.render(element)
+*     },
+*     get files() {
+*       return runtime.files
+*     },
+*     [Symbol.dispose]() {
+*       runtime.dispose()
 *     },
 *   }
 * })
 * ```
 */
-function defineMiddleware(factory) {
-	return (options) => factory(options ?? {});
+function createRenderer(factory) {
+	return factory;
 }
 //#endregion
-//#region src/defineParser.ts
+//#region src/defineGenerator.ts
 /**
-* Defines a parser with type safety. Creates parsers that transform generated files to strings based on their extension.
+* 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 Call the returned factory with optional options to instantiate the parser.
+* 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 { defineParser } from '@kubb/core'
+* @example JSX-based schema generator
+* ```tsx
+* import { defineGenerator } from '@kubb/core'
+* import { jsxRenderer } from '@kubb/renderer-jsx'
 *
-* export const jsonParser = defineParser({
-*   name: 'json',
-*   extNames: ['.json'],
-*   parse(file) {
-*     const { extractStringsFromNodes } = await import('@kubb/ast')
-*     return file.sources.map((s) => extractStringsFromNodes(s.nodes ?? [])).join('\n')
+* 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>
+*     )
 *   },
 * })
 * ```
 */
-function defineParser(parser) {
-	return parser;
+function defineGenerator(generator) {
+	return generator;
 }
 //#endregion
-//#region src/definePlugin.ts
+//#region src/defineParser.ts
 /**
-* Wraps a factory function and returns a typed `Plugin` with lifecycle handlers grouped under `hooks`.
+* 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.
 *
-* Handlers live in a single `hooks` object (inspired by Astro integrations).
-* All lifecycle events from `KubbHooks` are available for subscription.
-*
-* @note For real plugins, use a `PluginFactoryOptions` type parameter to get type-safe context in `kubb:plugin:setup`.
-* Plugin names should follow the convention `plugin-<feature>` (e.g., `plugin-react-query`, `plugin-zod`).
+* Register the result in the `parsers` array on `defineConfig`, calling it to
+* apply options (`parserTs({ extension: { '.ts': '.js' } })`).
 *
 * @example
 * ```ts
-* import { definePlugin } from '@kubb/core'
+* import { defineParser } from '@kubb/core'
+* import { extractStringsFromNodes } from '@kubb/ast'
 *
-* export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
-*   name: 'plugin-ts',
-*   hooks: {
-*     'kubb:plugin:setup'(ctx) {
-*       ctx.setResolver(resolverTs)
-*     },
+* export const parserJson = defineParser((options: { pretty?: boolean } = {}) => ({
+*   name: 'json',
+*   extNames: ['.json'],
+*   parse(file) {
+*     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 definePlugin(factory) {
+function defineParser(factory) {
 	return (options) => factory(options ?? {});
 }
 //#endregion
@@ -1404,7 +2540,7 @@ function definePlugin(factory) {
 * import { defineConfig } from 'kubb'
 *
 * export default defineConfig({
-*   input:  { path: './petStore.yaml' },
+*   input:  './petStore.yaml',
 *   output: { path: './src/gen' },
 *   storage: memoryStorage(),
 * })
@@ -1440,30 +2576,26 @@ const memoryStorage = createStorage(() => {
 	};
 });
 //#endregion
-exports.AsyncEventEmitter = AsyncEventEmitter;
-exports.FileManager = require_PluginDriver.FileManager;
-exports.FileProcessor = FileProcessor;
-exports.PluginDriver = require_PluginDriver.PluginDriver;
-exports.URLPath = URLPath;
-Object.defineProperty(exports, "ast", {
-	enumerable: true,
-	get: function() {
-		return _kubb_ast;
-	}
-});
+exports.Diagnostics = Diagnostics;
+exports.Hookable = require_usingCtx.Hookable;
+exports.KubbDriver = KubbDriver;
+exports.Resolver = Resolver;
+exports.applyConfigDefaults = applyConfigDefaults;
+exports.cliReporter = cliReporter;
 exports.createAdapter = createAdapter;
 exports.createKubb = createKubb;
 exports.createRenderer = createRenderer;
+exports.createReporter = createReporter;
+exports.createResolver = createResolver;
 exports.createStorage = createStorage;
 exports.defineGenerator = defineGenerator;
-exports.defineLogger = defineLogger;
-exports.defineMiddleware = defineMiddleware;
 exports.defineParser = defineParser;
 exports.definePlugin = definePlugin;
-exports.defineResolver = require_PluginDriver.defineResolver;
+exports.fileReporter = fileReporter;
 exports.fsStorage = fsStorage;
-exports.isInputPath = isInputPath;
-exports.logLevel = require_PluginDriver.logLevel;
+exports.getInputKind = getInputKind;
+exports.jsonReporter = jsonReporter;
+exports.logLevel = logLevel;
 exports.memoryStorage = memoryStorage;
 
 //# sourceMappingURL=index.cjs.map