@kubb/core 5.0.0-alpha.16 → 5.0.0-alpha.18

package/dist/index.cjs

@@ -3,13 +3,12 @@ Object.defineProperties(exports, {
 	[Symbol.toStringTag]: { value: "Module" }
 });
 const require_chunk = require("./chunk-ByKO4r7w.cjs");
-let _kubb_ast = require("@kubb/ast");
-let node_path = require("node:path");
-node_path = require_chunk.__toESM(node_path);
 let node_events = require("node:events");
-let node_util = require("node:util");
 let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let _kubb_ast = require("@kubb/ast");
 let _kubb_react_fabric = require("@kubb/react-fabric");
 let _kubb_react_fabric_parsers = require("@kubb/react-fabric/parsers");
 let _kubb_react_fabric_plugins = require("@kubb/react-fabric/plugins");
@@ -22,12 +21,23 @@ let remeda = require("remeda");
 let empathic_package = require("empathic/package");
 empathic_package = require_chunk.__toESM(empathic_package);
 let semver = require("semver");
-//#region ../../internals/utils/dist/index.js
-/** Thrown when a plugin's configuration or input fails validation. */
+//#region ../../internals/utils/src/errors.ts
+/** Thrown when a plugin's configuration or input fails validation.
+*
+* @example
+* ```ts
+* throw new ValidationPluginError('Invalid config: "output.path" is required')
+* ```
+*/
 var ValidationPluginError = class extends Error {};
 /**
 * Thrown when one or more errors occur during a Kubb build.
 * Carries the full list of underlying errors on `errors`.
+*
+* @example
+* ```ts
+* throw new BuildError('Build failed', { errors: [err1, err2] })
+* ```
 */
 var BuildError = class extends Error {
 	errors;
@@ -39,19 +49,34 @@ var BuildError = class extends Error {
 };
 /**
 * Coerces an unknown thrown value to an `Error` instance.
-* When the value is already an `Error` it is returned as-is;
-* otherwise a new `Error` is created whose message is `String(value)`.
+* Returns the value as-is when it is already an `Error`; otherwise wraps it with `String(value)`.
+*
+* @example
+* ```ts
+* try { ... } catch(err) {
+*   throw new BuildError('Build failed', { cause: toError(err), errors: [] })
+* }
+* ```
 */
 function toError(value) {
 	return value instanceof Error ? value : new Error(String(value));
 }
+//#endregion
+//#region ../../internals/utils/src/asyncEventEmitter.ts
 /**
-* A typed EventEmitter that awaits all async listeners before resolving.
+* Typed `EventEmitter` that awaits all async listeners before resolving.
 * Wraps Node's `EventEmitter` with full TypeScript event-map inference.
+*
+* @example
+* ```ts
+* const emitter = new AsyncEventEmitter<{ build: [name: string] }>()
+* emitter.on('build', async (name) => { console.log(name) })
+* await emitter.emit('build', 'petstore') // all listeners awaited
+* ```
 */
 var AsyncEventEmitter = class {
 	/**
-	* `maxListener` controls the maximum number of listeners per event before Node emits a memory-leak warning.
+	* Maximum number of listeners per event before Node emits a memory-leak warning.
 	* @default 10
 	*/
 	constructor(maxListener = 10) {
@@ -59,8 +84,13 @@ var AsyncEventEmitter = class {
 	}
 	#emitter = new node_events.EventEmitter();
 	/**
-	* Emits an event and awaits all registered listeners in parallel.
+	* Emits `eventName` and awaits all registered listeners in parallel.
 	* Throws if any listener rejects, wrapping the cause with the event name and serialized arguments.
+	*
+	* @example
+	* ```ts
+	* await emitter.emit('build', 'petstore')
+	* ```
 	*/
 	async emit(eventName, ...eventArgs) {
 		const listeners = this.#emitter.listeners(eventName);
@@ -79,11 +109,25 @@ var AsyncEventEmitter = class {
 			}
 		}));
 	}
-	/** Registers a persistent listener for the given event. */
+	/**
+	* Registers a persistent listener for `eventName`.
+	*
+	* @example
+	* ```ts
+	* emitter.on('build', async (name) => { console.log(name) })
+	* ```
+	*/
 	on(eventName, handler) {
 		this.#emitter.on(eventName, handler);
 	}
-	/** Registers a one-shot listener that removes itself after the first invocation. */
+	/**
+	* Registers a one-shot listener that removes itself after the first invocation.
+	*
+	* @example
+	* ```ts
+	* emitter.onOnce('build', async (name) => { console.log(name) })
+	* ```
+	*/
 	onOnce(eventName, handler) {
 		const wrapper = (...args) => {
 			this.off(eventName, wrapper);
@@ -91,15 +135,31 @@ var AsyncEventEmitter = class {
 		};
 		this.on(eventName, wrapper);
 	}
-	/** Removes a previously registered listener. */
+	/**
+	* Removes a previously registered listener.
+	*
+	* @example
+	* ```ts
+	* emitter.off('build', handler)
+	* ```
+	*/
 	off(eventName, handler) {
 		this.#emitter.off(eventName, handler);
 	}
-	/** Removes all listeners from every event channel. */
+	/**
+	* Removes all listeners from every event channel.
+	*
+	* @example
+	* ```ts
+	* emitter.removeAll()
+	* ```
+	*/
 	removeAll() {
 		this.#emitter.removeAllListeners();
 	}
 };
+//#endregion
+//#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
 * Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
@@ -156,190 +216,18 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	}) : camelCase(part));
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
-/** Returns a `CLIAdapter` with type inference. Pass a different adapter to `createCLI` to swap the CLI engine. */
-function defineCLIAdapter(adapter) {
-	return adapter;
-}
-/**
-* Serializes `CommandDefinition[]` to a plain, JSON-serializable structure.
-* Use to expose CLI capabilities to AI agents or MCP tools.
-*/
-function getCommandSchema(defs) {
-	return defs.map(serializeCommand);
-}
-function serializeCommand(def) {
-	return {
-		name: def.name,
-		description: def.description,
-		arguments: def.arguments,
-		options: serializeOptions(def.options ?? {}),
-		subCommands: def.subCommands ? def.subCommands.map(serializeCommand) : []
-	};
-}
-function serializeOptions(options) {
-	return Object.entries(options).map(([name, opt]) => {
-		return {
-			name,
-			flags: `${opt.short ? `-${opt.short}, ` : ""}--${name}${opt.type === "string" ? ` <${opt.hint ?? name}>` : ""}`,
-			type: opt.type,
-			description: opt.description,
-			...opt.default !== void 0 ? { default: opt.default } : {},
-			...opt.hint ? { hint: opt.hint } : {},
-			...opt.enum ? { enum: opt.enum } : {},
-			...opt.required ? { required: opt.required } : {}
-		};
-	});
-}
-/** Prints formatted help output for a command using its `CommandDefinition`. */
-function renderHelp(def, parentName) {
-	const schema = getCommandSchema([def])[0];
-	const programName = parentName ? `${parentName} ${schema.name}` : schema.name;
-	const argsPart = schema.arguments?.length ? ` ${schema.arguments.join(" ")}` : "";
-	const subCmdPart = schema.subCommands.length ? " <command>" : "";
-	console.log(`\n${(0, node_util.styleText)("bold", "Usage:")} ${programName}${argsPart}${subCmdPart} [options]\n`);
-	if (schema.description) console.log(`  ${schema.description}\n`);
-	if (schema.subCommands.length) {
-		console.log((0, node_util.styleText)("bold", "Commands:"));
-		for (const sub of schema.subCommands) console.log(`  ${(0, node_util.styleText)("cyan", sub.name.padEnd(16))}${sub.description}`);
-		console.log();
-	}
-	const options = [...schema.options, {
-		name: "help",
-		flags: "-h, --help",
-		type: "boolean",
-		description: "Show help"
-	}];
-	console.log((0, node_util.styleText)("bold", "Options:"));
-	for (const opt of options) {
-		const flags = (0, node_util.styleText)("cyan", opt.flags.padEnd(30));
-		const defaultPart = opt.default !== void 0 ? (0, node_util.styleText)("dim", ` (default: ${opt.default})`) : "";
-		console.log(`  ${flags}${opt.description}${defaultPart}`);
-	}
-	console.log();
-}
-function buildParseOptions(def) {
-	const result = { help: {
-		type: "boolean",
-		short: "h"
-	} };
-	for (const [name, opt] of Object.entries(def.options ?? {})) result[name] = {
-		type: opt.type,
-		...opt.short ? { short: opt.short } : {},
-		...opt.default !== void 0 ? { default: opt.default } : {}
-	};
-	return result;
-}
-async function runCommand(def, argv, parentName) {
-	const parseOptions = buildParseOptions(def);
-	let parsed;
-	try {
-		const result = (0, node_util.parseArgs)({
-			args: argv,
-			options: parseOptions,
-			allowPositionals: true,
-			strict: false
-		});
-		parsed = {
-			values: result.values,
-			positionals: result.positionals
-		};
-	} catch {
-		renderHelp(def, parentName);
-		process.exit(1);
-	}
-	if (parsed.values["help"]) {
-		renderHelp(def, parentName);
-		process.exit(0);
-	}
-	for (const [name, opt] of Object.entries(def.options ?? {})) if (opt.required && parsed.values[name] === void 0) {
-		console.error((0, node_util.styleText)("red", `Error: --${name} is required`));
-		renderHelp(def, parentName);
-		process.exit(1);
-	}
-	if (!def.run) {
-		renderHelp(def, parentName);
-		process.exit(0);
-	}
-	try {
-		await def.run(parsed);
-	} catch (err) {
-		console.error((0, node_util.styleText)("red", `Error: ${err instanceof Error ? err.message : String(err)}`));
-		renderHelp(def, parentName);
-		process.exit(1);
-	}
-}
-function printRootHelp(programName, version, defs) {
-	console.log(`\n${(0, node_util.styleText)("bold", "Usage:")} ${programName} <command> [options]\n`);
-	console.log(`  Kubb generation — v${version}\n`);
-	console.log((0, node_util.styleText)("bold", "Commands:"));
-	for (const def of defs) console.log(`  ${(0, node_util.styleText)("cyan", def.name.padEnd(16))}${def.description}`);
-	console.log();
-	console.log((0, node_util.styleText)("bold", "Options:"));
-	console.log(`  ${(0, node_util.styleText)("cyan", "-v, --version".padEnd(30))}Show version number`);
-	console.log(`  ${(0, node_util.styleText)("cyan", "-h, --help".padEnd(30))}Show help`);
-	console.log();
-	console.log(`Run ${(0, node_util.styleText)("cyan", `${programName} <command> --help`)} for command-specific help.\n`);
-}
-defineCLIAdapter({
-	renderHelp(def, parentName) {
-		renderHelp(def, parentName);
-	},
-	async run(defs, argv, opts) {
-		const { programName, defaultCommandName, version } = opts;
-		const args = argv.length >= 2 && argv[0]?.includes("node") ? argv.slice(2) : argv;
-		if (args[0] === "--version" || args[0] === "-v") {
-			console.log(version);
-			process.exit(0);
-		}
-		if (args[0] === "--help" || args[0] === "-h") {
-			printRootHelp(programName, version, defs);
-			process.exit(0);
-		}
-		if (args.length === 0) {
-			const defaultDef = defs.find((d) => d.name === defaultCommandName);
-			if (defaultDef?.run) await runCommand(defaultDef, [], programName);
-			else printRootHelp(programName, version, defs);
-			return;
-		}
-		const [first, ...rest] = args;
-		const isKnownSubcommand = defs.some((d) => d.name === first);
-		let def;
-		let commandArgv;
-		let parentName;
-		if (isKnownSubcommand) {
-			def = defs.find((d) => d.name === first);
-			commandArgv = rest;
-			parentName = programName;
-		} else {
-			def = defs.find((d) => d.name === defaultCommandName);
-			commandArgv = args;
-			parentName = programName;
-		}
-		if (!def) {
-			console.error(`Unknown command: ${first}`);
-			printRootHelp(programName, version, defs);
-			process.exit(1);
-		}
-		if (def.subCommands?.length) {
-			const [subName, ...subRest] = commandArgv;
-			const subDef = def.subCommands.find((s) => s.name === subName);
-			if (subName === "--help" || subName === "-h") {
-				renderHelp(def, parentName);
-				process.exit(0);
-			}
-			if (!subDef) {
-				renderHelp(def, parentName);
-				process.exit(subName ? 1 : 0);
-			}
-			await runCommand(subDef, subRest, `${parentName} ${def.name}`);
-			return;
-		}
-		await runCommand(def, commandArgv, parentName);
-	}
-});
+//#endregion
+//#region ../../internals/utils/src/time.ts
 /**
-* Calculates elapsed time in milliseconds from a high-resolution start time.
-* Rounds to 2 decimal places to provide sub-millisecond precision without noise.
+* 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);
@@ -347,39 +235,22 @@ function getElapsedMs(hrStart) {
 	return Math.round(ms * 100) / 100;
 }
 /**
-* Converts a millisecond duration into a human-readable string.
-* Adjusts units (ms, s, m s) based on the magnitude of the duration.
+* 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'
+* ```
 */
 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`;
 }
-/**
-* 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");
+//#endregion
+//#region ../../internals/utils/src/fs.ts
 /**
 * Converts all backslashes to forward slashes.
 * Extended-length Windows paths (`\\?\...`) are left unchanged.
@@ -389,8 +260,14 @@ function toSlash(p) {
 	return p.replaceAll("\\", "/");
 }
 /**
-* Returns the relative path from `rootDir` to `filePath`, always using
-* forward slashes and prefixed with `./` when not already traversing upward.
+* Returns the relative path from `rootDir` to `filePath`, always using forward slashes
+* and prefixed with `./` when not already traversing upward.
+*
+* @example
+* ```ts
+* getRelativePath('/src/components', '/src/components/Button.tsx') // './Button.tsx'
+* getRelativePath('/src/components', '/src/utils/helpers.ts')      // '../utils/helpers.ts'
+* ```
 */
 function getRelativePath(rootDir, filePath) {
 	if (!rootDir || !filePath) throw new Error(`Root and file should be filled in when retrieving the relativePath, ${rootDir || ""} ${filePath || ""}`);
@@ -400,35 +277,54 @@ function getRelativePath(rootDir, filePath) {
 /**
 * 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 (0, node_fs_promises.access)(path).then(() => true, () => false);
 }
-/** Synchronous counterpart of `read`. */
+/**
+* Synchronous counterpart of `read`.
+*
+* @example
+* ```ts
+* const source = readSync('./src/Pet.ts')
+* ```
+*/
 function readSync(path) {
 	return (0, node_fs.readFileSync)(path, { encoding: "utf8" });
 }
 /**
 * Writes `data` to `path`, trimming leading/trailing whitespace before saving.
-* Skips the write and returns `undefined` when the trimmed content is empty or
-* identical to what is already on disk.
+* Skips the write when the trimmed content is empty or identical to what is already on disk.
 * Creates any missing parent directories automatically.
-* When `sanity` is `true`, re-reads the file after writing and throws if the
-* content does not match.
+* When `sanity` is `true`, re-reads the file after writing and throws if the content does not match.
+*
+* @example
+* ```ts
+* await write('./src/Pet.ts', source)         // writes and returns trimmed content
+* await write('./src/Pet.ts', source)         // null — file unchanged
+* await write('./src/Pet.ts', '  ')           // null — empty content skipped
+* ```
 */
 async function write(path, data, options = {}) {
 	const trimmed = data.trim();
-	if (trimmed === "") return void 0;
+	if (trimmed === "") return null;
 	const resolved = (0, node_path.resolve)(path);
 	if (typeof Bun !== "undefined") {
 		const file = Bun.file(resolved);
-		if ((await file.exists() ? await file.text() : null) === trimmed) return void 0;
+		if ((await file.exists() ? await file.text() : null) === trimmed) return null;
 		await Bun.write(resolved, trimmed);
 		return trimmed;
 	}
 	try {
-		if (await (0, node_fs_promises.readFile)(resolved, { encoding: "utf-8" }) === trimmed) return void 0;
+		if (await (0, node_fs_promises.readFile)(resolved, { encoding: "utf-8" }) === trimmed) return null;
 	} catch {}
 	await (0, node_fs_promises.mkdir)((0, node_path.dirname)(resolved), { recursive: true });
 	await (0, node_fs_promises.writeFile)(resolved, trimmed, { encoding: "utf-8" });
@@ -439,16 +335,32 @@ async function write(path, data, options = {}) {
 	}
 	return trimmed;
 }
-/** Recursively removes `path`. Silently succeeds when `path` does not exist. */
+/**
+* Recursively removes `path`. Silently succeeds when `path` does not exist.
+*
+* @example
+* ```ts
+* await clean('./dist')
+* ```
+*/
 async function clean(path) {
 	return (0, node_fs_promises.rm)(path, {
 		recursive: true,
 		force: true
 	});
 }
+//#endregion
+//#region ../../internals/utils/src/names.ts
 /**
 * Registers `originalName` in `data` without altering the returned name.
-* Use this when you need to track usage frequency but always emit the original identifier.
+* Use when you need to track usage frequency but always emit the original identifier.
+*
+* @example
+* ```ts
+* const seen: Record<string, number> = {}
+* setUniqueName('Foo', seen) // 'Foo'  (seen = { Foo: 1 })
+* setUniqueName('Foo', seen) // 'Foo'  (seen = { Foo: 2 })
+* ```
 */
 function setUniqueName(originalName, data) {
 	let used = data[originalName] || 0;
@@ -459,10 +371,21 @@ function setUniqueName(originalName, data) {
 	data[originalName] = 1;
 	return originalName;
 }
-/** Type guard for a rejected `Promise.allSettled` result with a typed `reason`. */
+//#endregion
+//#region ../../internals/utils/src/promise.ts
+/** Returns `true` when `result` is a rejected `Promise.allSettled` result with a typed `reason`.
+*
+* @example
+* ```ts
+* const results = await Promise.allSettled([p1, p2])
+* results.filter(isPromiseRejectedResult<Error>).map((r) => r.reason.message)
+* ```
+*/
 function isPromiseRejectedResult(result) {
 	return result.status === "rejected";
 }
+//#endregion
+//#region ../../internals/utils/src/reserved.ts
 /**
 * JavaScript and Java reserved words.
 * @link https://github.com/jonschlinkert/reserved/blob/master/index.js
@@ -551,8 +474,14 @@ const reservedWords = new Set([
 	"valueOf"
 ]);
 /**
-* Prefixes a word with `_` when it is a reserved JavaScript/Java identifier
-* or starts with a digit.
+* Prefixes `word` with `_` when it is a reserved JavaScript/Java identifier or starts with a digit.
+*
+* @example
+* ```ts
+* transformReservedWord('class')  // '_class'
+* transformReservedWord('42foo')  // '_42foo'
+* transformReservedWord('status') // 'status'
+* ```
 */
 function transformReservedWord(word) {
 	const firstChar = word.charCodeAt(0);
@@ -561,6 +490,13 @@ function transformReservedWord(word) {
 }
 /**
 * Returns `true` when `name` is a syntactically valid JavaScript variable name.
+*
+* @example
+* ```ts
+* isValidVarName('status')  // true
+* isValidVarName('class')   // false (reserved word)
+* isValidVarName('42foo')   // false (starts with digit)
+* ```
 */
 function isValidVarName(name) {
 	try {
@@ -570,6 +506,8 @@ function isValidVarName(name) {
 	}
 	return true;
 }
+//#endregion
+//#region ../../internals/utils/src/urlPath.ts
 /**
 * Parses and transforms an OpenAPI/Swagger path string into various URL formats.
 *
@@ -579,18 +517,33 @@ function isValidVarName(name) {
 * p.template // '`/pet/${petId}`'
 */
 var URLPath = class {
-	/** The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`. */
+	/**
+	* The raw OpenAPI/Swagger path string, e.g. `/pet/{petId}`.
+	*/
 	path;
 	#options;
 	constructor(path, options = {}) {
 		this.path = path;
 		this.#options = options;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').URL // '/pet/:petId'
+	* ```
+	*/
 	get URL() {
 		return this.toURLPath();
 	}
-	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`). */
+	/** Returns `true` when `path` is a fully-qualified URL (e.g. starts with `https://`).
+	*
+	* @example
+	* ```ts
+	* new URLPath('https://petstore.swagger.io/v2/pet').isURL // true
+	* new URLPath('/pet/{petId}').isURL                       // false
+	* ```
+	*/
 	get isURL() {
 		try {
 			return !!new URL(this.path).href;
@@ -608,11 +561,25 @@ var URLPath = class {
 	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. */
+	/** Returns the path and its extracted params as a structured `URLObject`, or as a stringified expression when `stringify` is set.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').object
+	* // { url: '/pet/:petId', params: { petId: 'petId' } }
+	* ```
+	*/
 	get object() {
 		return this.toObject();
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters. */
+	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	*
+	* @example
+	* ```ts
+	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
+	* new URLPath('/pet').params         // undefined
+	* ```
+	*/
 	get params() {
 		return this.getParams();
 	}
@@ -620,7 +587,9 @@ var URLPath = class {
 		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. */
+	/**
+	* Iterates over every `{param}` token in `path`, calling `fn` with the raw token and transformed name.
+	*/
 	#eachParam(fn) {
 		for (const match of this.path.matchAll(/\{([^}]+)\}/g)) {
 			const raw = match[1];
@@ -657,6 +626,12 @@ var URLPath = class {
 	* 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 = {};
@@ -666,7 +641,13 @@ var URLPath = class {
 		});
 		return Object.keys(params).length > 0 ? params : void 0;
 	}
-	/** Converts the OpenAPI path to Express-style colon syntax, e.g. `/pet/{petId}` → `/pet/:petId`. */
+	/** 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");
 	}
@@ -684,10 +665,27 @@ function isInputPath(config) {
 }
 //#endregion
 //#region src/constants.ts
+/**
+* Base URL for the Kubb Studio web app.
+*/
 const DEFAULT_STUDIO_URL = "https://studio.kubb.dev";
+/**
+* File name used for generated barrel (index) files.
+*/
 const BARREL_FILENAME = "index.ts";
+/**
+* Default banner style written at the top of every generated file.
+*/
 const DEFAULT_BANNER = "simple";
+/**
+* Default file-extension mapping used when no explicit mapping is configured.
+*/
 const DEFAULT_EXTENSION = { ".ts": ".ts" };
+/**
+* Numeric log-level thresholds used internally to compare verbosity.
+*
+* Higher numbers are more verbose.
+*/
 const logLevel = {
 	silent: Number.NEGATIVE_INFINITY,
 	error: 0,
@@ -696,6 +694,13 @@ const logLevel = {
 	verbose: 4,
 	debug: 5
 };
+/**
+* CLI command descriptors for each supported linter.
+*
+* Each entry contains the executable `command`, an `args` factory that maps an
+* output path to the correct argument list, and an `errorMessage` shown when
+* the linter is not found.
+*/
 const linters = {
 	eslint: {
 		command: "eslint",
@@ -717,6 +722,13 @@ const linters = {
 		errorMessage: "Oxlint not found"
 	}
 };
+/**
+* CLI command descriptors for each supported code formatter.
+*
+* Each entry contains the executable `command`, an `args` factory that maps an
+* output path to the correct argument list, and an `errorMessage` shown when
+* the formatter is not found.
+*/
 const formatters = {
 	prettier: {
 		command: "prettier",
@@ -916,7 +928,11 @@ function validateConcurrency(concurrency) {
 //#endregion
 //#region src/utils/executeStrategies.ts
 /**
-* Chains promises
+* Runs promise functions in sequence, threading each result into the next call.
+*
+* - Each function receives the accumulated state from the previous call.
+* - Skips functions that return a falsy value (acts as a no-op for that step).
+* - Returns an array of all individual results.
 */
 function hookSeq(promises) {
 	return promises.filter(Boolean).reduce((promise, func) => {
@@ -929,7 +945,10 @@ function hookSeq(promises) {
 	}, Promise.resolve([]));
 }
 /**
-* Chains promises, first non-null result stops and returns
+* Runs promise functions in sequence and returns the first non-null result.
+*
+* - Stops as soon as `nullCheck` passes for a result (default: `!== null`).
+* - Subsequent functions are skipped once a match is found.
 */
 function hookFirst(promises, nullCheck = (state) => state !== null) {
 	let promise = Promise.resolve(null);
@@ -940,7 +959,10 @@ function hookFirst(promises, nullCheck = (state) => state !== null) {
 	return promise;
 }
 /**
-* Runs an array of promise functions with optional concurrency limit.
+* Runs promise functions concurrently and returns all settled results.
+*
+* - Limits simultaneous executions to `concurrency` (default: unlimited).
+* - Uses `Promise.allSettled` so individual failures do not cancel other tasks.
 */
 function hookParallel(promises, concurrency = Number.POSITIVE_INFINITY) {
 	const limit = pLimit(concurrency);
@@ -1447,11 +1469,14 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version = "5.0.0-alpha.16";
+var version = "5.0.0-alpha.18";
 //#endregion
 //#region src/utils/diagnostics.ts
 /**
-* Get diagnostic information for debugging
+* 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 {
@@ -1464,6 +1489,17 @@ function getDiagnosticInfo() {
 }
 //#endregion
 //#region src/build.ts
+/**
+* Initializes all Kubb infrastructure for a build without executing any plugins.
+*
+* - Validates the input path (when applicable).
+* - Applies config defaults (`root`, `output.*`, `devtools`).
+* - Creates the Fabric instance and wires storage, format, and lint hooks.
+* - Runs the adapter (if configured) to produce the universal `RootNode`.
+*
+* Pass the returned {@link SetupResult} directly to {@link safeBuild} or {@link build}
+* via the `overrides` argument to reuse the same infrastructure across multiple runs.
+*/
 async function setup(options) {
 	const { config: userConfig, events = new AsyncEventEmitter() } = options;
 	const sources = /* @__PURE__ */ new Map();
@@ -1590,6 +1626,12 @@ async function setup(options) {
 		sources
 	};
 }
+/**
+* Runs a full Kubb build and throws on any error or plugin failure.
+*
+* Internally delegates to {@link safeBuild} and rethrows collected errors.
+* Pass an existing {@link SetupResult} via `overrides` to skip the setup phase.
+*/
 async function build(options, overrides) {
 	const { fabric, files, driver, failedPlugins, pluginTimings, error, sources } = await safeBuild(options, overrides);
 	if (error) throw error;
@@ -1607,6 +1649,16 @@ async function build(options, overrides) {
 		sources
 	};
 }
+/**
+* Runs a full Kubb build and captures errors instead of throwing.
+*
+* - Installs each plugin in order, recording failures in `failedPlugins`.
+* - Generates the root barrel file when `output.barrelType` is set.
+* - Writes all files through Fabric.
+*
+* Returns a {@link BuildOutput} even on failure — inspect `error` and
+* `failedPlugins` to determine whether the build succeeded.
+*/
 async function safeBuild(options, overrides) {
 	const { fabric, driver, events, sources } = overrides ? overrides : await setup(options);
 	const failedPlugins = /* @__PURE__ */ new Set();
@@ -2170,14 +2222,10 @@ var FunctionParams = class FunctionParams {
 //#endregion
 //#region src/utils/formatters.ts
 /**
-* Check if a formatter command is available in the system.
+* Returns `true` when the given formatter is installed and callable.
 *
-* @param formatter - The formatter to check ('biome', 'prettier', or 'oxfmt')
-* @returns Promise that resolves to true if the formatter is available, false otherwise
-*
-* @remarks
-* This function checks availability by running `<formatter> --version` command.
-* All supported formatters (biome, prettier, oxfmt) implement the --version flag.
+* Availability is detected by running `<formatter> --version` and checking
+* that the process exits without error.
 */
 async function isFormatterAvailable(formatter) {
 	try {
@@ -2188,22 +2236,16 @@ async function isFormatterAvailable(formatter) {
 	}
 }
 /**
-* Detect which formatter is available in the system.
-*
-* @returns Promise that resolves to the first available formatter or undefined if none are found
+* Detects the first available code formatter on the current system.
 *
-* @remarks
-* Checks in order of preference: biome, oxfmt, prettier.
-* Uses the `--version` flag to detect if each formatter command is available.
-* This is a reliable method as all supported formatters implement this flag.
+* - Checks in preference order: `biome`, `oxfmt`, `prettier`.
+* - Returns `null` when none are found.
 *
 * @example
-* ```typescript
+* ```ts
 * const formatter = await detectFormatter()
 * if (formatter) {
 *   console.log(`Using ${formatter} for formatting`)
-* } else {
-*   console.log('No formatter found')
 * }
 * ```
 */
@@ -2214,9 +2256,19 @@ async function detectFormatter() {
 		"prettier"
 	]);
 	for (const formatter of formatterNames) if (await isFormatterAvailable(formatter)) return formatter;
+	return null;
 }
 //#endregion
 //#region src/utils/TreeNode.ts
+/**
+* Tree structure used to build per-directory barrel (`index.ts`) files from a
+* flat list of generated {@link KubbFile.File} entries.
+*
+* Each node represents either a directory or a file within the output tree.
+* Use {@link TreeNode.build} to construct a root node from a file list, then
+* traverse with {@link TreeNode.forEach}, {@link TreeNode.leaves}, or the
+* `*Deep` helpers.
+*/
 var TreeNode = class TreeNode {
 	data;
 	parent;
@@ -2232,10 +2284,18 @@ var TreeNode = class TreeNode {
 		this.children.push(child);
 		return child;
 	}
+	/**
+	* Returns the root ancestor of this node, walking up via `parent` links.
+	*/
 	get root() {
 		if (!this.parent) return this;
 		return this.parent.root;
 	}
+	/**
+	* Returns all leaf descendants (nodes with no children) of this node.
+	*
+	* Results are cached after the first traversal.
+	*/
 	get leaves() {
 		if (!this.children || this.children.length === 0) return [this];
 		if (this.#cachedLeaves) return this.#cachedLeaves;
@@ -2266,6 +2326,12 @@ var TreeNode = class TreeNode {
 		if (typeof callback !== "function") throw new TypeError("map() callback must be a function");
 		return this.leaves.map(callback);
 	}
+	/**
+	* Builds a {@link TreeNode} tree from a flat list of files.
+	*
+	* - Filters to files under `root` (when provided) and skips `.json` files.
+	* - Returns `null` when no files match.
+	*/
 	static build(files, root) {
 		try {
 			const filteredTree = buildDirectoryTree(files, root);
@@ -2381,6 +2447,14 @@ function trimExtName(text) {
 	if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
 	return text;
 }
+/**
+* Generates `index.ts` barrel files for all directories under `root/output.path`.
+*
+* - Returns an empty array when `type` is falsy or `'propagate'`.
+* - Skips generation when the output path itself ends with `index` (already a barrel).
+* - When `type` is `'all'`, strips named exports so every re-export becomes a wildcard (`export * from`).
+* - Attaches `meta` to each barrel file for downstream plugin identification.
+*/
 async function getBarrelFiles(files, { type, meta = {}, root, output }) {
 	if (!type || type === "propagate") return [];
 	const pathToBuildFrom = (0, node_path.join)(root, output.path);
@@ -2407,7 +2481,11 @@ async function getBarrelFiles(files, { type, meta = {}, root, output }) {
 //#endregion
 //#region src/utils/getConfigs.ts
 /**
-* Converting UserConfig to Config Array without a change in the object beside the JSON convert.
+* Resolves a {@link ConfigInput} into a normalized array of {@link Config} objects.
+*
+* - Awaits the config when it is a `Promise`.
+* - Calls the factory function with `args` when the config is a function.
+* - Wraps a single config object in an array for uniform downstream handling.
 */
 async function getConfigs(config, args) {
 	const resolved = await (typeof config === "function" ? config(args) : config);
@@ -2426,6 +2504,13 @@ function mergeResolvers(...resolvers) {
 }
 //#endregion
 //#region src/utils/getPreset.ts
+/**
+* Resolves a named preset into merged resolvers and transformers.
+*
+* - Merges the preset's resolvers on top of the first (default) resolver to produce `baseResolver`.
+* - Merges any additional user-supplied resolvers on top of that to produce the final `resolver`.
+* - Concatenates preset transformers before user-supplied transformers.
+*/
 function getPreset(params) {
 	const { preset: presetName, presets, resolvers, transformers: userTransformers } = params;
 	const [defaultResolver, ...userResolvers] = resolvers;
@@ -2440,6 +2525,12 @@ function getPreset(params) {
 }
 //#endregion
 //#region src/utils/linters.ts
+/**
+* Returns `true` when the given linter is installed and callable.
+*
+* Availability is detected by running `<linter> --version` and checking
+* that the process exits without error.
+*/
 async function isLinterAvailable(linter) {
 	try {
 		await (0, tinyexec.x)(linter, ["--version"], { nodeOptions: { stdio: "ignore" } });
@@ -2448,6 +2539,20 @@ async function isLinterAvailable(linter) {
 		return false;
 	}
 }
+/**
+* Detects the first available linter on the current system.
+*
+* - Checks in preference order: `biome`, `oxlint`, `eslint`.
+* - Returns `null` when none are found.
+*
+* @example
+* ```ts
+* const linter = await detectLinter()
+* if (linter) {
+*   console.log(`Using ${linter} for linting`)
+* }
+* ```
+*/
 async function detectLinter() {
 	const linterNames = new Set([
 		"biome",
@@ -2455,12 +2560,13 @@ async function detectLinter() {
 		"eslint"
 	]);
 	for (const linter of linterNames) if (await isLinterAvailable(linter)) return linter;
+	return null;
 }
 //#endregion
 //#region src/utils/packageJSON.ts
 function getPackageJSONSync(cwd) {
 	const pkgPath = empathic_package.up({ cwd });
-	if (!pkgPath) return;
+	if (!pkgPath) return null;
 	return JSON.parse(readSync(pkgPath));
 }
 function match(packageJSON, dependency) {
@@ -2470,12 +2576,27 @@ function match(packageJSON, dependency) {
 	};
 	if (typeof dependency === "string" && dependencies[dependency]) return dependencies[dependency];
 	const matched = Object.keys(dependencies).find((dep) => dep.match(dependency));
-	return matched ? dependencies[matched] : void 0;
+	return matched ? dependencies[matched] ?? null : null;
 }
 function getVersionSync(dependency, cwd) {
 	const packageJSON = getPackageJSONSync(cwd);
-	return packageJSON ? match(packageJSON, dependency) : void 0;
+	return packageJSON ? match(packageJSON, dependency) : null;
 }
+/**
+* Returns `true` when the nearest `package.json` declares a dependency that
+* satisfies the given semver range.
+*
+* - Searches both `dependencies` and `devDependencies`.
+* - Accepts a string package name or a `RegExp` to match scoped/pattern packages.
+* - Uses `semver.satisfies` for range comparison; returns `false` when the
+*   version string cannot be coerced into a valid semver.
+*
+* @example
+* ```ts
+* satisfiesDependency('react', '>=18')          // true when react@18.x is installed
+* satisfiesDependency(/^@tanstack\//, '>=5')    // true when any @tanstack/* >=5 is found
+* ```
+*/
 function satisfiesDependency(dependency, version, cwd) {
 	const packageVersion = getVersionSync(dependency, cwd);
 	if (!packageVersion) return false;
@@ -2485,8 +2606,10 @@ function satisfiesDependency(dependency, version, cwd) {
 	return (0, semver.satisfies)(semVer, version);
 }
 //#endregion
+exports.AsyncEventEmitter = AsyncEventEmitter;
 exports.FunctionParams = FunctionParams;
 exports.PluginDriver = PluginDriver;
+exports.URLPath = URLPath;
 exports.build = build;
 exports.createAdapter = createAdapter;
 exports.createPlugin = createPlugin;