@kubb/core 5.0.0-beta.6 → 5.0.0-beta.61

package/dist/index.js

@@ -1,201 +1,173 @@
-import { t as __name } from "./chunk--u3MIqq1.js";
-import { a as DEFAULT_BANNER, c as logLevel, i as defineResolver, l as camelCase, n as applyHookResult, o as DEFAULT_EXTENSION, r as FileManager, s as DEFAULT_STUDIO_URL, t as PluginDriver } from "./PluginDriver-BkTRD2H2.js";
-import { EventEmitter } from "node:events";
-import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
+import "./chunk-C0LytTxp.js";
+import { a as createStorage, c as camelCase, d as BuildError, f as getErrorMessage, i as FileManager, l as pascalCase, n as _usingCtx, o as OPERATION_FILTER_TYPES, r as FileProcessor, s as diagnosticCode, t as memoryStorage, u as AsyncEventEmitter } from "./memoryStorage-CWFzAz4o.js";
+import { hash } from "node:crypto";
+import { stripVTControlCharacters, styleText } from "node:util";
+import { access, glob, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path, { dirname, join, relative, resolve } from "node:path";
 import * as ast from "@kubb/ast";
-import { collectUsedSchemaNames, extractStringsFromNodes, transform, walk } from "@kubb/ast";
-import { version } from "node:process";
-//#region ../../internals/utils/src/errors.ts
+import { composeMacros, operationDef, schemaDef, transform } from "@kubb/ast";
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as factory from "@kubb/ast/factory";
+import { collectUsedSchemaNames } from "@kubb/ast/utils";
+import process$1 from "node:process";
+//#region ../../internals/utils/src/time.ts
 /**
-* Thrown when one or more errors occur during a Kubb build.
-* Carries the full list of underlying errors on `errors`.
+* Calculates elapsed time in milliseconds from a high-resolution `process.hrtime` start time.
+* Rounds to 2 decimal places for sub-millisecond precision without noise.
 *
 * @example
 * ```ts
-* throw new BuildError('Build failed', { errors: [err1, err2] })
+* const start = process.hrtime()
+* doWork()
+* getElapsedMs(start) // 42.35
 * ```
 */
-var BuildError = class extends Error {
-	errors;
-	constructor(message, options) {
-		super(message, { cause: options.cause });
-		this.name = "BuildError";
-		this.errors = options.errors;
-	}
-};
+function getElapsedMs(hrStart) {
+	const [seconds, nanoseconds] = process.hrtime(hrStart);
+	const ms = seconds * 1e3 + nanoseconds / 1e6;
+	return Math.round(ms * 100) / 100;
+}
 /**
-* 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)`.
+* Converts a millisecond duration into a human-readable string (`ms`, `s`, or `m s`).
 *
 * @example
 * ```ts
-* try { ... } catch(err) {
-*   throw new BuildError('Build failed', { cause: toError(err), errors: [] })
-* }
+* formatMs(250)   // '250ms'
+* formatMs(1500)  // '1.50s'
+* formatMs(90000) // '1m 30.0s'
 * ```
 */
-function toError(value) {
-	return value instanceof Error ? value : new Error(String(value));
+function formatMs(ms) {
+	if (ms >= 6e4) return `${Math.floor(ms / 6e4)}m ${(ms % 6e4 / 1e3).toFixed(1)}s`;
+	if (ms >= 1e3) return `${(ms / 1e3).toFixed(2)}s`;
+	return `${Math.round(ms)}ms`;
 }
 //#endregion
-//#region ../../internals/utils/src/asyncEventEmitter.ts
+//#region ../../internals/utils/src/colors.ts
+/**
+* Parses a CSS hex color string (`#RGB`) into its RGB channels.
+* Falls back to `255` for any channel that cannot be parsed.
+*/
+function parseHex(color) {
+	const int = Number.parseInt(color.replace("#", ""), 16);
+	return Number.isNaN(int) ? {
+		r: 255,
+		g: 255,
+		b: 255
+	} : {
+		r: int >> 16 & 255,
+		g: int >> 8 & 255,
+		b: int & 255
+	};
+}
+/**
+* Returns a function that wraps a string in a 24-bit ANSI true-color escape sequence
+* for the given hex color.
+*/
+function hex(color) {
+	const { r, g, b } = parseHex(color);
+	return (text) => `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+}
+hex("#F55A17"), hex("#F5A217"), hex("#F58517"), hex("#B45309"), hex("#FFFFFF"), hex("#adadc6"), hex("#FDA4AF");
+/**
+* ANSI color names used by {@link randomCliColor} for deterministic terminal coloring.
+*/
+const randomColors = [
+	"black",
+	"red",
+	"green",
+	"yellow",
+	"blue",
+	"white",
+	"magenta",
+	"cyan",
+	"gray"
+];
 /**
-* Typed `EventEmitter` that awaits all async listeners before resolving.
-* Wraps Node's `EventEmitter` with full TypeScript event-map inference.
+* Wraps `text` in a deterministic ANSI color derived from the text's SHA-256 hash.
 *
 * @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
+* randomCliColor('petstore') // '\x1b[33m' + 'petstore' + '\x1b[39m' (always the same color for 'petstore')
 * ```
 */
-var AsyncEventEmitter = class {
-	/**
-	* Maximum number of listeners per event before Node emits a memory-leak warning.
-	* @default 10
-	*/
-	constructor(maxListener = 10) {
-		this.#emitter.setMaxListeners(maxListener);
-	}
-	#emitter = new EventEmitter();
+function randomCliColor(text) {
+	if (!text) return "";
+	return styleText(randomColors[hash("sha256", text, "buffer").readUInt32BE(0) % randomColors.length] ?? "white", text);
+}
+//#endregion
+//#region ../../internals/utils/src/runtime.ts
+/**
+* Detects the JavaScript runtime executing the current process and exposes its name and version.
+*
+* Prefer the shared {@link runtime} instance over constructing your own.
+*/
+var Runtime = class {
 	/**
-	* Emits `eventName` and awaits all registered listeners sequentially.
-	* Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
+	* `true` when the current process is running under Bun.
 	*
-	* @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) });
-		}
-	}
-	/**
-	* Registers a persistent listener for `eventName`.
+	* Detection keys off the global `Bun` object rather than `process.versions`,
+	* because Bun polyfills `process.versions.node` for Node compatibility and would
+	* otherwise look like Node.
 	*
 	* @example
 	* ```ts
-	* emitter.on('build', async (name) => { console.log(name) })
+	* if (runtime.isBun) {
+	*   await Bun.write(path, data)
+	* }
 	* ```
 	*/
-	on(eventName, handler) {
-		this.#emitter.on(eventName, handler);
+	get isBun() {
+		return typeof Bun !== "undefined";
 	}
 	/**
-	* Registers a one-shot listener that removes itself after the first invocation.
-	*
-	* @example
-	* ```ts
-	* emitter.onOnce('build', async (name) => { console.log(name) })
-	* ```
+	* `true` when the current process is running under Deno.
 	*/
-	onOnce(eventName, handler) {
-		const wrapper = (...args) => {
-			this.off(eventName, wrapper);
-			return handler(...args);
-		};
-		this.on(eventName, wrapper);
+	get isDeno() {
+		return typeof globalThis.Deno !== "undefined";
 	}
 	/**
-	* Removes a previously registered listener.
+	* `true` when the current process is running under Node.
 	*
-	* @example
-	* ```ts
-	* emitter.off('build', handler)
-	* ```
+	* Bun and Deno are excluded first so a polyfilled `process` does not register as Node.
 	*/
-	off(eventName, handler) {
-		this.#emitter.off(eventName, handler);
+	get isNode() {
+		return !this.isBun && !this.isDeno && typeof process !== "undefined" && process.versions?.node != null;
 	}
 	/**
-	* Returns the number of listeners registered for `eventName`.
+	* Name of the runtime executing the current process.
 	*
 	* @example
 	* ```ts
-	* emitter.on('build', handler)
-	* emitter.listenerCount('build') // 1
+	* runtime.name // 'bun' when run with `bun kubb`, 'node' otherwise
 	* ```
 	*/
-	listenerCount(eventName) {
-		return this.#emitter.listenerCount(eventName);
+	get name() {
+		if (this.isBun) return "bun";
+		if (this.isDeno) return "deno";
+		return "node";
 	}
 	/**
-	* Removes all listeners from every event channel.
+	* Version of the active runtime, or an empty string when it cannot be read.
 	*
 	* @example
 	* ```ts
-	* emitter.removeAll()
+	* runtime.version // '1.3.11' under Bun, '22.22.2' under Node
 	* ```
 	*/
-	removeAll() {
-		this.#emitter.removeAllListeners();
+	get version() {
+		if (this.isBun) return process.versions.bun ?? "";
+		if (this.isDeno) return globalThis.Deno?.version?.deno ?? "";
+		return process.versions?.node ?? "";
 	}
 };
-//#endregion
-//#region ../../internals/utils/src/time.ts
-/**
-* Calculates elapsed time in milliseconds from a high-resolution `process.hrtime` start time.
-* Rounds to 2 decimal places for sub-millisecond precision without noise.
-*
-* @example
-* ```ts
-* const start = process.hrtime()
-* doWork()
-* getElapsedMs(start) // 42.35
-* ```
-*/
-function getElapsedMs(hrStart) {
-	const [seconds, nanoseconds] = process.hrtime(hrStart);
-	const ms = seconds * 1e3 + nanoseconds / 1e6;
-	return Math.round(ms * 100) / 100;
-}
 /**
-* Converts a millisecond duration into a human-readable string (`ms`, `s`, or `m s`).
-*
-* @example
-* ```ts
-* formatMs(250)   // '250ms'
-* formatMs(1500)  // '1.50s'
-* formatMs(90000) // '1m 30.0s'
-* ```
+* Shared {@link Runtime} instance describing the JavaScript runtime executing the current process.
 */
-function formatMs(ms) {
-	if (ms >= 6e4) return `${Math.floor(ms / 6e4)}m ${(ms % 6e4 / 1e3).toFixed(1)}s`;
-	if (ms >= 1e3) return `${(ms / 1e3).toFixed(2)}s`;
-	return `${Math.round(ms)}ms`;
-}
+const runtime = new Runtime();
 //#endregion
 //#region ../../internals/utils/src/fs.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')
-* }
-* ```
-*/
-async function exists(path) {
-	if (typeof Bun !== "undefined") return Bun.file(path).exists();
-	return access(path).then(() => true, () => false);
-}
-/**
 * 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.
@@ -212,7 +184,7 @@ async function write(path, data, options = {}) {
 	const trimmed = data.trim();
 	if (trimmed === "") return null;
 	const resolved = resolve(path);
-	if (typeof Bun !== "undefined") {
+	if (runtime.isBun) {
 		const file = Bun.file(resolved);
 		if ((await file.exists() ? await file.text() : null) === trimmed) return null;
 		await Bun.write(resolved, trimmed);
@@ -244,6 +216,156 @@ async function clean(path) {
 		force: true
 	});
 }
+/**
+* Converts a filesystem path to use POSIX (`/`) separators.
+*
+* Most of the codebase compares and composes paths as strings (prefix matching, joining for
+* import specifiers, splitting on `/`). On POSIX `path.resolve` already returns `/`-separated
+* paths, but on Windows it returns `\`-separated paths, which breaks every such comparison.
+*
+* Routing every path that crosses a module boundary through `toPosixPath` keeps the rest of the
+* code platform-agnostic. The conversion runs unconditionally so Windows-specific behavior is
+* exercisable from POSIX CI.
+*
+* @example
+* toPosixPath('C:\\repo\\src\\pet.ts') // 'C:/repo/src/pet.ts'
+*/
+function toPosixPath(filePath) {
+	return filePath.replaceAll("\\", "/");
+}
+/**
+* Builds a nested file path from a dotted name. Splits on dots that precede a letter
+* (so version numbers embedded in operationIds like `v2025.0` stay intact), camelCases
+* every earlier segment, applies `caseLast` to the final segment, and joins with `/`.
+*
+* Empty segments are dropped before joining. They arise when the name starts with a dot
+* followed by a letter (e.g. `..Schema` splits into `['..', 'Schema']` and `'..'` cases to
+* an empty string). Without this a leading `/` would form, which `path.resolve` reads as an
+* absolute path, letting generated files escape the configured output directory.
+*
+* @example Nested path from a dotted name
+* `toFilePath('pet.petId') // 'pet/petId'`
+*
+* @example PascalCase the final segment
+* `toFilePath('pet.Pet', pascalCase) // 'pet/Pet'`
+*
+* @example Suffix applied to the final segment only
+* `toFilePath('tag.tag', (part) => camelCase(part, { suffix: 'schema' })) // 'tag/tagSchema'`
+*/
+function toFilePath(name, caseLast = camelCase) {
+	const parts = name.split(/\.(?=[a-zA-Z])/);
+	return parts.map((part, i) => i === parts.length - 1 ? caseLast(part) : camelCase(part)).filter(Boolean).join("/");
+}
+//#endregion
+//#region ../../internals/utils/src/promise.ts
+function* chunks(arr, size) {
+	for (let i = 0; i < arr.length; i += size) yield arr.slice(i, i + size);
+}
+/**
+* Slices `source` into batches of `concurrency` items and awaits `process` for each batch.
+* Accepts both plain arrays (sync) and `AsyncIterable` (streaming).
+*
+* `process` controls whether items inside a batch run in parallel; this helper only
+* controls batch size and per-batch flushing.
+*
+* @example
+* ```ts
+* // parallel dispatch inside each batch
+* await forBatches(schemas, (batch) => Promise.all(batch.map(process)), { concurrency: 8 })
+*
+* // async iterable with a flush after every batch
+* await forBatches(stream.schemas, (batch) => dispatch(batch), { concurrency: 8, flush })
+* ```
+*/
+async function forBatches(source, process, options) {
+	const { concurrency, flush } = options;
+	if (Array.isArray(source)) {
+		for (const batch of chunks(source, concurrency)) {
+			await process(batch);
+			if (flush) await flush();
+		}
+		return;
+	}
+	const batch = [];
+	for await (const item of source) {
+		batch.push(item);
+		if (batch.length >= concurrency) {
+			await process(batch.splice(0));
+			if (flush) await flush();
+		}
+	}
+	if (batch.length > 0) {
+		await process(batch.splice(0));
+		if (flush) await flush();
+	}
+}
+/** Returns `true` when `result` is a thenable `Promise`.
+*
+* @example
+* ```ts
+* isPromise(Promise.resolve(1)) // true
+* isPromise(42)                 // false
+* ```
+*/
+function isPromise(result) {
+	return result !== null && result !== void 0 && typeof result["then"] === "function";
+}
+/**
+* Wraps `factory` with a keyed cache backed by the provided store.
+*
+* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
+* collected) or a `Map` for primitive keys. For multi-argument functions,
+* nest two `memoize` calls — the outer keyed by the first argument, the
+* inner (created once per outer miss) keyed by the second.
+*
+* Because the cache is owned by the caller, it can be shared, inspected, or
+* cleared independently of the memoized function.
+*
+* @example Single WeakMap key
+* ```ts
+* const cache = new WeakMap<SchemaNode, Set<string>>()
+* const getRefs = memoize(cache, (node) => collectRefs(node))
+* ```
+*
+* @example Single Map key (primitive)
+* ```ts
+* const cache = new Map<string, Resolver>()
+* const getResolver = memoize(cache, (name) => buildResolver(name))
+* ```
+*
+* @example Two-level (object + primitive)
+* ```ts
+* const outer = new WeakMap<Params[], Map<string, Params[]>>()
+* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
+* fn(params)('camelcase')
+* ```
+*/
+function memoize(store, factory) {
+	return (key) => {
+		if (store.has(key)) return store.get(key);
+		const value = factory(key);
+		store.set(key, value);
+		return value;
+	};
+}
+/**
+* Wraps a plain array in a reusable `AsyncIterable`.
+* Each `[Symbol.asyncIterator]()` call returns a fresh generator so the
+* iterable can be consumed multiple times (e.g. once per plugin pre-scan).
+*
+* @example
+* ```ts
+* const stream = arrayToAsyncIterable([1, 2, 3])
+* for await (const n of stream) console.log(n) // 1, 2, 3
+* ```
+*/
+function arrayToAsyncIterable(arr) {
+	return { [Symbol.asyncIterator]() {
+		return (async function* () {
+			yield* arr;
+		})();
+	} };
+}
 //#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
@@ -345,102 +467,99 @@ const reservedWords = new Set([
 */
 function isValidVarName(name) {
 	if (!name || reservedWords.has(name)) return false;
-	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+	return isIdentifier(name);
 }
-//#endregion
-//#region ../../internals/utils/src/urlPath.ts
 /**
-* Parses and transforms an OpenAPI/Swagger path string into various URL formats.
+* Returns `true` when `name` is syntactically a valid identifier, ignoring reserved words.
+*
+* Reserved words and globals (`class`, `name`, `Date`, …) are valid as bare object-literal keys
+* even though they are not valid variable names, so use this (not {@link isValidVarName}) when
+* deciding whether an object key needs quoting.
 *
 * @example
-* const p = new URLPath('/pet/{petId}')
-* p.URL      // '/pet/:petId'
-* p.template // '`/pet/${petId}`'
+* ```ts
+* isIdentifier('name')   // true
+* isIdentifier('x-total')// false
+* ```
 */
-var URLPath = class {
-	/**
-	* The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
-	*/
-	path;
-	#options;
-	constructor(path, options = {}) {
-		this.path = path;
-		this.#options = options;
+function isIdentifier(name) {
+	return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name);
+}
+//#endregion
+//#region ../../internals/utils/src/url.ts
+function transformParam(raw, casing) {
+	const param = isValidVarName(raw) ? raw : camelCase(raw);
+	return casing === "camelcase" ? camelCase(param) : param;
+}
+function toParamsObject(path, { replacer, casing } = {}) {
+	const params = {};
+	for (const match of path.matchAll(/\{([^}]+)\}/g)) {
+		const param = transformParam(match[1], casing);
+		const key = replacer ? replacer(param) : param;
+		params[key] = key;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
+	return Object.keys(params).length > 0 ? params : null;
+}
+/**
+* Helpers for OpenAPI/Swagger paths, plus a thin wrapper over the native `URL`.
+*/
+var Url = class Url {
+	/**
+	* Reports whether `url` is a parseable absolute URL. Delegates to the native `URL.canParse`.
 	*
 	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
-	* ```
+	* Url.canParse('https://petstore.swagger.io/v2') // true
+	* Url.canParse('/pet/{petId}')                   // false
 	*/
-	get URL() {
-		return this.toURLPath();
+	static canParse(url, base) {
+		return URL.canParse(url, base);
 	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
+	/**
+	* Converts an OpenAPI/Swagger path to Express-style colon syntax.
 	*
 	* @example
-	* ```ts
-	* new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
-	* new URLPath('/pet/{petId}').isURL                       // false
-	* ```
+	* Url.toPath('/pet/{petId}') // '/pet/:petId'
 	*/
-	get isURL() {
-		try {
-			return !!new URL(this.path).href;
-		} catch {
-			return false;
-		}
+	static toPath(path) {
+		return path.replace(/\{([^}]+)\}/g, ":$1");
 	}
 	/**
-	* Converts the OpenAPI path to a TypeScript template literal string.
+	* Converts an OpenAPI/Swagger path to a TypeScript template literal string.
+	* `prefix` is prepended inside the literal, `replacer` transforms each parameter name,
+	* and `casing` controls parameter identifier casing.
 	*
 	* @example
-	* new URLPath('/pet/{petId}').template              // '`/pet/${petId}`'
-	* new URLPath('/account/monetary-accountID').template // '`/account/${monetaryAccountId}`'
-	*/
-	get template() {
-		return this.toTemplateString();
-	}
-	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
+	* Url.toTemplateString('/pet/{petId}') // '`/pet/${petId}`'
 	*
 	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').object
-	* // { url: '/pet/:petId', params: { petId: 'petId' } }
-	* ```
+	* Url.toTemplateString('/pet/{petId}', { prefix: 'https://api' }) // '`https://api/pet/${petId}`'
 	*/
-	get object() {
-		return this.toObject();
+	static toTemplateString(path, { prefix, replacer, casing } = {}) {
+		const result = path.split(/\{([^}]+)\}/).map((part, i) => {
+			if (i % 2 === 0) return part;
+			const param = transformParam(part, casing);
+			return `\${${replacer ? replacer(param) : param}}`;
+		}).join("");
+		return `\`${prefix ?? ""}${result}\``;
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	/**
+	* 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}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
-	* ```
-	*/
-	get params() {
-		return this.getParams();
-	}
-	#transformParam(raw) {
-		const param = isValidVarName(raw) ? raw : camelCase(raw);
-		return this.#options.casing === "camelcase" ? camelCase(param) : param;
-	}
-	/**
-	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	* Url.toObject('/pet/{petId}')
+	* // { url: '/pet/:petId', params: { petId: 'petId' } }
 	*/
-	#eachParam(fn) {
-		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
-			const raw = match[1];
-			fn(raw, this.#transformParam(raw));
-		}
-	}
-	toObject({ type = "path", replacer, stringify } = {}) {
+	static toObject(path, { type = "path", replacer, stringify, casing } = {}) {
 		const object = {
-			url: type === "path" ? this.toURLPath() : this.toTemplateString({ replacer }),
-			params: this.getParams()
+			url: type === "path" ? Url.toPath(path) : Url.toTemplateString(path, {
+				replacer,
+				casing
+			}),
+			params: toParamsObject(path, {
+				replacer,
+				casing
+			})
 		};
 		if (stringify) {
 			if (type === "template") return JSON.stringify(object).replaceAll("'", "").replaceAll(`"`, "");
@@ -449,761 +568,1756 @@ var URLPath = class {
 		}
 		return object;
 	}
-	/**
-	* 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}`'
-	*/
-	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("")}\``;
-	}
-	/**
-	* 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' }
-	* ```
-	*/
-	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;
-	}
-	/** Converts the OpenAPI path to Express-style colon syntax.
-	*
-	* @example
-	* ```ts
-	* new URLPath('/pet/{petId}').toURLPath() // '/pet/:petId'
-	* ```
-	*/
-	toURLPath() {
-		return this.path.replace(/\{([^}]+)\}/g, ":$1");
-	}
 };
 //#endregion
 //#region src/createAdapter.ts
 /**
-* Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+* 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.
 *
-* Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
-* Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
-*
-* @note Adapters must parse their input format to Kubb's `InputNode` structure.
+* Adapters must return an `InputNode` from `parse`. That node is what every
+* plugin in the build consumes.
 *
 * @example
 * ```ts
-* export const myAdapter = createAdapter<MyAdapter>((options) => {
-*   return {
-*     name: 'my-adapter',
-*     options,
-*     async parse(source) {
-*       // Transform source format to InputNode
-*       return { ... }
-*     },
-*   }
-* })
+* import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+*
+* type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
 *
-* // Instantiate:
-* const adapter = myAdapter({ validate: true })
+* export const myAdapter = createAdapter<MyAdapter>((options) => ({
+*   name: 'my-adapter',
+*   options,
+*   document: null,
+*   async parse(_source) {
+*     // Convert `source` (path or inline data) into an InputNode.
+*     return ast.factory.createInput()
+*   },
+*   getImports: () => [],
+*   async validate() {
+*     // Throw or call ctx.error here when the spec is invalid.
+*   },
+* }))
 * ```
 */
 function createAdapter(build) {
 	return (options) => build(options ?? {});
 }
 //#endregion
-//#region ../../node_modules/.pnpm/yocto-queue@1.2.2/node_modules/yocto-queue/index.js
-var Node$1 = class {
-	static {
-		__name(this, "Node");
-	}
-	value;
-	next;
-	constructor(value) {
-		this.value = value;
-	}
-};
-var Queue = class {
-	#head;
-	#tail;
-	#size;
-	constructor() {
-		this.clear();
-	}
-	enqueue(value) {
-		const node = new Node$1(value);
-		if (this.#head) {
-			this.#tail.next = node;
-			this.#tail = node;
-		} else {
-			this.#head = node;
-			this.#tail = node;
-		}
-		this.#size++;
-	}
-	dequeue() {
-		const current = this.#head;
-		if (!current) return;
-		this.#head = this.#head.next;
-		this.#size--;
-		if (!this.#head) this.#tail = void 0;
-		return current.value;
-	}
-	peek() {
-		if (!this.#head) return;
-		return this.#head.value;
-	}
-	clear() {
-		this.#head = void 0;
-		this.#tail = void 0;
-		this.#size = 0;
-	}
-	get size() {
-		return this.#size;
-	}
-	*[Symbol.iterator]() {
-		let current = this.#head;
-		while (current) {
-			yield current.value;
-			current = current.next;
-		}
-	}
-	*drain() {
-		while (this.#head) yield this.dequeue();
-	}
-};
-//#endregion
-//#region ../../node_modules/.pnpm/p-limit@7.3.0/node_modules/p-limit/index.js
-function pLimit(concurrency) {
-	let rejectOnClear = false;
-	if (typeof concurrency === "object") ({concurrency, rejectOnClear = false} = concurrency);
-	validateConcurrency(concurrency);
-	if (typeof rejectOnClear !== "boolean") throw new TypeError("Expected `rejectOnClear` to be a boolean");
-	const queue = new Queue();
-	let activeCount = 0;
-	const resumeNext = () => {
-		if (activeCount < concurrency && queue.size > 0) {
-			activeCount++;
-			queue.dequeue().run();
-		}
-	};
-	const next = () => {
-		activeCount--;
-		resumeNext();
-	};
-	const run = async (function_, resolve, arguments_) => {
-		const result = (async () => function_(...arguments_))();
-		resolve(result);
-		try {
-			await result;
-		} catch {}
-		next();
-	};
-	const enqueue = (function_, resolve, reject, arguments_) => {
-		const queueItem = { reject };
-		new Promise((internalResolve) => {
-			queueItem.run = internalResolve;
-			queue.enqueue(queueItem);
-		}).then(run.bind(void 0, function_, resolve, arguments_));
-		if (activeCount < concurrency) resumeNext();
-	};
-	const generator = (function_, ...arguments_) => new Promise((resolve, reject) => {
-		enqueue(function_, resolve, reject, arguments_);
-	});
-	Object.defineProperties(generator, {
-		activeCount: { get: () => activeCount },
-		pendingCount: { get: () => queue.size },
-		clearQueue: { value() {
-			if (!rejectOnClear) {
-				queue.clear();
-				return;
-			}
-			const abortError = AbortSignal.abort().reason;
-			while (queue.size > 0) queue.dequeue().reject(abortError);
-		} },
-		concurrency: {
-			get: () => concurrency,
-			set(newConcurrency) {
-				validateConcurrency(newConcurrency);
-				concurrency = newConcurrency;
-				queueMicrotask(() => {
-					while (activeCount < concurrency && queue.size > 0) resumeNext();
-				});
-			}
-		},
-		map: { async value(iterable, function_) {
-			const promises = Array.from(iterable, (value, index) => this(function_, value, index));
-			return Promise.all(promises);
-		} }
-	});
-	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) => extractStringsFromNodes(item.nodes)).filter(Boolean).join("\n\n");
-}
+//#region src/diagnostics.ts
 /**
-* Converts a single file to a string using the registered parsers.
-* Falls back to joining source values when no matching parser is found.
-*
-* @internal
+* Docs major version, derived from the package version so the link tracks the published major.
 */
-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
-			});
-			const currentProcessed = ++processed;
-			const percentage = currentProcessed / total * 100;
-			await onUpdate?.({
-				file,
-				source,
-				processed: currentProcessed,
-				percentage,
-				total
-			});
-		};
-		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;
-	}
-};
-//#endregion
-//#region src/createStorage.ts
+const docsMajor = "5.0.0-beta.61".split(".")[0] ?? "5";
 /**
-* 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.
-*
-* @note Call the returned factory with optional options to instantiate the storage adapter.
+* Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
 *
 * @example
 * ```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 getKeys(base) {
-*       const keys = [...store.keys()]
-*       return base ? keys.filter((k) => k.startsWith(base)) : keys
-*     },
-*     async clear(base) { if (!base) store.clear() },
-*   }
-* })
-*
-* // Instantiate:
-* const storage = memoryStorage()
+* const update = narrow(diagnostic, diagnosticCode.updateAvailable)
+* if (update) {
+*   console.log(update.latestVersion)
+* }
 * ```
 */
-function createStorage(build) {
-	return (options) => build(options ?? {});
+function narrow(diagnostic, code) {
+	return diagnostic.code === code ? diagnostic : null;
 }
-//#endregion
-//#region src/storages/fsStorage.ts
 /**
-* Detects the filesystem error used to indicate that a path does not exist.
+* 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 isMissingPathError(error) {
-	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+function isKind(kind) {
+	return (diagnostic) => (diagnostic.kind ?? "problem") === kind;
 }
 /**
-* Built-in filesystem storage driver.
-*
-* This is the default storage when no `storage` option is configured in the root config.
-* 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.
+* Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
 *
-* 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
+* @example
+* ```ts
+* if (isProblem(diagnostic)) {
+*   console.log(diagnostic.location)
+* }
+* ```
+*/
+const isProblem = isKind("problem");
+/**
+* Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
 *
 * @example
 * ```ts
-* import { fsStorage } from '@kubb/core'
-* import { defineConfig } from 'kubb'
+* const timings = diagnostics.filter(isPerformance)
+* ```
+*/
+const isPerformance = isKind("performance");
+/**
+* Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
 *
-* export default defineConfig({
-*   input:  { path: './petStore.yaml' },
-*   output: { path: './src/gen' },
-*   storage: fsStorage(),
-* })
+* @example
+* ```ts
+* if (isUpdate(diagnostic)) {
+*   console.log(diagnostic.latestVersion)
+* }
 * ```
 */
-const fsStorage = createStorage(() => ({
-	name: "fs",
-	async hasItem(key) {
-		try {
-			await access(resolve(key));
-			return true;
-		} catch (error) {
-			if (isMissingPathError(error)) return false;
-			throw new Error(`Failed to access storage item "${key}"`, { cause: error });
-		}
+const isUpdate = isKind("update");
+/**
+* Glyph and accent color per severity, matching the miette/oxlint convention
+* (`×` error, `⚠` warning, `ℹ` advice).
+*/
+const severityStyle = {
+	error: {
+		glyph: "×",
+		color: "red"
 	},
-	async getItem(key) {
-		try {
-			return await readFile(resolve(key), "utf8");
-		} catch (error) {
-			if (isMissingPathError(error)) return null;
-			throw new Error(`Failed to read storage item "${key}"`, { cause: error });
-		}
+	warning: {
+		glyph: "⚠",
+		color: "yellow"
 	},
-	async setItem(key, value) {
-		await write(resolve(key), value, { sanity: false });
+	info: {
+		glyph: "ℹ",
+		color: "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."
 	},
-	async removeItem(key) {
-		await rm(resolve(key), { force: true });
+	[diagnosticCode.inputNotFound]: {
+		title: "Input not found",
+		cause: "The file or URL set in `input.path` (or passed as `kubb generate PATH`) could not be read.",
+		fix: "Check that the path or URL exists and is readable, then set it in `input.path` or pass it on the CLI."
 	},
-	async getKeys(base) {
-		const keys = [];
-		const resolvedBase = resolve(base ?? process.cwd());
-		async function walk(dir, prefix) {
-			let entries;
-			try {
-				entries = await readdir(dir, { withFileTypes: true });
-			} catch (error) {
-				if (isMissingPathError(error)) return;
-				throw new Error(`Failed to list storage keys under "${resolvedBase}"`, { cause: error });
-			}
-			for (const entry of entries) {
-				const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-				if (entry.isDirectory()) await walk(join(dir, entry.name), rel);
-				else keys.push(rel);
-			}
-		}
-		await walk(resolvedBase, "");
-		return keys;
+	[diagnosticCode.inputRequired]: {
+		title: "Input required",
+		cause: "An adapter is configured but no `input` was provided.",
+		fix: "Set `input.path` (a file or URL) or `input.data` (an inline spec) in your Kubb config."
 	},
-	async clear(base) {
-		if (!base) return;
-		await clean(resolve(base));
+	[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.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.hookFailed]: {
+		title: "Hook failed",
+		cause: "A post-generate shell hook (`hooks.done`) 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."
 	}
-}));
-//#endregion
-//#region package.json
-var version$1 = "5.0.0-beta.6";
-//#endregion
-//#region src/utils/diagnostics.ts
+};
 /**
-* Returns a snapshot of the current runtime environment.
+* Static helpers for working with {@link Diagnostic}s, plus the run-scoped sink
+* that lets deep code report a diagnostic without threading a callback.
 *
-* Useful for attaching context to debug logs and error reports so that
-* issues can be reproduced without manual information gathering.
+* 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 lazily consumed stream, a generator) reports through
+* `Diagnostics.report` and lands in the same run.
 */
-function getDiagnosticInfo() {
-	return {
-		nodeVersion: version,
-		KubbVersion: version$1,
-		platform: process.platform,
-		arch: process.arch,
-		cwd: process.cwd()
+var Diagnostics = class Diagnostics {
+	static #reporterStorage = new AsyncLocalStorage();
+	/**
+	* The diagnostic code catalog, exposed as `Diagnostics.code` (e.g. `Diagnostics.code.refNotFound`).
+	*/
+	static code = diagnosticCode;
+	/**
+	* Type guard for a build {@link ProblemDiagnostic}.
+	*/
+	static isProblem = isProblem;
+	/**
+	* Type guard for a version-update {@link UpdateDiagnostic}.
+	*/
+	static isUpdate = isUpdate;
+	/**
+	* Type guard for a per-plugin {@link PerformanceDiagnostic}.
+	*/
+	static isPerformance = isPerformance;
+	/**
+	* Narrows a {@link Diagnostic} to the variant for `code`, or `null` when it does not match.
+	*/
+	static narrow = narrow;
+	/**
+	* 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
+	* throw new Diagnostics.Error({ code: diagnosticCode.refNotFound, severity: 'error', message: `Could not find ${ref}`, location: { kind: 'schema', pointer: ref, ref } })
+	* ```
+	*/
+	static Error = class DiagnosticError extends Error {
+		diagnostic;
+		constructor(diagnostic) {
+			super(diagnostic.message, { cause: diagnostic.cause });
+			this.name = "DiagnosticError";
+			this.diagnostic = diagnostic;
+		}
 	};
-}
-//#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}`]
-			});
+	/**
+	* Structural check for a {@link Diagnostics.Error}, including one thrown from a duplicated
+	* `@kubb/core` copy where `instanceof` fails. Matches on the `name` and a `diagnostic`
+	* that carries a `code`.
+	*/
+	static isError(error) {
+		if (error instanceof Diagnostics.Error) return true;
+		return error instanceof Error && error.name === "DiagnosticError" && "diagnostic" in error && typeof error.diagnostic === "object" && error.diagnostic !== null && typeof error.diagnostic?.code === "string";
+	}
+	/**
+	* Runs `fn` with `sink` as the active diagnostic sink for the whole async
+	* subtree, so {@link Diagnostics.report} reaches it from anywhere inside.
+	*/
+	static scope(sink, fn) {
+		return Diagnostics.#reporterStorage.run(sink, fn);
+	}
+	/**
+	* Collects a diagnostic into the active build via the run-scoped sink, without throwing.
+	* Returns `true` when a run consumed it, `false` when called outside a {@link Diagnostics.scope}
+	* (so callers can fall back to throwing). Use a `warning`/`info` severity for non-fatal issues.
+	* For rendering a diagnostic live on the hook bus, use {@link Diagnostics.emit} instead.
+	*/
+	static report(diagnostic) {
+		const sink = Diagnostics.#reporterStorage.getStore();
+		if (!sink) return false;
+		sink(diagnostic);
+		return true;
+	}
+	/**
+	* Emits a diagnostic on the run's `kubb:diagnostic` event so the loggers render it live.
+	* Use it instead of calling `hooks.emit('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.emit("kubb:diagnostic", { diagnostic });
+	}
+	/**
+	* Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
+	* keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
+	*/
+	static from(error) {
+		const seen = /* @__PURE__ */ new Set();
+		let current = error;
+		let root;
+		while (current instanceof Error && !seen.has(current)) {
+			if (Diagnostics.isError(current)) return current.diagnostic;
+			seen.add(current);
+			root = current;
+			current = current.cause;
 		}
-	} 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 });
+		return {
+			code: diagnosticCode.unknown,
+			severity: "error",
+			message: root ? root.message : 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
+		};
+	}
+	/**
+	* 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
+		};
+	}
+	/**
+	* 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. `timing`
+	* 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 {
+			errors,
+			warnings,
+			infos
+		};
 	}
-	const config = {
-		...userConfig,
-		root: userConfig.root || process.cwd(),
-		parsers: userConfig.parsers ?? [],
-		adapter: userConfig.adapter,
-		output: {
-			format: false,
-			lint: false,
-			write: true,
-			extension: DEFAULT_EXTENSION,
-			defaultBanner: DEFAULT_BANNER,
-			...userConfig.output
-		},
-		devtools: userConfig.devtools ? {
-			studioUrl: 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(resolve(config.root, config.output.path));
-	}
-	const driver = new 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);
-	if (config.adapter) {
-		const source = inputToAdapterSource(config);
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`Running adapter: ${config.adapter.name}`]
-		});
-		driver.adapter = config.adapter;
-		driver.inputNode = await config.adapter.parse(source);
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [
-				`✓ Adapter '${config.adapter.name}' resolved InputNode`,
-				`  • Schemas: ${driver.inputNode.schemas.length}`,
-				`  • Operations: ${driver.inputNode.operations.length}`
-			]
-		});
+	/**
+	* Drops duplicate `problem` diagnostics that share a code, location pointer, and
+	* plugin, so the same issue reported across several passes is shown once. Non-problem
+	* diagnostics are always kept.
+	*/
+	static dedupe(diagnostics) {
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const diagnostic of diagnostics) {
+			if (!isProblem(diagnostic)) {
+				result.push(diagnostic);
+				continue;
+			}
+			const pointer = diagnostic.location && "pointer" in diagnostic.location ? diagnostic.location.pointer : "";
+			const key = `${diagnostic.code} ${pointer} ${diagnostic.plugin ?? ""}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			result.push(diagnostic);
+		}
+		return result;
+	}
+	/**
+	* 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`.
+	*/
+	static docsUrl(code) {
+		return `https://kubb.dev/docs/${docsMajor}.x/reference/diagnostics/${code.toLowerCase().replaceAll("_", "-")}`;
+	}
+	/**
+	* The catalog entry for a code: its title, cause, and fix. Mirrors the kubb.dev
+	* `/diagnostics/<slug>` page.
+	*/
+	static explain(code) {
+		return diagnosticCatalog[code];
+	}
+	/**
+	* Reduces a diagnostic to its JSON-safe fields plus a `docsUrl`, for machine-readable
+	* consumers. The `cause`, `kind`, and `duration` are dropped, and absent optional
+	* fields are omitted rather than set to `undefined`.
+	*/
+	static serialize(diagnostic) {
+		const problem = isProblem(diagnostic) ? diagnostic : void 0;
+		return {
+			code: diagnostic.code,
+			severity: diagnostic.severity,
+			message: diagnostic.message,
+			...problem?.location ? { location: problem.location } : {},
+			...problem?.help ? { help: problem.help } : {},
+			...problem?.plugin ? { plugin: problem.plugin } : {},
+			...diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
+		};
+	}
+	/**
+	* Renders a {@link Diagnostic} for terminal output as its parts: the colored severity `symbol`
+	* (the gutter glyph), the `plugin(CODE): message` `headline`, and the `details` lines (optional
+	* `at <pointer>`, `help:`, and `docs:`).
+	*
+	* Hosts compose these to fit their gutter: a clack logger passes `symbol` as its own gutter and
+	* `[headline, ...details]` as the message, while plain text outputs use {@link Diagnostics.formatLines}.
+	*/
+	static format(diagnostic) {
+		const { code, severity, message } = diagnostic;
+		const { glyph, color } = severityStyle[severity];
+		const problem = isProblem(diagnostic) ? diagnostic : void 0;
+		const rule = styleText(color, styleText("bold", problem?.plugin ? `${problem.plugin}(${code})` : code));
+		const details = [];
+		if (problem?.location && "pointer" in problem.location) details.push(`  ${styleText("dim", "at")} ${styleText("cyan", problem.location.pointer)}`);
+		if (problem?.help) details.push(`  ${styleText("cyan", "help:")} ${problem.help}`);
+		if (code !== diagnosticCode.unknown) details.push(`  ${styleText("dim", "docs:")} ${styleText("cyan", Diagnostics.docsUrl(code))}`);
+		return {
+			symbol: styleText(color, styleText("bold", glyph)),
+			headline: `${rule}: ${message}`,
+			details
+		};
+	}
+	/**
+	* The self-contained block form of {@link Diagnostics.format}: `${symbol} ${headline}` followed by
+	* the detail lines. Used where there is no gutter to own the symbol (plain and file output).
+	*/
+	static formatLines(diagnostic) {
+		const { symbol, headline, details } = Diagnostics.format(diagnostic);
+		return [`${symbol} ${headline}`, ...details];
 	}
+};
+//#endregion
+//#region src/definePlugin.ts
+/**
+* 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 ?? "directory";
+	if (mode === "file" && group) throw new Diagnostics.Error({
+		code: diagnosticCode.invalidPluginOptions,
+		severity: "error",
+		message: `Plugin "${pluginName}" sets \`output.mode: 'file'\` but also configures a \`group\` option.`,
+		help: "A single-file output has nothing to group. Remove the `group` option, or use `output.mode: 'directory'` to organize files into subdirectories.",
+		location: { kind: "config" },
+		plugin: pluginName
+	});
 	return {
-		config,
-		hooks,
-		driver,
-		sources,
-		storage
+		...output,
+		mode
 	};
 }
 /**
-* Walks the AST and dispatches nodes to a plugin's direct AST hooks
-* (`schema`, `operation`, `operations`).
-*
-* When `include` contains only operation-scoped filters (`tag`, `operationId`, `path`,
-* `method`, `contentType`) and no `schemaName` filter, the function pre-computes the set
-* of top-level schema names transitively reachable from the included operations and skips
-* schemas that fall outside that set. This ensures that component schemas referenced
-* exclusively by excluded operations are not generated.
+* 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.
+*
+* Pass a `PluginFactoryOptions` type parameter to get a typed `ctx` inside
+* `kubb:plugin:setup`. Plugin names should follow the `plugin-<feature>`
+* convention (`plugin-react-query`, `plugin-zod`, ...).
+*
+* @example
+* ```ts
+* import { 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/defineResolver.ts
+/**
+* Merges document `meta` with per-file `file` context into the `BannerMeta` passed to a
+* `banner`/`footer` function. Missing fields default to empty/`false` so the object shape
+* is stable even when a caller (e.g. the barrel plugin) has no document metadata.
 */
-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)
+function 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
 	};
-	const operationFilterTypes = new Set([
-		"tag",
-		"operationId",
-		"path",
-		"method",
-		"contentType"
-	]);
-	const hasOperationBasedIncludes = include?.some(({ type }) => operationFilterTypes.has(type)) ?? false;
-	const hasSchemaNameIncludes = include?.some(({ type }) => type === "schemaName") ?? false;
-	let allowedSchemaNames;
-	if (hasOperationBasedIncludes && !hasSchemaNameIncludes) allowedSchemaNames = collectUsedSchemaNames(inputNode.operations.filter((op) => resolver.resolveOptions(op, {
-		options: plugin.options,
-		exclude,
-		include,
-		override
-	}) !== null), inputNode.schemas);
-	await walk(inputNode, {
-		depth: "shallow",
-		async schema(node) {
-			const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node;
-			if (allowedSchemaNames !== void 0 && transformedNode.name && !allowedSchemaNames.has(transformedNode.name)) return;
-			const options = resolver.resolveOptions(transformedNode, {
-				options: plugin.options,
-				exclude,
-				include,
-				override
-			});
-			if (options === null) return;
-			const ctx = {
-				...generatorContext,
-				options
-			};
-			for (const gen of generators) {
-				if (!gen.schema) continue;
-				await applyHookResult(await gen.schema(transformedNode, ctx), driver, resolveRenderer(gen));
-			}
-			await driver.hooks.emit("kubb:generate:schema", transformedNode, ctx);
-		},
-		async operation(node) {
-			const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node;
-			const options = resolver.resolveOptions(transformedNode, {
-				options: plugin.options,
-				exclude,
-				include,
-				override
-			});
-			if (options !== null) {
-				collectedOperations.push(transformedNode);
-				const ctx = {
-					...generatorContext,
-					options
-				};
-				for (const gen of generators) {
-					if (!gen.operation) continue;
-					await applyHookResult(await gen.operation(transformedNode, ctx), driver, resolveRenderer(gen));
-				}
-				await driver.hooks.emit("kubb:generate:operation", transformedNode, ctx);
-			}
-		}
-	});
-	if (collectedOperations.length > 0) {
-		const ctx = {
-			...generatorContext,
-			options: plugin.options
-		};
-		for (const gen of generators) {
-			if (!gen.operations) continue;
-			await applyHookResult(await gen.operations(collectedOperations, ctx), driver, resolveRenderer(gen));
+}
+const stringPatternCache = /* @__PURE__ */ new Map();
+function testPattern(value, pattern) {
+	if (typeof pattern === "string") {
+		let regex = stringPatternCache.get(pattern);
+		if (!regex) {
+			regex = new RegExp(pattern);
+			stringPatternCache.set(pattern, regex);
 		}
-		await driver.hooks.emit("kubb:generate:operations", collectedOperations, ctx);
+		return regex.test(value);
 	}
+	return value.match(pattern) !== null;
 }
-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;
+/**
+* Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
+*/
+function matchesOperationPattern(node, type, pattern) {
+	if (type === "tag") return node.tags.some((tag) => testPattern(tag, pattern));
+	if (type === "operationId") return testPattern(node.operationId, pattern);
+	if (type === "path") return node.path !== void 0 && testPattern(node.path, pattern);
+	if (type === "method") return node.method !== void 0 && testPattern(node.method.toLowerCase(), pattern);
+	if (type === "contentType") return node.requestBody?.content?.some((c) => testPattern(c.contentType, pattern)) ?? false;
+	return false;
+}
+/**
+* Checks if a schema matches a pattern for a given filter type (`schemaName`).
+*
+* Returns `null` when the filter type doesn't apply to schemas.
+*/
+function matchesSchemaPattern(node, type, pattern) {
+	if (type === "schemaName") return node.name ? testPattern(node.name, pattern) : false;
+	return null;
+}
+/**
+* Default name resolver used by `defineResolver`.
+*
+* - `camelCase` for `file`, with dotted names split into `/`-joined nested paths.
+* - `PascalCase` for `type`.
+* - `camelCase` for `function` and everything else.
+*/
+function defaultResolver(name, type) {
+	if (type === "file") return toFilePath(name);
+	if (type === "type") return pascalCase(name);
+	return camelCase(name);
+}
+/**
+* Default option resolver. Applies include/exclude filters and merges matching override options.
+*
+* Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+*
+* @example Include/exclude filtering
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { output: 'types' },
+*   exclude: [{ type: 'tag', pattern: 'internal' }],
+* })
+* // → null when node has tag 'internal'
+* ```
+*
+* @example Override merging
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { enumType: 'asConst' },
+*   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+* })
+* // → { enumType: 'enum' } when operationId matches
+* ```
+*/
+const resolveOptionsCache = /* @__PURE__ */ new WeakMap();
+function computeOptions(node, options, exclude, include, override) {
+	if (operationDef.is(node)) {
+		if (exclude.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) return null;
+		if (include && !include.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) return null;
+		const overrideOptions = override.find(({ type, pattern }) => matchesOperationPattern(node, type, pattern))?.options;
+		return {
+			...options,
+			...overrideOptions
+		};
+	}
+	if (schemaDef.is(node)) {
+		if (exclude.some(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)) return null;
+		if (include) {
+			const applicable = include.map(({ type, pattern }) => matchesSchemaPattern(node, type, pattern)).filter((result) => result !== null);
+			if (applicable.length > 0 && !applicable.includes(true)) return null;
+		}
+		const overrideOptions = override.find(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)?.options;
+		return {
+			...options,
+			...overrideOptions
+		};
+	}
+	return options;
+}
+function defaultResolveOptions(node, { options, exclude = [], include, override = [] }) {
+	const optionsKey = options;
+	let byOptions = resolveOptionsCache.get(optionsKey);
+	if (!byOptions) {
+		byOptions = /* @__PURE__ */ new WeakMap();
+		resolveOptionsCache.set(optionsKey, byOptions);
+	}
+	const cached = byOptions.get(node);
+	if (cached !== void 0) return cached.value;
+	const result = computeOptions(node, options, exclude, include, override);
+	byOptions.set(node, { value: result });
+	return result;
+}
+/**
+* Default path resolver used by `defineResolver`.
+*
+* - `mode: 'file'` resolves directly to `output.path` (the full file path, extension included).
+* - `mode: 'directory'` (default) resolves to `output.path/{baseName}`, or into a
+*   subdirectory when `group` and a `tag`/`path` value are provided.
+*
+* A custom `group.name` function overrides the default subdirectory naming.
+* For `tag` groups the default is the camelCased tag.
+* For `path` groups the default is the first path segment after `/`.
+*
+* @example Flat output
+* ```ts
+* defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+* // → '/src/types/petTypes.ts'
+* ```
+*
+* @example Tag-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → '/src/types/pets/petTypes.ts'
+* ```
+*
+* @example Path-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', path: '/pets/list' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+* )
+* // → '/src/types/pets/petTypes.ts'
+* ```
+*
+* @example Single file (`mode: 'file'`)
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts' },
+*   { root: '/src', output: { path: 'types.ts', mode: 'file' } },
+* )
+* // → '/src/types.ts'
+* ```
+*/
+function defaultResolvePath({ baseName, tag, path: groupPath }, { root, output, group }) {
+	if ((output.mode ?? "directory") === "file") return path.resolve(root, output.path);
+	const result = (() => {
+		if (group && (groupPath || tag)) {
+			const groupValue = group.type === "path" ? groupPath : tag;
+			const defaultName = group.type === "tag" ? ({ group: groupName }) => camelCase(groupName) : ({ group: groupName }) => {
+				const segment = groupName.split("/").filter((part) => part !== "" && part !== "." && part !== "..")[0];
+				return segment ? camelCase(segment) : "";
+			};
+			const groupName = (group.name ?? defaultName)({ group: groupValue });
+			return path.resolve(root, output.path, groupName, baseName);
+		}
+		return path.resolve(root, output.path, baseName);
+	})();
+	const outputDir = path.resolve(root, output.path);
+	const outputDirWithSep = outputDir.endsWith(path.sep) ? outputDir : `${outputDir}${path.sep}`;
+	if (result !== outputDir && !result.startsWith(outputDirWithSep)) throw new Diagnostics.Error({
+		code: Diagnostics.code.pathTraversal,
+		severity: "error",
+		message: `Resolved path "${result}" is outside the output directory "${outputDir}".`,
+		help: "This can stem from a path traversal in the OpenAPI specification or a misconfigured `group.name` function. Keep generated paths within the output directory.",
+		location: { kind: "config" }
+	});
+	return result;
+}
+/**
+* Default file resolver used by `defineResolver`.
+*
+* Resolves a `FileNode` by combining name resolution (`resolver.default`) with
+* path resolution (`resolver.resolvePath`). The resolved file always has empty
+* `sources`, `imports`, and `exports` arrays, which consumers populate separately.
+*
+* In `mode: 'file'` the name is omitted and the file sits directly at the output path.
+*
+* @example Resolve a schema file
+* ```ts
+* const file = defaultResolveFile.call(
+*   resolver,
+*   { name: 'pet', extname: '.ts' },
+*   { root: '/src', output: { path: 'types' } },
+* )
+* // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+* ```
+*
+* @example Resolve an operation file with tag grouping
+* ```ts
+* const file = defaultResolveFile.call(
+*   resolver,
+*   { name: 'listPets', extname: '.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → { baseName: 'listPets.ts', path: '/src/types/pets/listPets.ts', ... }
+* ```
+*/
+function defaultResolveFile({ name, extname, tag, path: groupPath }, context) {
+	const baseName = `${(context.output.mode ?? "directory") === "file" ? "" : this.default(name, "file")}${extname}`;
+	const filePath = this.resolvePath({
+		baseName,
+		tag,
+		path: groupPath
+	}, context);
+	return factory.createFile({
+		path: filePath,
+		baseName: path.basename(filePath),
+		meta: { pluginName: this.pluginName },
+		sources: [],
+		imports: [],
+		exports: []
+	});
+}
+/**
+* Generates the default "Generated by Kubb" banner from config and optional node metadata.
+*/
+function buildDefaultBanner({ title, description, version, config }) {
+	try {
+		const source = (() => {
+			if (Array.isArray(config.input)) {
+				const first = config.input[0];
+				if (first && "path" in first) return path.basename(first.path);
+				return "";
+			}
+			if (config.input && "path" in config.input) return path.basename(config.input.path);
+			if (config.input && "data" in config.input) return "text content";
+			return "";
+		})();
+		let banner = "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n";
+		if (config.output.defaultBanner === "simple") {
+			banner += "*/\n";
+			return banner;
+		}
+		if (source) banner += `* Source: ${source}\n`;
+		if (title) banner += `* Title: ${title}\n`;
+		if (description) {
+			const formattedDescription = description.replace(/\n/gm, "\n* ");
+			banner += `* Description: ${formattedDescription}\n`;
+		}
+		if (version) banner += `* OpenAPI spec version: ${version}\n`;
+		banner += "*/\n";
+		return banner;
+	} catch (_error) {
+		return "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/";
+	}
+}
+/**
+* Default banner resolver. Returns the banner string for a generated file.
+*
+* A user-supplied `output.banner` overrides the default Kubb "Generated by Kubb" notice.
+* When no `output.banner` is set, the Kubb notice is used (including `title` and `version`
+* from the document metadata when `meta` is provided).
+*
+* - When `output.banner` is a function, calls it with the file's `BannerMeta` and returns the result.
+* - When `output.banner` is a string, returns it directly.
+* - When `config.output.defaultBanner` is `false`, returns `undefined`.
+* - Otherwise returns the Kubb "Generated by Kubb" notice.
+*
+* @example String banner overrides default
+* ```ts
+* defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+* // → '// my banner'
+* ```
+*
+* @example Function banner with metadata
+* ```ts
+* defaultResolveBanner(meta, { output: { banner: (m) => `// v${m.version}` }, config })
+* // → '// v3.0.0'
+* ```
+*
+* @example Function banner skips re-export files
+* ```ts
+* defaultResolveBanner(meta, { output: { banner: (m) => (m.isBarrel ? '' : "'use server'") }, config, file: { path, baseName, isBarrel: true } })
+* // → ''
+* ```
+*
+* @example No user banner, Kubb notice with OAS metadata
+* ```ts
+* defaultResolveBanner(meta, { config })
+* // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
+* ```
+*
+* @example Disabled default banner
+* ```ts
+* defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+* // → null
+* ```
+*/
+function defaultResolveBanner(meta, { output, config, file }) {
+	if (typeof output?.banner === "function") return output.banner(buildBannerMeta({
+		meta,
+		file
+	}));
+	if (typeof output?.banner === "string") return output.banner;
+	if (config.output.defaultBanner === false) return null;
+	return buildDefaultBanner({
+		title: meta?.title,
+		version: meta?.version,
+		config
+	});
+}
+/**
+* Default footer resolver. Returns the footer string for a generated file.
+*
+* - When `output.footer` is a function, calls it with the file's `BannerMeta` and returns the result.
+* - When `output.footer` is a string, returns it directly.
+* - Otherwise returns `undefined`.
+*
+* @example String footer
+* ```ts
+* defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+* // → '// end of file'
+* ```
+*
+* @example Function footer with metadata
+* ```ts
+* defaultResolveFooter(meta, { output: { footer: (m) => `// ${m.title}` }, config })
+* // → '// Pet Store'
+* ```
+*/
+function defaultResolveFooter(meta, { output, file }) {
+	if (typeof output?.footer === "function") return output.footer(buildBannerMeta({
+		meta,
+		file
+	}));
+	if (typeof output?.footer === "string") return output.footer;
+	return null;
+}
+/**
+* Defines a plugin resolver. The resolver is the object that decides what
+* every generated symbol and file path is called. Built-in defaults handle
+* name casing, include/exclude/override filtering, output path computation,
+* and file construction. Supply your own to override any of them:
+*
+* - `default` sets the name casing strategy (camelCase or PascalCase).
+* - `resolveOptions` does include/exclude/override filtering.
+* - `resolvePath` computes the output path.
+* - `resolveFile` builds the full `FileNode`.
+* - `resolveBanner` and `resolveFooter` produce the top and bottom of file text.
+*
+* Methods in the returned object can call sibling resolver methods via `this`.
+* A custom rule can delegate to a default, for example `this.default(name, 'type')`.
+*
+* @example Basic resolver with naming helpers
+* ```ts
+* export const resolverTs = defineResolver<PluginTs>(() => ({
+*   name: 'default',
+*   resolveName(name) {
+*     return this.default(name, 'function')
+*   },
+*   resolveTypeName(name) {
+*     return this.default(name, 'type')
+*   },
+* }))
+* ```
+*
+* @example Custom output path
+* ```ts
+* import path from 'node:path'
+*
+* export const resolverTs = defineResolver<PluginTs>(() => ({
+*   name: 'custom',
+*   resolvePath({ baseName }, { root, output }) {
+*     return path.resolve(root, output.path, 'generated', baseName)
+*   },
+* }))
+* ```
+*/
+function defineResolver(build) {
+	let resolver;
+	resolver = {
+		default: defaultResolver,
+		resolveOptions: defaultResolveOptions,
+		resolvePath: defaultResolvePath,
+		resolveFile: (params, context) => defaultResolveFile.call(resolver, params, context),
+		resolveBanner: defaultResolveBanner,
+		resolveFooter: defaultResolveFooter,
+		...build()
+	};
+	return resolver;
+}
+//#endregion
+//#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();
+	/**
+	* Number of plugins with at least one registered macro.
+	*/
+	get size() {
+		return this.#macros.size;
+	}
+	/**
+	* Appends `macro` to the plugin's list, after any macros already registered.
+	*/
+	add(pluginName, macro) {
+		const list = this.#macros.get(pluginName);
+		if (list) list.push(macro);
+		else this.#macros.set(pluginName, [macro]);
+		this.#invalidate(pluginName);
+	}
+	/**
+	* Replaces the plugin's macro list with `macros`.
+	*/
+	set(pluginName, macros) {
+		this.#macros.set(pluginName, [...macros]);
+		this.#invalidate(pluginName);
+	}
+	/**
+	* Looks up the composed visitor for `pluginName`, or `undefined` when the plugin has no macros.
+	*/
+	get(pluginName) {
+		return this.#visitorFor(pluginName);
+	}
+	/**
+	* Runs the plugin's macros on `node`. Returns the original node reference when the plugin has no
+	* macros, so callers can compare by identity to detect a no-op.
+	*/
+	applyTo(pluginName, node) {
+		const visitor = this.#visitorFor(pluginName);
+		if (!visitor) return node;
+		let memo = this.#memo.get(pluginName);
+		if (!memo) {
+			memo = /* @__PURE__ */ new WeakMap();
+			this.#memo.set(pluginName, memo);
+		}
+		const cached = memo.get(node);
+		if (cached) return cached;
+		const result = transform(node, visitor);
+		memo.set(node, result);
+		return result;
+	}
+	/**
+	* Clears every registration. Called from the driver's `dispose()` so macros do not leak across
+	* builds.
+	*/
+	dispose() {
+		this.#macros.clear();
+		this.#composed.clear();
+		this.#memo.clear();
+	}
+	#invalidate(pluginName) {
+		this.#composed.delete(pluginName);
+		this.#memo.delete(pluginName);
+	}
+	#visitorFor(pluginName) {
+		const macros = this.#macros.get(pluginName);
+		if (!macros || macros.length === 0) return void 0;
+		let composed = this.#composed.get(pluginName);
+		if (!composed) {
+			composed = composeMacros(macros);
+			this.#composed.set(pluginName, composed);
+		}
+		return composed;
+	}
+};
+//#endregion
+//#region src/KubbDriver.ts
+function enforceOrder(enforce) {
+	return enforce === "pre" ? -1 : enforce === "post" ? 1 : 0;
+}
+var KubbDriver = class {
+	config;
+	options;
+	/**
+	* The streaming `InputNode<true>` produced by the adapter. Set after adapter setup.
+	* Parse-only adapters are wrapped automatically.
+	*/
+	inputNode = null;
+	adapter = null;
+	/**
+	* Raw adapter source so `adapter.parse()` / `adapter.stream()` can run lazily.
+	* Intentionally outlives the build, cleared by `dispose()`.
+	*/
+	#adapterSource = null;
+	/**
+	* Central file store for all generated files.
+	* Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
+	* add files. This property gives direct read/write access when needed.
+	*/
+	fileManager = new FileManager();
+	plugins = /* @__PURE__ */ new Map();
+	/**
+	* Tracks which plugins have generators registered via `addGenerator()` (event-based path).
+	* Used by the build loop to decide whether to emit generator events for a given plugin.
+	*/
+	#eventGeneratorPlugins = /* @__PURE__ */ new Set();
+	#resolvers = /* @__PURE__ */ new Map();
+	#defaultResolvers = /* @__PURE__ */ new Map();
+	/**
+	* Tracks every listener the driver added (plugin, generator) so `dispose()` can remove them
+	* in one pass. External `hooks.on(...)` listeners are not tracked.
+	*/
+	#listeners = [];
+	/**
+	* 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;
+	}
+	/**
+	* Attaches a listener to the shared emitter and tracks it so `dispose()` can remove it later.
+	* Listeners attached directly via `hooks.on(...)` are not tracked and survive disposal.
+	*/
+	#trackListener(event, handler) {
+		this.hooks.on(event, handler);
+		this.#listeners.push([event, handler]);
+	}
+	async setup() {
+		const normalized = this.config.plugins.map((rawPlugin) => this.#normalizePlugin(rawPlugin));
+		const dependenciesByName = new Map(normalized.map((plugin) => [plugin.name, new Set(plugin.dependencies ?? [])]));
+		normalized.sort((a, b) => {
+			if (dependenciesByName.get(b.name)?.has(a.name)) return -1;
+			if (dependenciesByName.get(a.name)?.has(b.name)) return 1;
+			return enforceOrder(a.enforce) - enforceOrder(b.enforce);
+		});
+		for (const plugin of normalized) {
+			if (plugin.apply) plugin.apply(this.config);
+			this.#registerPlugin(plugin);
+			this.plugins.set(plugin.name, plugin);
+		}
+		if (this.config.adapter) this.#adapterSource = inputToAdapterSource(this.config);
+	}
+	get hooks() {
+		return this.options.hooks;
+	}
+	/**
+	* Creates an `NormalizedPlugin` from a hook-style plugin and registers
+	* its lifecycle handlers on the `AsyncEventEmitter`.
+	*/
+	#normalizePlugin(plugin) {
+		const normalized = {
+			name: plugin.name,
+			dependencies: plugin.dependencies,
+			enforce: plugin.enforce,
+			hooks: plugin.hooks,
+			options: plugin.options ?? {
+				output: {
+					path: ".",
+					mode: "directory"
+				},
+				exclude: [],
+				override: []
+			}
+		};
+		if ("apply" in plugin && typeof plugin.apply === "function") normalized.apply = plugin.apply;
+		return normalized;
+	}
+	/**
+	* Parses the adapter source into `this.inputNode`. Idempotent, so repeated calls from
+	* `run` do not re-parse. Adapters with `stream()` are used directly.
+	* Adapters with only `parse()` are wrapped via `factory.createInput({ stream: true })` so the dispatch loop
+	* stays stream-only.
+	*/
+	async #parseInput() {
+		if (this.inputNode || !this.adapter || !this.#adapterSource) return;
+		const adapter = this.adapter;
+		const source = this.#adapterSource;
+		if (adapter.stream) {
+			this.inputNode = await adapter.stream(source);
+			return;
+		}
+		const parsed = await adapter.parse(source);
+		this.inputNode = factory.createInput({
+			stream: true,
+			schemas: arrayToAsyncIterable(parsed.schemas),
+			operations: arrayToAsyncIterable(parsed.operations),
+			meta: parsed.meta
+		});
+	}
+	/**
+	* Registers a hook-style plugin's lifecycle handlers on the shared `AsyncEventEmitter`.
+	*
+	* The `kubb:plugin:setup` listener wraps the global context in a plugin-specific one so
+	* `addGenerator`, `setResolver`, and `setMacros` target the right `normalizedPlugin`.
+	* Every other `KubbHooks` event registers as a pass-through listener that external tooling
+	* can observe via `hooks.on(...)`.
+	*
+	* @internal
+	*/
+	#registerPlugin(plugin) {
+		const { hooks } = plugin;
+		if (!hooks) return;
+		if (hooks["kubb:plugin:setup"]) {
+			const setupHandler = (globalCtx) => {
+				const pluginCtx = {
+					...globalCtx,
+					options: plugin.options ?? {},
+					addGenerator: (gen) => {
+						this.registerGenerator(plugin.name, gen);
 					},
-					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;
+					setResolver: (resolver) => {
+						this.setPluginResolver(plugin.name, resolver);
+					},
+					addMacro: (macro) => {
+						this.#transforms.add(plugin.name, macro);
 					},
-					upsertFile: (...files) => driver.fileManager.upsert(...files)
+					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(factory.createFile(userFileNode));
+					}
+				};
+				return hooks["kubb:plugin:setup"](pluginCtx);
+			};
+			this.#trackListener("kubb:plugin:setup", setupHandler);
+		}
+		for (const event of Object.keys(hooks)) {
+			if (event === "kubb:plugin:setup") continue;
+			const handler = hooks[event];
+			if (!handler) continue;
+			this.#trackListener(event, handler);
+		}
+	}
+	/**
+	* Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
+	* can configure generators, resolvers, macros and renderers before `buildStart` runs.
+	*
+	* Call this once from `safeBuild` before the plugin execution loop begins.
+	*/
+	async emitSetupHooks() {
+		const noop = () => {};
+		await this.hooks.emit("kubb:plugin:setup", {
+			config: this.config,
+			options: {},
+			addGenerator: noop,
+			setResolver: noop,
+			addMacro: noop,
+			setMacros: noop,
+			setOptions: noop,
+			injectFile: noop,
+			updateConfig: noop
+		});
+	}
+	/**
+	* Registers a generator for the given plugin on the shared event 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) {
+		if (generator.schema) {
+			const schemaHandler = async (node, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				const result = await generator.schema(node, ctx);
+				await this.dispatch({
+					result,
+					renderer: generator.renderer
 				});
-				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"
-					]
+			};
+			this.#trackListener("kubb:generate:schema", schemaHandler);
+		}
+		if (generator.operation) {
+			const operationHandler = async (node, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				const result = await generator.operation(node, ctx);
+				await this.dispatch({
+					result,
+					renderer: generator.renderer
 				});
-				failedPlugins.add({
-					plugin,
-					error
+			};
+			this.#trackListener("kubb:generate:operation", operationHandler);
+		}
+		if (generator.operations) {
+			const operationsHandler = async (nodes, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				const result = await generator.operations(nodes, ctx);
+				await this.dispatch({
+					result,
+					renderer: generator.renderer
 				});
-			}
+			};
+			this.#trackListener("kubb:generate:operations", operationsHandler);
 		}
-		await hooks.emit("kubb:plugins:end", {
-			config,
-			get files() {
-				return driver.fileManager.files;
-			},
-			upsertFile: (...files) => driver.fileManager.upsert(...files)
-		});
-		const files = driver.fileManager.files;
+		this.#eventGeneratorPlugins.add(pluginName);
+	}
+	/**
+	* Returns `true` when at least one generator was registered for the given plugin
+	* via `addGenerator()` in `kubb:plugin:setup` (event-based path).
+	*
+	* Used by the build loop to decide whether to walk the AST and emit generator events
+	* for a plugin that has no static `plugin.generators`.
+	*/
+	hasEventGenerators(pluginName) {
+		return this.#eventGeneratorPlugins.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({ storage }) {
+		const { hooks, config } = this;
+		const diagnostics = [];
 		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, {
+		for (const parser of config.parsers) if (parser.extNames) for (const ext of parser.extNames) parsersMap.set(ext, parser);
+		const processor = new FileProcessor({
 			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);
+			storage,
+			extension: config.output.extension
+		});
+		processor.hooks.on("start", async (files) => {
+			await hooks.emit("kubb:files:processing:start", { files });
+		});
+		const updateBuffer = [];
+		processor.hooks.on("update", (item) => {
+			updateBuffer.push(item);
+		});
+		processor.hooks.on("end", async (files) => {
+			await hooks.emit("kubb:files:processing:update", { files: updateBuffer.map((item) => ({
+				...item,
+				config
+			})) });
+			updateBuffer.length = 0;
+			await hooks.emit("kubb:files:processing:end", { files });
+		});
+		const onFileUpsert = (file) => {
+			processor.enqueue(file);
+		};
+		this.fileManager.hooks.on("upsert", onFileUpsert);
+		return Diagnostics.scope((diagnostic) => diagnostics.push(diagnostic), async () => {
+			try {
+				const outputRoot = resolve(config.root, config.output.path);
+				await this.#parseInput();
+				await this.emitSetupHooks();
+				if (this.adapter && this.inputNode) await hooks.emit("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.emit("kubb:plugin:start", { plugin });
+					} catch (caughtError) {
+						const error = 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.hasEventGenerators(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, () => processor.flush()));
+				await processor.drain();
+				await hooks.emit("kubb:plugins:end", Object.assign({ config }, this.#filesPayload()));
+				await processor.drain();
+				await hooks.emit("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 {
+				this.fileManager.hooks.off("upsert", onFileUpsert);
+			}
+		});
+	}
+	#filesPayload() {
+		const driver = this;
+		return {
+			get files() {
+				return driver.fileManager.files;
 			},
-			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`]
+			upsertFile: (...files) => driver.fileManager.upsert(...files)
+		};
+	}
+	#emitPluginEnd({ plugin, duration, success, error }) {
+		return this.hooks.emit("kubb:plugin:end", Object.assign({
+			plugin,
+			duration,
+			success,
+			...error ? { error } : {},
+			config: this.config
+		}, this.#filesPayload()));
+	}
+	/**
+	* Streams 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
+	* because the two passes share `flushPending` and the FileProcessor's event emitter.
+	* A failing plugin contributes an error diagnostic so the rest of the build continues.
+	* Every plugin also contributes a `timing` diagnostic.
+	*
+	* Plugins run sequentially so `kubb:plugin:end` fires as each plugin completes, instead
+	* of all at once after every plugin has marched through the parallel batches together.
+	* That ordering is what drives the CLI's `Plugins N/M` counter. Without it the bar would
+	* sit at the initial value until the very end of the run.
+	*
+	* When `entries` is empty or `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, flushPending) {
+		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 states = entries.map(({ plugin, context, hrStart }) => {
+			const { exclude, include, override } = plugin.options;
+			const hasExclude = Array.isArray(exclude) && exclude.length > 0;
+			const hasInclude = Array.isArray(include) && include.length > 0;
+			const hasOverride = Array.isArray(override) && override.length > 0;
+			return {
+				plugin,
+				generatorContext: {
+					...context,
+					resolver: this.getResolver(plugin.name)
+				},
+				generators: plugin.generators ?? [],
+				hrStart,
+				failed: false,
+				error: null,
+				optionsAreStatic: !hasExclude && !hasInclude && !hasOverride,
+				allowedSchemaNames: null
+			};
 		});
-		await hooks.emit("kubb:build:end", {
-			files,
-			config,
-			outputDir: resolve(config.root, config.output.path)
+		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 schemasBuffer = await Array.fromAsync(schemas);
+		const operationsBuffer = await Array.fromAsync(operations);
+		const pruningStates = states.filter(({ plugin }) => {
+			const { include } = plugin.options;
+			return (include?.some(({ type }) => OPERATION_FILTER_TYPES.has(type)) ?? false) && !(include?.some(({ type }) => type === "schemaName") ?? false);
 		});
-		return {
-			failedPlugins,
-			files,
-			driver,
-			pluginTimings,
-			sources
+		if (pruningStates.length > 0) {
+			const includedOpsByState = new Map(pruningStates.map((state) => [state, []]));
+			for (const operation of operationsBuffer) for (const state of pruningStates) {
+				const { exclude, include, override } = state.plugin.options;
+				if (state.generatorContext.resolver.resolveOptions(operation, {
+					options: state.plugin.options,
+					exclude,
+					include,
+					override
+				}) !== null) includedOpsByState.get(state)?.push(operation);
+			}
+			for (const state of pruningStates) {
+				state.allowedSchemaNames = collectUsedSchemaNames(includedOpsByState.get(state) ?? [], schemasBuffer);
+				includedOpsByState.delete(state);
+			}
+		}
+		const resolveForPlugin = (state, node) => {
+			const { plugin, generatorContext } = state;
+			const transformedNode = transforms.applyTo(plugin.name, node);
+			if (state.optionsAreStatic) return {
+				transformedNode,
+				options: plugin.options
+			};
+			const { exclude, include, override } = plugin.options;
+			const options = generatorContext.resolver.resolveOptions(transformedNode, {
+				options: plugin.options,
+				exclude,
+				include,
+				override
+			});
+			if (options === null) return null;
+			return {
+				transformedNode,
+				options
+			};
+		};
+		const dispatchNode = async (state, node, dispatch) => {
+			if (state.failed) return;
+			try {
+				const resolved = resolveForPlugin(state, node);
+				if (!resolved) return;
+				const { transformedNode, options } = resolved;
+				if (dispatch.checkAllowedNames && state.allowedSchemaNames !== null && "name" in transformedNode && transformedNode.name && !state.allowedSchemaNames.has(transformedNode.name)) return;
+				const ctx = {
+					...state.generatorContext,
+					options
+				};
+				for (const gen of state.generators) {
+					const run = gen[dispatch.method];
+					if (!run) continue;
+					const raw = run(transformedNode, ctx);
+					const result = isPromise(raw) ? await raw : raw;
+					const applied = this.dispatch({
+						result,
+						renderer: gen.renderer
+					});
+					if (isPromise(applied)) await applied;
+				}
+				if (dispatch.emit) await dispatch.emit(transformedNode, ctx);
+			} catch (caughtError) {
+				state.failed = true;
+				state.error = caughtError;
+			}
+		};
+		const schemaDispatch = {
+			method: "schema",
+			checkAllowedNames: true,
+			emit: emitsSchemaHook ? (node, ctx) => this.hooks.emit("kubb:generate:schema", node, ctx) : null
+		};
+		const operationDispatch = {
+			method: "operation",
+			checkAllowedNames: false,
+			emit: emitsOperationHook ? (node, ctx) => this.hooks.emit("kubb:generate:operation", node, ctx) : null
+		};
+		for (const state of states) {
+			const needsCollectedOperations = emitsOperationsHook || state.generators.some((gen) => !!gen.operations);
+			const collectedOperations = needsCollectedOperations ? [] : void 0;
+			await forBatches(schemasBuffer, (nodes) => Promise.all(nodes.map((node) => dispatchNode(state, node, schemaDispatch))), {
+				concurrency: 8,
+				flush: flushPending
+			});
+			await forBatches(operationsBuffer, (nodes) => {
+				if (needsCollectedOperations) collectedOperations?.push(...nodes);
+				return Promise.all(nodes.map((node) => dispatchNode(state, node, operationDispatch)));
+			}, {
+				concurrency: 8,
+				flush: flushPending
+			});
+			if (!state.failed && needsCollectedOperations) try {
+				const { plugin, generatorContext, generators } = state;
+				const ctx = {
+					...generatorContext,
+					options: plugin.options
+				};
+				const pluginOperations = (collectedOperations ?? []).reduce((acc, node) => {
+					const resolved = resolveForPlugin(state, node);
+					if (resolved) acc.push(resolved.transformedNode);
+					return acc;
+				}, []);
+				for (const gen of generators) {
+					if (!gen.operations) continue;
+					const result = await gen.operations(pluginOperations, ctx);
+					await this.dispatch({
+						result,
+						renderer: gen.renderer
+					});
+				}
+				await this.hooks.emit("kubb:generate:operations", pluginOperations, ctx);
+			} catch (caughtError) {
+				state.failed = true;
+				state.error = caughtError;
+			}
+			const duration = getElapsedMs(state.hrStart);
+			await this.#emitPluginEnd({
+				plugin: state.plugin,
+				duration,
+				success: !state.failed,
+				error: state.failed && state.error ? state.error : void 0
+			});
+			if (state.failed && state.error) diagnostics.push({
+				...Diagnostics.from(state.error),
+				plugin: state.plugin.name
+			});
+			diagnostics.push(Diagnostics.performance({
+				plugin: state.plugin.name,
+				duration
+			}));
+		}
+		return diagnostics;
+	}
+	/**
+	* Stores whatever a generator method or `kubb:generate:*` hook returned.
+	*
+	* - An `Array<FileNode>` goes straight into `fileManager` via `upsert`.
+	* - A renderer element runs through `renderer` (the renderer factory, e.g. JSX) and the
+	*   produced files go to `fileManager.upsert`.
+	* - A falsy result is treated as a no-op. The generator wrote files itself via
+	*   `ctx.upsertFile`.
+	*
+	* Pass `renderer` when the result may be a renderer element. Generators that only return
+	* `Array<FileNode>` do not need one.
+	*/
+	async dispatch({ result, renderer }) {
+		try {
+			var _usingCtx$2 = _usingCtx();
+			if (!result) return;
+			if (Array.isArray(result)) {
+				this.fileManager.upsert(...result);
+				return;
+			}
+			if (!renderer) return;
+			const instance = _usingCtx$2.u(renderer());
+			if (instance.stream) {
+				for (const file of instance.stream(result)) this.fileManager.upsert(file);
+				return;
+			}
+			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 [event, handler] of this.#listeners) this.hooks.off(event, handler);
+		this.#listeners.length = 0;
+		this.#eventGeneratorPlugins.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) => defineResolver(() => ({
+		name: "default",
+		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 merged = {
+			...this.#getDefaultResolver(pluginName),
+			...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.plugins.get(pluginName)?.resolver ?? this.#getDefaultResolver(pluginName);
+	}
+	getContext(plugin) {
+		const driver = this;
+		const report = (diagnostic) => {
+			Diagnostics.report({
+				...diagnostic,
+				plugin: plugin.name
+			});
 		};
-	} catch (error) {
 		return {
-			failedPlugins,
-			files: [],
+			config: driver.config,
+			get root() {
+				return resolve(driver.config.root, driver.config.output.path);
+			},
+			hooks: driver.hooks,
+			plugin,
+			getPlugin: driver.getPlugin.bind(driver),
+			requirePlugin: ((name) => driver.requirePlugin(name, { requiredBy: plugin.name })),
+			getResolver: driver.getResolver.bind(driver),
 			driver,
-			pluginTimings,
-			error,
-			sources
+			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
+				});
+			}
 		};
-	} 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 });
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName);
 	}
-	return {
-		failedPlugins,
-		files,
-		driver,
-		pluginTimings,
-		error: void 0,
-		sources
-	};
-}
+	requirePlugin(pluginName, context) {
+		const plugin = this.plugins.get(pluginName);
+		if (!plugin) {
+			const requiredBy = context?.requiredBy;
+			throw new Diagnostics.Error({
+				code: Diagnostics.code.pluginNotFound,
+				severity: "error",
+				message: requiredBy ? `Plugin "${pluginName}" is required by "${requiredBy}" but not found. Make sure it is included in your Kubb config.` : `Plugin "${pluginName}" is required but not found. Make sure it is included in your Kubb config.`,
+				help: requiredBy ? `Add "${pluginName}" to the \`plugins\` array in kubb.config.ts (required by "${requiredBy}"), or remove the dependency on it.` : `Add "${pluginName}" to the \`plugins\` array in kubb.config.ts, or remove the dependency on it.`,
+				location: { kind: "config" }
+			});
+		}
+		return plugin;
+	}
+};
 function inputToAdapterSource(config) {
 	const input = config.input;
-	if (!input) throw new Error("[kubb] input is required when using an adapter. Provide input.path or input.data in your config.");
-	if (Array.isArray(input)) return {
-		type: "paths",
-		paths: input.map((i) => new URLPath(i.path).isURL ? i.path : resolve(config.root, i.path))
-	};
+	if (!input) throw new Diagnostics.Error({
+		code: Diagnostics.code.inputRequired,
+		severity: "error",
+		message: "An adapter is configured without an input.",
+		help: "Provide `input.path` (a file or URL) or `input.data` (an inline spec) in your Kubb config.",
+		location: { kind: "config" }
+	});
 	if ("data" in input) return {
 		type: "data",
 		data: input.data
 	};
-	if (new URLPath(input.path).isURL) return {
+	if (Url.canParse(input.path)) return {
 		type: "path",
 		path: input.path
 	};
@@ -1212,261 +2326,593 @@ function inputToAdapterSource(config) {
 		path: resolve(config.root, input.path)
 	};
 }
+//#endregion
+//#region src/storages/fsStorage.ts
 /**
-* Creates a Kubb instance bound to a single config entry.
+* Built-in filesystem storage driver.
+*
+* This is the default storage when no `storage` option is configured in the root config.
+* 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.
 *
-* 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()`.
+* 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
 *
 * @example
 * ```ts
-* const kubb = createKubb(userConfig)
+* import { fsStorage } from '@kubb/core'
+* import { defineConfig } from 'kubb'
 *
-* kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => {
-*   console.log(`${plugin.name} completed in ${duration}ms`)
+* export default defineConfig({
+*   input:  { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   storage: fsStorage(),
 * })
-*
-* const { files, failedPlugins } = await kubb.safeBuild()
 * ```
 */
-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();
+const fsStorage = createStorage(() => ({
+	name: "fs",
+	async hasItem(key) {
+		try {
+			await access(resolve(key));
+			return true;
+		} catch (_error) {
+			return false;
+		}
+	},
+	async getItem(key) {
+		try {
+			return await readFile(resolve(key), "utf8");
+		} catch (_error) {
+			return null;
+		}
+	},
+	async setItem(key, value) {
+		await write(resolve(key), value, { sanity: false });
+	},
+	async removeItem(key) {
+		await rm(resolve(key), { force: true });
+	},
+	async getKeys(base) {
+		const resolvedBase = resolve(base ?? process.cwd());
+		if (runtime.isBun) {
+			const bunGlob = new Bun.Glob("**/*");
+			return Array.fromAsync(bunGlob.scan({
+				cwd: resolvedBase,
+				onlyFiles: true,
+				dot: true
+			}));
+		}
+		const keys = [];
+		try {
+			for await (const entry of glob("**/*", {
+				cwd: resolvedBase,
+				withFileTypes: true
+			})) if (entry.isFile()) keys.push(toPosixPath(relative(resolvedBase, join(entry.parentPath, entry.name))));
+		} catch (_error) {}
+		return keys;
+	},
+	async clear(base) {
+		if (!base) return;
+		await clean(resolve(base));
+	}
+}));
+//#endregion
+//#region src/createKubb.ts
+/**
+* Builds a `Storage` view scoped to the file paths produced by the current build.
+* Reads delegate to the underlying `storage` so source bytes stay where they were
+* written. Writes register the key so subsequent reads and `getKeys` are scoped
+* to this build's output.
+*/
+function createSourcesView(storage) {
+	const paths = /* @__PURE__ */ new Set();
+	return createStorage(() => ({
+		name: `${storage.name}:sources`,
+		async hasItem(key) {
+			return paths.has(key) && await storage.hasItem(key);
 		},
-		get driver() {
-			return setupResult?.driver;
+		async getItem(key) {
+			return paths.has(key) ? storage.getItem(key) : null;
 		},
-		get config() {
-			return setupResult?.config;
+		async setItem(key, value) {
+			paths.add(key);
+			await storage.setItem(key, value);
 		},
-		async setup() {
-			setupResult = await setup(userConfig, { hooks });
+		async removeItem(key) {
+			paths.delete(key);
+			await storage.removeItem(key);
 		},
-		async build() {
-			if (!setupResult) await instance.setup();
-			return build(setupResult);
+		async getKeys(base) {
+			if (!base) return [...paths];
+			const result = [];
+			for (const key of paths) if (key.startsWith(base)) result.push(key);
+			return result;
 		},
-		async safeBuild() {
-			if (!setupResult) await instance.setup();
-			return safeBuild(setupResult);
+		async clear() {
+			paths.clear();
+			await storage.clear();
 		}
+	}))();
+}
+function resolveConfig(userConfig) {
+	return {
+		...userConfig,
+		root: userConfig.root || process.cwd(),
+		parsers: userConfig.parsers ?? [],
+		output: {
+			format: false,
+			lint: false,
+			extension: { ".ts": ".ts" },
+			defaultBanner: "simple",
+			...userConfig.output
+		},
+		storage: userConfig.storage ?? fsStorage(),
+		reporters: userConfig.reporters ?? [],
+		plugins: userConfig.plugins ?? []
 	};
-	return instance;
 }
-//#endregion
-//#region src/createRenderer.ts
 /**
-* Creates a renderer factory for use in generator definitions.
+* 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, serializable config object (the shape `defineConfig`
+* produces), not a fluent builder. Config stays plain data so it can be cache
+* fingerprinted and validated against the shipped JSON schema.
 *
-* 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.
+* Attach event listeners to `.hooks` before calling `setup()` or `build()`.
 *
 * @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) },
-*   }
-* })
+* const kubb = createKubb(userConfig)
+* kubb.hooks.on('kubb:plugin:end', ({ plugin, duration }) => console.log(plugin.name, duration))
+* const { files, diagnostics } = await kubb.safeBuild()
+* ```
+*/
+var Kubb = class {
+	hooks;
+	config;
+	#driver = null;
+	#storage = null;
+	constructor(userConfig, options = {}) {
+		this.config = resolveConfig(userConfig);
+		this.hooks = options.hooks ?? new AsyncEventEmitter();
+	}
+	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 });
+		const storage = createSourcesView(config.storage);
+		this.hooks.setMaxListeners(Math.max(10, config.plugins.length * 4));
+		if (config.output.clean) await config.storage.clear(resolve(config.root, config.output.path));
+		await driver.setup();
+		this.#driver = driver;
+		this.#storage = 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 BuildError(`Build failed with ${errors.length} ${errors.length === 1 ? "error" : "errors"}`, { errors });
+		}
+		return out;
+	}
+	/**
+	* Runs the full pipeline and captures errors in `BuildOutput` instead of throwing.
+	* Automatically calls `setup()` if needed. This is the canonical call: it never throws on
+	* plugin errors, so callers stay in control of how failures surface.
+	*/
+	async safeBuild() {
+		try {
+			var _usingCtx$1 = _usingCtx();
+			if (!this.#driver) await this.setup();
+			const cleanup = _usingCtx$1.u(this);
+			const driver = cleanup.driver;
+			const storage = cleanup.storage;
+			const { diagnostics } = await driver.run({ storage });
+			return {
+				diagnostics,
+				files: driver.fileManager.files,
+				driver,
+				storage
+			};
+		} catch (_) {
+			_usingCtx$1.e = _;
+		} finally {
+			_usingCtx$1.d();
+		}
+	}
+	dispose() {
+		this.#driver?.dispose();
+	}
+	[Symbol.dispose]() {
+		this.dispose();
+	}
+};
+/**
+* Constructs a {@link Kubb} build orchestrator from a user config. Equivalent
+* to `new Kubb(userConfig, options)` and the canonical public entry point.
 *
-* // 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> },
+* @example
+* ```ts
+* import { createKubb } from '@kubb/core'
+* import { adapterOas } from '@kubb/adapter-oas'
+* import { pluginTs } from '@kubb/plugin-ts'
+*
+* const kubb = createKubb({
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   adapter: adapterOas(),
+*   plugins: [pluginTs()],
 * })
+*
+* await kubb.build()
 * ```
 */
-function createRenderer(factory) {
-	return factory;
+function createKubb(userConfig, options = {}) {
+	return new Kubb(userConfig, options);
 }
 //#endregion
-//#region src/defineGenerator.ts
+//#region src/createReporter.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.
+* Numeric log-level thresholds used internally to compare verbosity.
+*
+* Higher numbers are more verbose.
 */
-function defineGenerator(generator) {
-	return generator;
-}
-//#endregion
-//#region src/defineLogger.ts
+const logLevel = {
+	silent: Number.NEGATIVE_INFINITY,
+	error: 0,
+	warn: 1,
+	info: 3,
+	verbose: 4
+};
 /**
-* Wraps a logger definition into a typed {@link Logger}.
+* Defines a reporter. When the definition has a `drain`, the returned reporter buffers each value
+* `report` returns and hands the array to `drain` once, then clears it. Without a `drain`, nothing
+* is buffered. Wiring the reporter onto the run's events is the host's job, so the reporter only
+* ever deals with a {@link GenerationResult}.
 *
 * @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))
+* import { createReporter, Diagnostics } from '@kubb/core'
+*
+* 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 defineLogger(logger) {
-	return logger;
+function createReporter(reporter) {
+	const drain = reporter.drain;
+	if (!drain) return {
+		name: reporter.name,
+		async report(result, context) {
+			await reporter.report(result, context);
+		}
+	};
+	const reports = [];
+	return {
+		name: reporter.name,
+		async report(result, context) {
+			reports.push(await reporter.report(result, context));
+		},
+		async drain(context) {
+			await drain(context, reports);
+			reports.length = 0;
+		}
+	};
+}
+//#endregion
+//#region src/reporters/report.ts
+/**
+* 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 buildReport(result) {
+	const { config, diagnostics, filesCreated, status, hrStart } = result;
+	const failed = Diagnostics.failedPlugins(diagnostics);
+	const total = config.plugins?.length ?? 0;
+	const counts = Diagnostics.count(diagnostics);
+	const problems = diagnostics.filter(Diagnostics.isProblem);
+	const timings = diagnostics.filter(Diagnostics.isPerformance).sort((a, b) => b.duration - a.duration).map((diagnostic) => ({
+		plugin: diagnostic.plugin,
+		durationMs: diagnostic.duration
+	}));
+	return {
+		name: config.name ?? "",
+		status,
+		plugins: {
+			passed: total - failed.length,
+			failed,
+			total
+		},
+		counts,
+		filesCreated,
+		durationMs: getElapsedMs(hrStart),
+		output: resolve(config.root, config.output.path),
+		timings,
+		diagnostics: problems.map((diagnostic) => Diagnostics.serialize(diagnostic))
+	};
+}
+//#endregion
+//#region src/reporters/cliReporter.ts
+/**
+* Builds the vitest/jest-style summary for one {@link Report}: right-aligned dim labels with
+* `N passed (total)` counts, and a per-plugin `Timings` section when `showTimings`.
+*/
+function buildSummaryLines(report, { showTimings }) {
+	const { status, plugins, counts, filesCreated, durationMs, output, timings } = report;
+	const rows = [];
+	rows.push(["Plugins", status === "success" ? `${styleText("green", `${plugins.passed} passed`)} (${plugins.total})` : `${styleText("green", `${plugins.passed} passed`)} | ${styleText("red", `${plugins.failed.length} failed`)} (${plugins.total})`]);
+	if (status === "failed" && plugins.failed.length > 0) rows.push(["Failed", plugins.failed.map((name) => randomCliColor(name)).join(", ")]);
+	if (counts.errors > 0 || counts.warnings > 0) {
+		const issues = [counts.errors > 0 ? styleText("red", `${counts.errors} ${counts.errors === 1 ? "error" : "errors"}`) : void 0, counts.warnings > 0 ? styleText("yellow", `${counts.warnings} ${counts.warnings === 1 ? "warning" : "warnings"}`) : void 0].filter(Boolean).join(" | ");
+		rows.push(["Issues", issues]);
+	}
+	rows.push(["Files", `${styleText("green", String(filesCreated))} generated`]);
+	rows.push(["Duration", styleText("green", formatMs(durationMs))]);
+	rows.push(["Output", output]);
+	const labelWidth = Math.max(...rows.map(([label]) => label.length), timings.length > 0 ? 7 : 0);
+	const lines = rows.map(([label, value]) => `${styleText("dim", label.padStart(labelWidth))}  ${value}`);
+	if (showTimings && timings.length > 0) {
+		const nameWidth = Math.max(0, ...timings.map((timing) => timing.plugin.length));
+		const indent = " ".repeat(labelWidth + 2);
+		lines.push(styleText("dim", "Timings".padStart(labelWidth)));
+		for (const timing of timings) {
+			const timeStr = formatMs(timing.durationMs);
+			const barLength = Math.min(Math.ceil(timing.durationMs / 100), 10);
+			const bar = styleText("dim", "█".repeat(barLength));
+			lines.push(`${indent}${styleText("dim", "•")} ${timing.plugin.padEnd(nameWidth)} ${bar} ${timeStr}`);
+		}
+	}
+	return lines;
 }
+/**
+* Renders the summary as plain `console.log` lines so it works in every CLI (no clack/TTY
+* dependency): a blank line, the config name colored by status, then the summary rows.
+*/
+function renderSummary(lines, { title, status }) {
+	console.log("");
+	if (title) console.log(styleText(status === "failed" ? "red" : "green", title));
+	for (const line of lines) console.log(line);
+}
+/**
+* The default `cli` reporter. Renders the {@link Report} for each config as it finishes, independent
+* of the live logger view. Suppressed at `silent`. The `verbose` level adds the per-plugin timings.
+*/
+const cliReporter = createReporter({
+	name: "cli",
+	report(result, { logLevel: logLevel$1 }) {
+		if (logLevel$1 <= logLevel.silent) return;
+		const report = buildReport(result);
+		renderSummary(buildSummaryLines(report, { showTimings: logLevel$1 >= logLevel.verbose }), {
+			title: report.name,
+			status: report.status
+		});
+	}
+});
 //#endregion
-//#region src/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")
+	];
+}
+/**
+* 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)}`)
+	];
+}
 /**
-* Creates a middleware factory using the hook-style `hooks` API.
+* 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']`), replacing the
+* old `--debug` flag.
 *
-* 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 Unlike the streaming logger it replaced, it captures the collected diagnostics once a
+* config finishes, not the live `kubb:info`/`kubb:plugin` event 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 = 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 = resolve(process$1.cwd(), ".kubb", baseName);
+		await write(pathName, `${content}\n`);
+		console.error(`Debug log written to ${relative(process$1.cwd(), pathName)}`);
+	}
+});
+//#endregion
+//#region src/reporters/jsonReporter.ts
+/**
+* The `json` reporter. `report` returns one config's {@link Report}, which {@link createReporter}
+* buffers, and `drain` writes them as a single pretty-printed JSON array on `kubb:lifecycle:end`.
+* Buffering keeps a multi-config run one valid JSON document on stdout instead of concatenated
+* objects that would break `jq .`. The terminal reporter is suppressed while `json` is active so
+* stdout stays valid JSON.
+*/
+const jsonReporter = createReporter({
+	name: "json",
+	report(result) {
+		return buildReport(result);
+	},
+	drain(_context, reports) {
+		process$1.stdout.write(`${JSON.stringify(reports, null, 2)}\n`);
+	}
+});
+//#endregion
+//#region src/createRenderer.ts
+/**
+* Defines a renderer factory. Renderers turn the generator's return value
+* (JSX, a template string, a tree of any shape) into `FileNode`s that get
+* written to disk.
 *
-* @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'
-*
-* // Stateless middleware
-* export const logMiddleware = defineMiddleware(() => ({
-*   name: 'log-middleware',
-*   hooks: {
-*     'kubb:build:end'({ files }) {
-*       console.log(`Build complete with ${files.length} files`)
-*     },
-*   },
-* }))
+* import { createRenderer } from '@kubb/core'
 *
-* // 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`.
-*
-* 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`).
+* Defines a parser with type-safe `this`. Used to register handlers for new
+* file extensions or to plug a non-TypeScript output into the build.
 *
 * @example
 * ```ts
-* import { definePlugin } from '@kubb/core'
+* import { defineParser } from '@kubb/core'
+* import { extractStringsFromNodes } from '@kubb/ast/utils'
 *
-* export const pluginTs = definePlugin((options: { prefix?: string } = {}) => ({
-*   name: 'plugin-ts',
-*   hooks: {
-*     'kubb:plugin:setup'(ctx) {
-*       ctx.setResolver(resolverTs)
-*     },
+* export const jsonParser = defineParser({
+*   name: 'json',
+*   extNames: ['.json'],
+*   parse(file) {
+*     return file.sources
+*       .map((source) => extractStringsFromNodes(source.nodes ?? []))
+*       .join('\n')
+*   },
+*   print(...nodes) {
+*     return nodes.map(String).join('\n')
 *   },
-* }))
-* ```
-*/
-function definePlugin(factory) {
-	return (options) => factory(options ?? {});
-}
-//#endregion
-//#region src/storages/memoryStorage.ts
-/**
-* In-memory storage driver. Useful for testing and dry-run scenarios where
-* generated output should be captured without touching the filesystem.
-*
-* All data lives in a `Map` scoped to the storage instance and is discarded
-* when the instance is garbage-collected.
-*
-* @example
-* ```ts
-* import { memoryStorage } from '@kubb/core'
-* import { defineConfig } from 'kubb'
-*
-* export default defineConfig({
-*   input:  { path: './petStore.yaml' },
-*   output: { path: './src/gen' },
-*   storage: memoryStorage(),
 * })
 * ```
 */
-const memoryStorage = createStorage(() => {
-	const store = /* @__PURE__ */ new Map();
-	return {
-		name: "memory",
-		async hasItem(key) {
-			return store.has(key);
-		},
-		async getItem(key) {
-			return store.get(key) ?? null;
-		},
-		async setItem(key, value) {
-			store.set(key, value);
-		},
-		async removeItem(key) {
-			store.delete(key);
-		},
-		async getKeys(base) {
-			const keys = [...store.keys()];
-			return base ? keys.filter((k) => k.startsWith(base)) : keys;
-		},
-		async clear(base) {
-			if (!base) {
-				store.clear();
-				return;
-			}
-			for (const key of store.keys()) if (key.startsWith(base)) store.delete(key);
-		}
-	};
-});
+function defineParser(parser) {
+	return parser;
+}
 //#endregion
-export { AsyncEventEmitter, FileManager, FileProcessor, PluginDriver, URLPath, ast, createAdapter, createKubb, createRenderer, createStorage, defineGenerator, defineLogger, defineMiddleware, defineParser, definePlugin, defineResolver, fsStorage, isInputPath, logLevel, memoryStorage };
+export { AsyncEventEmitter, Diagnostics, KubbDriver, Url, ast, cliReporter, createAdapter, createKubb, createRenderer, createReporter, createStorage, defineGenerator, defineParser, definePlugin, defineResolver, fileReporter, fsStorage, jsonReporter, logLevel, memoryStorage };
 
 //# sourceMappingURL=index.js.map