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

package/dist/index.js

@@ -1,10 +1,10 @@
 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-DV3p2Hky.js";
+import { a as definePlugin, c as DEFAULT_STUDIO_URL, i as defineResolver, l as logLevel, n as applyHookResult, o as DEFAULT_BANNER, r as FileManager, s as DEFAULT_EXTENSION, t as PluginDriver, u as camelCase } from "./PluginDriver-CGypdXHg.js";
 import { EventEmitter } from "node:events";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import * as ast from "@kubb/ast";
-import { extractStringsFromNodes, transform, walk } from "@kubb/ast";
+import { collectUsedSchemaNames, extractStringsFromNodes, transform, walk } from "@kubb/ast";
 import { version } from "node:process";
 //#region ../../internals/utils/src/errors.ts
 /**
@@ -524,6 +524,46 @@ function createAdapter(build) {
 	return (options) => build(options ?? {});
 }
 //#endregion
+//#region package.json
+var version$1 = "5.0.0-beta.11";
+//#endregion
+//#region src/createStorage.ts
+/**
+* Factory for implementing custom storage backends that control where generated files are written.
+*
+* Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
+* Kubb provides filesystem and in-memory implementations out of the box.
+*
+* @note Call the returned factory with optional options to instantiate the storage adapter.
+*
+* @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()
+* ```
+*/
+function createStorage(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 {
@@ -665,7 +705,8 @@ function joinSources(file) {
 * @internal
 */
 var FileProcessor = class {
-	#limit = pLimit(100);
+	events = new AsyncEventEmitter();
+	#limit = pLimit(16);
 	async parse(file, { parsers, extension } = {}) {
 		const parseExtName = extension?.[file.extname] || void 0;
 		if (!parsers || !file.extname) return joinSources(file);
@@ -673,8 +714,8 @@ var FileProcessor = class {
 		if (!parser) return joinSources(file);
 		return parser.parse(file, { extname: parseExtName });
 	}
-	async run(files, { parsers, mode = "sequential", extension, onStart, onEnd, onUpdate } = {}) {
-		await onStart?.(files);
+	async run(files, { parsers, mode = "sequential", extension } = {}) {
+		await this.events.emit("start", files);
 		const total = files.length;
 		let processed = 0;
 		const processOne = async (file) => {
@@ -684,7 +725,7 @@ var FileProcessor = class {
 			});
 			const currentProcessed = ++processed;
 			const percentage = currentProcessed / total * 100;
-			await onUpdate?.({
+			await this.events.emit("update", {
 				file,
 				source,
 				processed: currentProcessed,
@@ -694,56 +735,13 @@ var FileProcessor = class {
 		};
 		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);
+		await this.events.emit("end", files);
 		return files;
 	}
 };
 //#endregion
-//#region src/createStorage.ts
-/**
-* Factory for implementing custom storage backends that control where generated files are written.
-*
-* Takes a builder function `(options: TOptions) => Storage` and returns a factory `(options?: TOptions) => Storage`.
-* Kubb provides filesystem and in-memory implementations out of the box.
-*
-* @note Call the returned factory with optional options to instantiate the storage adapter.
-*
-* @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()
-* ```
-*/
-function createStorage(build) {
-	return (options) => build(options ?? {});
-}
-//#endregion
 //#region src/storages/fsStorage.ts
 /**
-* Detects the filesystem error used to indicate that a path does not exist.
-*/
-function isMissingPathError(error) {
-	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-}
-/**
 * Built-in filesystem storage driver.
 *
 * This is the default storage when no `storage` option is configured in the root config.
@@ -774,17 +772,15 @@ const fsStorage = createStorage(() => ({
 		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 });
+		} catch (_error) {
+			return false;
 		}
 	},
 	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 });
+		} catch (_error) {
+			return null;
 		}
 	},
 	async setItem(key, value) {
@@ -800,9 +796,8 @@ const fsStorage = createStorage(() => ({
 			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 });
+			} catch (_error) {
+				return;
 			}
 			for (const entry of entries) {
 				const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
@@ -819,37 +814,69 @@ const fsStorage = createStorage(() => ({
 	}
 }));
 //#endregion
-//#region package.json
-var version$1 = "5.0.0-beta.1";
-//#endregion
-//#region src/utils/diagnostics.ts
+//#region src/createKubb.ts
 /**
-* Returns a snapshot of the current runtime environment.
+* Builds a `Storage` view scoped to the file paths produced by the current build.
 *
-* Useful for attaching context to debug logs and error reports so that
-* issues can be reproduced without manual information gathering.
+* Reads delegate to the underlying `storage` (typically `fsStorage()`) so source bytes
+* stay where they were written instead of being held in an extra in-memory map.
+* Writing via `setItem` stores the content in the underlying storage and registers the
+* key so subsequent reads and `getKeys` are scoped to this build's output.
 */
-function getDiagnosticInfo() {
-	return {
-		nodeVersion: version,
-		KubbVersion: version$1,
-		platform: process.platform,
-		arch: process.arch,
-		cwd: process.cwd()
-	};
-}
-//#endregion
-//#region src/utils/isInputPath.ts
-function isInputPath(config) {
-	return typeof config?.input === "object" && config.input !== null && "path" in config.input;
+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);
+		},
+		async getItem(key) {
+			return paths.has(key) ? storage.getItem(key) : null;
+		},
+		async setItem(key, value) {
+			paths.add(key);
+			await storage.setItem(key, value);
+		},
+		async removeItem(key) {
+			paths.delete(key);
+			await storage.removeItem(key);
+		},
+		async getKeys(base) {
+			if (!base) return [...paths];
+			const result = [];
+			for (const key of paths) if (key.startsWith(base)) result.push(key);
+			return result;
+		},
+		async clear() {
+			paths.clear();
+			await storage.clear();
+		}
+	}))();
 }
-//#endregion
-//#region src/createKubb.ts
 async function setup(userConfig, options = {}) {
 	const hooks = options.hooks ?? new AsyncEventEmitter();
-	const sources = /* @__PURE__ */ new Map();
+	const config = {
+		...userConfig,
+		root: userConfig.root || process.cwd(),
+		parsers: userConfig.parsers ?? [],
+		adapter: userConfig.adapter,
+		output: {
+			format: false,
+			lint: false,
+			extension: DEFAULT_EXTENSION,
+			defaultBanner: DEFAULT_BANNER,
+			...userConfig.output
+		},
+		storage: userConfig.storage ?? fsStorage(),
+		devtools: userConfig.devtools ? {
+			studioUrl: DEFAULT_STUDIO_URL,
+			...typeof userConfig.devtools === "boolean" ? {} : userConfig.devtools
+		} : void 0,
+		plugins: userConfig.plugins ?? []
+	};
+	const driver = new PluginDriver(config, { hooks });
+	const storage = createSourcesView(config.storage);
 	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: [
@@ -859,7 +886,7 @@ async function setup(userConfig, options = {}) {
 			`  • 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)"}`,
+			`  • Storage: ${config.storage.name}`,
 			`  • Formatter: ${userConfig.output?.format || "none"}`,
 			`  • Linter: ${userConfig.output?.lint || "none"}`,
 			"Environment:",
@@ -880,73 +907,56 @@ async function setup(userConfig, options = {}) {
 			throw new Error(`Cannot read file/URL defined in \`input.path\` or set with \`kubb generate PATH\` in the CLI of your Kubb config ${userConfig.input.path}`, { cause: error });
 		}
 	}
-	if (!userConfig.adapter) throw new Error("Adapter should be defined");
-	const config = {
-		...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));
+		await config.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);
-	const adapter = config.adapter;
-	if (!adapter) throw new Error("No adapter configured. Please provide an adapter in your kubb.config.ts.");
-	const source = inputToAdapterSource(config);
-	await hooks.emit("kubb:debug", {
-		date: /* @__PURE__ */ new Date(),
-		logs: [`Running adapter: ${adapter.name}`]
-	});
-	driver.adapter = adapter;
-	driver.inputNode = await adapter.parse(source);
-	await hooks.emit("kubb:debug", {
-		date: /* @__PURE__ */ new Date(),
-		logs: [
-			`✓ Adapter '${adapter.name}' resolved InputNode`,
-			`  • Schemas: ${driver.inputNode.schemas.length}`,
-			`  • Operations: ${driver.inputNode.operations.length}`
-		]
-	});
+	if (config.adapter) {
+		const source = inputToAdapterSource(config);
+		await hooks.emit("kubb:debug", {
+			date: /* @__PURE__ */ new Date(),
+			logs: [`Running adapter: ${config.adapter.name}`]
+		});
+		driver.adapter = config.adapter;
+		driver.inputNode = await config.adapter.parse(source);
+		await hooks.emit("kubb:debug", {
+			date: /* @__PURE__ */ new Date(),
+			logs: [
+				`✓ Adapter '${config.adapter.name}' resolved InputNode`,
+				`  • Schemas: ${driver.inputNode.schemas.length}`,
+				`  • Operations: ${driver.inputNode.operations.length}`
+			]
+		});
+	}
 	return {
 		config,
 		hooks,
 		driver,
-		sources,
 		storage
 	};
 }
 /**
 * 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.
 */
 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.`);
+	if (!adapter || !inputNode) throw new Error(`[${plugin.name}] No adapter found. Add an OAS adapter (e.g. adapterOas()) before this plugin in your Kubb config.`);
 	function resolveRenderer(gen) {
 		return gen.renderer === null ? void 0 : gen.renderer ?? plugin.renderer ?? context.config.renderer;
 	}
@@ -956,10 +966,27 @@ async function runPluginAstHooks(plugin, context) {
 		...context,
 		resolver: driver.getResolver(plugin.name)
 	};
+	const operationFilterTypes = new Set([
+		"tag",
+		"operationId",
+		"path",
+		"method",
+		"contentType"
+	]);
+	const hasOperationBasedIncludes = include?.some(({ type }) => operationFilterTypes.has(type)) ?? false;
+	const hasSchemaNameIncludes = include?.some(({ type }) => type === "schemaName") ?? false;
+	let allowedSchemaNames;
+	if (hasOperationBasedIncludes && !hasSchemaNameIncludes) allowedSchemaNames = collectUsedSchemaNames(inputNode.operations.filter((op) => resolver.resolveOptions(op, {
+		options: plugin.options,
+		exclude,
+		include,
+		override
+	}) !== null), inputNode.schemas);
 	await walk(inputNode, {
 		depth: "shallow",
 		async schema(node) {
 			const transformedNode = plugin.transformer ? transform(node, plugin.transformer) : node;
+			if (allowedSchemaNames !== void 0 && transformedNode.name && !allowedSchemaNames.has(transformedNode.name)) return;
 			const options = resolver.resolveOptions(transformedNode, {
 				options: plugin.options,
 				exclude,
@@ -1012,10 +1039,49 @@ async function runPluginAstHooks(plugin, context) {
 	}
 }
 async function safeBuild(setupResult) {
-	const { driver, hooks, sources, storage } = setupResult;
+	const { driver, hooks, storage } = setupResult;
 	const failedPlugins = /* @__PURE__ */ new Set();
 	const pluginTimings = /* @__PURE__ */ new Map();
 	const config = driver.config;
+	const writtenPaths = /* @__PURE__ */ new Set();
+	const parsersMap = /* @__PURE__ */ new Map();
+	for (const parser of config.parsers) if (parser.extNames) for (const extname of parser.extNames) parsersMap.set(extname, parser);
+	const fileProcessor = new FileProcessor();
+	fileProcessor.events.on("start", async (processingFiles) => {
+		await hooks.emit("kubb:files:processing:start", { files: processingFiles });
+	});
+	fileProcessor.events.on("update", async ({ file, source, processed, total, percentage }) => {
+		await hooks.emit("kubb:file:processing:update", {
+			file,
+			source,
+			processed,
+			total,
+			percentage,
+			config
+		});
+		if (source) await storage.setItem(file.path, source);
+	});
+	fileProcessor.events.on("end", async (processed) => {
+		await hooks.emit("kubb:files:processing:end", { files: processed });
+		await hooks.emit("kubb:debug", {
+			date: /* @__PURE__ */ new Date(),
+			logs: [`✓ File write process completed for ${processed.length} files`]
+		});
+	});
+	async function flushPendingFiles() {
+		const files = driver.fileManager.files.filter((f) => !writtenPaths.has(f.path));
+		if (files.length === 0) return;
+		await hooks.emit("kubb:debug", {
+			date: /* @__PURE__ */ new Date(),
+			logs: [`Writing ${files.length} files...`]
+		});
+		await fileProcessor.run(files, {
+			parsers: parsersMap,
+			mode: "parallel",
+			extension: config.output.extension
+		});
+		for (const file of files) writtenPaths.add(file.path);
+	}
 	try {
 		await driver.emitSetupHooks();
 		if (driver.adapter && driver.inputNode) await hooks.emit("kubb:build:start", {
@@ -1051,6 +1117,7 @@ async function safeBuild(setupResult) {
 					},
 					upsertFile: (...files) => driver.fileManager.upsert(...files)
 				});
+				await flushPendingFiles();
 				await hooks.emit("kubb:debug", {
 					date: /* @__PURE__ */ new Date(),
 					logs: [`✓ Plugin started successfully (${formatMs(duration)})`]
@@ -1070,6 +1137,7 @@ async function safeBuild(setupResult) {
 					},
 					upsertFile: (...files) => driver.fileManager.upsert(...files)
 				});
+				await flushPendingFiles();
 				await hooks.emit("kubb:debug", {
 					date: errorTimestamp,
 					logs: [
@@ -1093,42 +1161,8 @@ async function safeBuild(setupResult) {
 			},
 			upsertFile: (...files) => driver.fileManager.upsert(...files)
 		});
+		await flushPendingFiles();
 		const files = driver.fileManager.files;
-		const parsersMap = /* @__PURE__ */ new Map();
-		for (const parser of config.parsers) if (parser.extNames) for (const extname of parser.extNames) parsersMap.set(extname, parser);
-		const fileProcessor = new FileProcessor();
-		await hooks.emit("kubb:debug", {
-			date: /* @__PURE__ */ new Date(),
-			logs: [`Writing ${files.length} files...`]
-		});
-		await fileProcessor.run(files, {
-			parsers: parsersMap,
-			extension: config.output.extension,
-			onStart: async (processingFiles) => {
-				await hooks.emit("kubb:files:processing:start", { files: processingFiles });
-			},
-			onUpdate: async ({ file, source, processed, total, percentage }) => {
-				await hooks.emit("kubb:file:processing:update", {
-					file,
-					source,
-					processed,
-					total,
-					percentage,
-					config
-				});
-				if (source) {
-					await storage?.setItem(file.path, source);
-					sources.set(file.path, source);
-				}
-			},
-			onEnd: async (processedFiles) => {
-				await hooks.emit("kubb:files:processing:end", { files: processedFiles });
-				await hooks.emit("kubb:debug", {
-					date: /* @__PURE__ */ new Date(),
-					logs: [`✓ File write process completed for ${processedFiles.length} files`]
-				});
-			}
-		});
 		await hooks.emit("kubb:build:end", {
 			files,
 			config,
@@ -1139,7 +1173,7 @@ async function safeBuild(setupResult) {
 			files,
 			driver,
 			pluginTimings,
-			sources
+			storage
 		};
 	} catch (error) {
 		return {
@@ -1148,14 +1182,14 @@ async function safeBuild(setupResult) {
 			driver,
 			pluginTimings,
 			error,
-			sources
+			storage
 		};
 	} finally {
 		driver.dispose();
 	}
 }
 async function build(setupResult) {
-	const { files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(setupResult);
+	const { files, driver, failedPlugins, pluginTimings, error, storage } = await safeBuild(setupResult);
 	if (error) throw error;
 	if (failedPlugins.size > 0) {
 		const errors = [...failedPlugins].map(({ error }) => error);
@@ -1167,32 +1201,48 @@ async function build(setupResult) {
 		driver,
 		pluginTimings,
 		error: void 0,
-		sources
+		storage
 	};
 }
-function inputToAdapterSource(config) {
-	if (Array.isArray(config.input)) return {
-		type: "paths",
-		paths: config.input.map((i) => new URLPath(i.path).isURL ? i.path : resolve(config.root, i.path))
+/**
+* Returns a snapshot of the current runtime environment.
+*
+* Useful for attaching context to debug logs and error reports so that
+* issues can be reproduced without manual information gathering.
+*/
+function getDiagnosticInfo() {
+	return {
+		nodeVersion: version,
+		KubbVersion: version$1,
+		platform: process.platform,
+		arch: process.arch,
+		cwd: process.cwd()
 	};
-	if ("data" in config.input) return {
+}
+function isInputPath(config) {
+	return typeof config?.input === "object" && config.input !== null && "path" in config.input;
+}
+function inputToAdapterSource(config) {
+	const input = config.input;
+	if (!input) throw new Error("[kubb] input is required when using an adapter. Provide input.path or input.data in your config.");
+	if ("data" in input) return {
 		type: "data",
-		data: config.input.data
+		data: input.data
 	};
-	if (new URLPath(config.input.path).isURL) return {
+	if (new URLPath(input.path).isURL) return {
 		type: "path",
-		path: config.input.path
+		path: input.path
 	};
 	return {
 		type: "path",
-		path: resolve(config.root, config.input.path)
+		path: resolve(config.root, input.path)
 	};
 }
 /**
 * Creates a Kubb instance bound to a single config entry.
 *
 * Accepts a user-facing config shape and resolves it to a full {@link Config} during
-* `setup()`. The instance then holds shared state (`hooks`, `sources`, `driver`, `config`)
+* `setup()`. The instance then holds shared state (`hooks`, `storage`, `driver`, `config`)
 * across the `setup → build` lifecycle. Attach event listeners to `kubb.hooks` before
 * calling `setup()` or `build()`.
 *
@@ -1214,14 +1264,17 @@ function createKubb(userConfig, options = {}) {
 		get hooks() {
 			return hooks;
 		},
-		get sources() {
-			return setupResult?.sources ?? /* @__PURE__ */ new Map();
+		get storage() {
+			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing storage");
+			return setupResult.storage;
 		},
 		get driver() {
-			return setupResult?.driver;
+			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing driver");
+			return setupResult.driver;
 		},
 		get config() {
-			return setupResult?.config;
+			if (!setupResult) throw new Error("[kubb] setup() must be called before accessing config");
+			return setupResult.config;
 		},
 		async setup() {
 			setupResult = await setup(userConfig, { hooks });
@@ -1285,7 +1338,11 @@ function defineGenerator(generator) {
 /**
 * Wraps a logger definition into a typed {@link Logger}.
 *
-* @example
+* The optional second type parameter `TInstallReturn` allows loggers to return
+* a value from `install` — for example, a sink factory that the caller can
+* forward to hook execution.
+*
+* @example Basic logger
 * ```ts
 * export const myLogger = defineLogger({
 *   name: 'my-logger',
@@ -1295,6 +1352,17 @@ function defineGenerator(generator) {
 *   },
 * })
 * ```
+*
+* @example Logger that returns a hook sink factory
+* ```ts
+* export const myLogger = defineLogger<LoggerOptions, HookSinkFactory>({
+*   name: 'my-logger',
+*   install(context, options) {
+*     // … register event handlers …
+*     return (commandWithArgs) => ({ onStdout: console.log })
+*   },
+* })
+* ```
 */
 function defineLogger(logger) {
 	return logger;
@@ -1365,34 +1433,6 @@ function defineParser(parser) {
 	return parser;
 }
 //#endregion
-//#region src/definePlugin.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`).
-*
-* @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/storages/memoryStorage.ts
 /**
 * In-memory storage driver. Useful for testing and dry-run scenarios where