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

package/dist/index.js

@@ -1,10 +1,9 @@
 import "./chunk--u3MIqq1.js";
-import { definePrinter, isOperationNode, isSchemaNode } from "@kubb/ast";
-import path, { basename, dirname, extname, join, posix, relative, resolve } from "node:path";
 import { EventEmitter } from "node:events";
-import { parseArgs, styleText } from "node:util";
 import { readFileSync } from "node:fs";
 import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import path, { basename, dirname, extname, join, posix, relative, resolve } from "node:path";
+import { definePrinter, isOperationNode, isSchemaNode } from "@kubb/ast";
 import { Fabric, createFabric, createReactFabric } from "@kubb/react-fabric";
 import { typescriptParser } from "@kubb/react-fabric/parsers";
 import { fsPlugin } from "@kubb/react-fabric/plugins";
@@ -16,12 +15,23 @@ import { jsx } from "@kubb/react-fabric/jsx-runtime";
 import { sortBy } from "remeda";
 import * as pkg from "empathic/package";
 import { coerce, satisfies } from "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;
@@ -33,19 +43,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) {
@@ -53,8 +78,13 @@ var AsyncEventEmitter = class {
 	}
 	#emitter = new 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);
@@ -73,11 +103,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);
@@ -85,15 +129,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)
@@ -150,190 +210,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${styleText("bold", "Usage:")} ${programName}${argsPart}${subCmdPart} [options]\n`);
-	if (schema.description) console.log(`  ${schema.description}\n`);
-	if (schema.subCommands.length) {
-		console.log(styleText("bold", "Commands:"));
-		for (const sub of schema.subCommands) console.log(`  ${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(styleText("bold", "Options:"));
-	for (const opt of options) {
-		const flags = styleText("cyan", opt.flags.padEnd(30));
-		const defaultPart = opt.default !== void 0 ? 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 = 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(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(styleText("red", `Error: ${err instanceof Error ? err.message : String(err)}`));
-		renderHelp(def, parentName);
-		process.exit(1);
-	}
-}
-function printRootHelp(programName, version, defs) {
-	console.log(`\n${styleText("bold", "Usage:")} ${programName} <command> [options]\n`);
-	console.log(`  Kubb generation — v${version}\n`);
-	console.log(styleText("bold", "Commands:"));
-	for (const def of defs) console.log(`  ${styleText("cyan", def.name.padEnd(16))}${def.description}`);
-	console.log();
-	console.log(styleText("bold", "Options:"));
-	console.log(`  ${styleText("cyan", "-v, --version".padEnd(30))}Show version number`);
-	console.log(`  ${styleText("cyan", "-h, --help".padEnd(30))}Show help`);
-	console.log();
-	console.log(`Run ${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);
@@ -341,39 +229,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.
@@ -383,8 +254,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 || ""}`);
@@ -394,35 +271,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 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 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 = 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 readFile(resolved, { encoding: "utf-8" }) === trimmed) return void 0;
+		if (await readFile(resolved, { encoding: "utf-8" }) === trimmed) return null;
 	} catch {}
 	await mkdir(dirname(resolved), { recursive: true });
 	await writeFile(resolved, trimmed, { encoding: "utf-8" });
@@ -433,16 +329,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 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;
@@ -453,10 +365,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
@@ -545,8 +468,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);
@@ -555,6 +484,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 {
@@ -564,6 +500,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.
 *
@@ -573,18 +511,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;
@@ -602,11 +555,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();
 	}
@@ -614,7 +581,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];
@@ -651,6 +620,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 = {};
@@ -660,7 +635,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");
 	}
@@ -678,10 +659,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,
@@ -690,6 +688,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",
@@ -711,6 +716,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",
@@ -910,7 +922,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) => {
@@ -923,7 +939,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);
@@ -934,7 +953,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);
@@ -1441,11 +1463,14 @@ const fsStorage = createStorage(() => ({
 }));
 //#endregion
 //#region package.json
-var version$1 = "5.0.0-alpha.17";
+var version$1 = "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 {
@@ -1458,6 +1483,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();
@@ -1584,6 +1620,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;
@@ -1601,6 +1643,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();
@@ -2164,14 +2216,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 {
@@ -2182,22 +2230,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')
 * }
 * ```
 */
@@ -2208,9 +2250,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;
@@ -2226,10 +2278,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;
@@ -2260,6 +2320,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);
@@ -2375,6 +2441,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 = join(root, output.path);
@@ -2401,7 +2475,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);
@@ -2420,6 +2498,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;
@@ -2434,6 +2519,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 x(linter, ["--version"], { nodeOptions: { stdio: "ignore" } });
@@ -2442,6 +2533,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",
@@ -2449,12 +2554,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 = pkg.up({ cwd });
-	if (!pkgPath) return;
+	if (!pkgPath) return null;
 	return JSON.parse(readSync(pkgPath));
 }
 function match(packageJSON, dependency) {
@@ -2464,12 +2570,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;
@@ -2479,6 +2600,6 @@ function satisfiesDependency(dependency, version, cwd) {
 	return satisfies(semVer, version);
 }
 //#endregion
-export { FunctionParams, PluginDriver, build, build as default, createAdapter, createPlugin, createStorage, defaultResolveOptions, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
+export { AsyncEventEmitter, FunctionParams, PluginDriver, URLPath, build, build as default, createAdapter, createPlugin, createStorage, defaultResolveOptions, defineConfig, defineGenerator, defineLogger, definePreset, definePresets, definePrinter, defineResolver, detectFormatter, detectLinter, formatters, fsStorage, getBarrelFiles, getConfigs, getMode, getPreset, isInputPath, linters, logLevel, memoryStorage, mergeResolvers, renderOperation, renderOperations, renderSchema, safeBuild, satisfiesDependency, setup };
 
 //# sourceMappingURL=index.js.map