@kubb/ast 5.0.0-alpha.16 → 5.0.0-alpha.17

package/dist/index.js

@@ -16,6 +16,17 @@ const nodeKinds = {
 	objectBindingParameter: "ObjectBindingParameter",
 	functionParameters: "FunctionParameters"
 };
+/**
+* Canonical schema type strings used by AST schema nodes.
+*
+* These values are used across the AST as stable discriminators
+* (for example `schema.type === schemaTypes.object`).
+*
+* The map is grouped by intent:
+* - primitives (`string`, `number`, `boolean`, ...)
+* - structural/composite (`object`, `array`, `union`, ...)
+* - special OpenAPI-oriented types (`ref`, `datetime`, `uuid`, ...)
+*/
 const schemaTypes = {
 	string: "string",
 	number: "number",
@@ -43,7 +54,7 @@ const schemaTypes = {
 	never: "never"
 };
 /**
-* Scalar primitive schema types used for union member simplification.
+* Primitive scalar schema types used when simplifying union members.
 */
 const SCALAR_PRIMITIVE_TYPES = new Set([
 	"string",
@@ -84,818 +95,945 @@ const mediaTypes = {
 	videoMp4: "video/mp4"
 };
 //#endregion
-//#region src/factory.ts
+//#region ../../internals/utils/dist/index.js
 /**
-* Creates a `RootNode`.
+* Shared implementation for camelCase and PascalCase conversion.
+* Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
+* and capitalizes each word according to `pascal`.
+*
+* When `pascal` is `true` the first word is also capitalized (PascalCase), otherwise only subsequent words are.
 */
-function createRoot(overrides = {}) {
-	return {
-		schemas: [],
-		operations: [],
-		...overrides,
-		kind: "Root"
-	};
+function toCamelOrPascal(text, pascal) {
+	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
+		if (word.length > 1 && word === word.toUpperCase()) return word;
+		if (i === 0 && !pascal) return word.charAt(0).toLowerCase() + word.slice(1);
+		return word.charAt(0).toUpperCase() + word.slice(1);
+	}).join("").replace(/[^a-zA-Z0-9]/g, "");
 }
 /**
-* Creates an `OperationNode`.
+* Splits `text` on `.` and applies `transformPart` to each segment.
+* The last segment receives `isLast = true`, all earlier segments receive `false`.
+* Segments are joined with `/` to form a file path.
+*
+* Only splits on dots followed by a letter so that version numbers
+* embedded in operationIds (e.g. `v2025.0`) are kept intact.
 */
-function createOperation(props) {
-	return {
-		tags: [],
-		parameters: [],
-		responses: [],
-		...props,
-		kind: "Operation"
-	};
-}
-function createSchema(props) {
-	if (props["type"] === "object") return {
-		properties: [],
-		...props,
-		kind: "Schema"
-	};
-	return {
-		...props,
-		kind: "Schema"
-	};
+function applyToFileParts(text, transformPart) {
+	const parts = text.split(/\.(?=[a-zA-Z])/);
+	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).join("/");
 }
 /**
-* Derives `schema.optional` and `schema.nullish` from `required` and `schema.nullable`.
-* This keeps `PropertyNode.required` as the single source of truth for optionality.
+* Converts `text` to camelCase.
+* When `isFile` is `true`, dot-separated segments are each cased independently and joined with `/`.
+*
+* @example
+* camelCase('hello-world')                   // 'helloWorld'
+* camelCase('pet.petId', { isFile: true })   // 'pet/petId'
 */
-function syncPropertySchema(required, schema) {
-	const nullable = schema.nullable ?? false;
-	return {
-		...schema,
-		optional: !required && !nullable ? true : void 0,
-		nullish: !required && nullable ? true : void 0
-	};
+function camelCase(text, { isFile, prefix = "", suffix = "" } = {}) {
+	if (isFile) return applyToFileParts(text, (part, isLast) => camelCase(part, isLast ? {
+		prefix,
+		suffix
+	} : {}));
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
 }
 /**
-* Creates a `PropertyNode`. `required` defaults to `false`.
-* `schema.optional` and `schema.nullish` are auto-derived from `required` and `schema.nullable`.
+* Converts `text` to PascalCase.
+* When `isFile` is `true`, the last dot-separated segment is PascalCased and earlier segments are camelCased.
+*
+* @example
+* pascalCase('hello-world')                  // 'HelloWorld'
+* pascalCase('pet.petId', { isFile: true })  // 'pet/PetId'
 */
-function createProperty(props) {
-	const required = props.required ?? false;
-	return {
-		...props,
-		kind: "Property",
-		required,
-		schema: syncPropertySchema(required, props.schema)
-	};
+function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
+	if (isFile) return applyToFileParts(text, (part, isLast) => isLast ? pascalCase(part, {
+		prefix,
+		suffix
+	}) : camelCase(part));
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
-/**
-* Creates a `ParameterNode`. `required` defaults to `false`.
-* `schema.optional` is auto-derived from `required` and `schema.nullable`.
-*/
-function createParameter(props) {
-	const required = props.required ?? false;
-	return {
-		...props,
-		kind: "Parameter",
-		required,
-		schema: syncPropertySchema(required, props.schema)
-	};
+/** Returns a `CLIAdapter` with type inference. Pass a different adapter to `createCLI` to swap the CLI engine. */
+function defineCLIAdapter(adapter) {
+	return adapter;
 }
 /**
-* Creates a `ResponseNode`.
+* Serializes `CommandDefinition[]` to a plain, JSON-serializable structure.
+* Use to expose CLI capabilities to AI agents or MCP tools.
 */
-function createResponse(props) {
-	return {
-		...props,
-		kind: "Response"
-	};
+function getCommandSchema(defs) {
+	return defs.map(serializeCommand);
 }
-/**
-* Creates a `FunctionParameterNode`. `optional` defaults to `false`.
-*
-* @example Required typed param
-* ```ts
-* createFunctionParameter({ name: 'petId', type: 'string' })
-* // → petId: string
-* ```
-*
-* @example Optional param
-* ```ts
-* createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
-* // → params?: QueryParams
-* ```
-*
-* @example Param with default (implicitly optional — cannot combine with `optional: true`)
-* ```ts
-* createFunctionParameter({ name: 'config', type: 'RequestConfig', default: '{}' })
-* // → config: RequestConfig = {}
-* ```
-*/
-function createFunctionParameter(props) {
+function serializeCommand(def) {
 	return {
-		optional: false,
-		...props,
-		kind: "FunctionParameter"
+		name: def.name,
+		description: def.description,
+		arguments: def.arguments,
+		options: serializeOptions(def.options ?? {}),
+		subCommands: def.subCommands ? def.subCommands.map(serializeCommand) : []
 	};
 }
-/**
-* Creates an `ObjectBindingParameterNode` — an object-destructured parameter group.
-*
-* @example Destructured object param
-* ```ts
-* createObjectBindingParameter({
-*   properties: [
-*     createFunctionParameter({ name: 'id', type: 'string', optional: false }),
-*     createFunctionParameter({ name: 'name', type: 'string', optional: true }),
-*   ],
-*   default: '{}',
-* })
-* // declaration → { id, name? }: { id: string; name?: string } = {}
-* // call        → { id, name }
-* ```
-*
-* @example Inline — children emitted as individual top-level params
-* ```ts
-* createObjectBindingParameter({
-*   properties: [createFunctionParameter({ name: 'petId', type: 'string', optional: false })],
-*   inline: true,
-* })
-* // declaration → petId: string
-* // call        → petId
-* ```
-*/
-function createObjectBindingParameter(props) {
-	return {
-		...props,
-		kind: "ObjectBindingParameter"
-	};
+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 } : {}
+		};
+	});
 }
-/**
-* Creates a `FunctionParametersNode` from an ordered list of params.
-*
-* @example
-* ```ts
-* createFunctionParameters({
-*   params: [
-*     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
-*     createFunctionParameter({ name: 'config', type: 'RequestConfig', optional: false, default: '{}' }),
-*   ],
-* })
-* ```
-*/
-function createFunctionParameters(props = {}) {
-	return {
-		params: [],
-		...props,
-		kind: "FunctionParameters"
+/** 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;
 }
-//#endregion
-//#region src/printer.ts
-/**
-* Creates a named printer factory. Mirrors the `createPlugin` / `createAdapter` pattern
-* from `@kubb/core` — wraps a builder to make options optional and separates raw options
-* from resolved options.
-*
-* The builder receives resolved options and returns:
-* - `name` — a unique identifier for the printer
-* - `options` — options stored on the returned printer instance
-* - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
-* - `print` _(optional)_ — a root-level override that becomes the public `printer.print`.
-*   Inside it, `this.print(node)` still dispatches to the `nodes` map — safe recursion, no infinite loop.
-*
-* When no `print` override is provided, `printer.print` is the node-level dispatcher directly.
-*
-* @example Basic usage — Zod schema printer
-* ```ts
-* type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
-*
-* export const zodPrinter = definePrinter<ZodPrinter>((options) => ({
-*   name: 'zod',
-*   options: { strict: options.strict ?? true },
-*   nodes: {
-*     string: () => 'z.string()',
-*     object(node) {
-*       const props = node.properties.map(p => `${p.name}: ${this.print(p.schema)}`).join(', ')
-*       return `z.object({ ${props} })`
-*     },
-*   },
-* }))
-* ```
-*
-* @example With a root-level `print` override to wrap output in a full declaration
-* ```ts
-* type TsPrinter = PrinterFactoryOptions<'ts', { typeName?: string }, ts.TypeNode, ts.Node>
-*
-* export const printerTs = definePrinter<TsPrinter>((options) => ({
-*   name: 'ts',
-*   options,
-*   nodes: { string: () => factory.keywordTypeNodes.string },
-*   print(node) {
-*     const type = this.print(node) // calls the node-level dispatcher
-*     if (!type || !this.options.typeName) return type
-*     return factory.createTypeAliasDeclaration(this.options.typeName, type)
-*   },
-* }))
-* ```
-*/
-function definePrinter(build) {
-	return createPrinterFactory((node) => node.type)(build);
+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);
+	}
+});
 /**
-* Generic printer factory. Extracts the core dispatch + context logic so it can be reused
-* for any node type — not just `SchemaNode`. `definePrinter` is built on top of this.
-*
-* @param getKey — derives the handler-map key from a node. Return `undefined` to skip.
-*
-* @example
-* ```ts
-* export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
-*   (node) => kindToHandlerKey[node.kind],
-* )
-* ```
+* Parses a CSS hex color string (`#RGB`) into its RGB channels.
+* Falls back to `255` for any channel that cannot be parsed.
 */
-function createPrinterFactory(getKey) {
-	return function(build) {
-		return (options) => {
-			const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? {});
-			const context = {
-				options: resolvedOptions,
-				print: (node) => {
-					const key = getKey(node);
-					if (key === void 0) return void 0;
-					const handler = nodes[key];
-					if (!handler) return void 0;
-					return handler.call(context, node);
-				}
-			};
-			return {
-				name,
-				options: resolvedOptions,
-				print: printOverride ? printOverride.bind(context) : context.print
-			};
-		};
+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");
+/**
+* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+*/
+function isValidVarName(name) {
+	try {
+		new Function(`var ${name}`);
+	} catch {
+		return false;
+	}
+	return true;
+}
 //#endregion
-//#region src/functionPrinter.ts
-const kindToHandlerKey = {
-	FunctionParameter: "functionParameter",
-	ObjectBindingParameter: "objectBindingParameter",
-	FunctionParameters: "functionParameters"
-};
+//#region src/guards.ts
 /**
-* Creates a named function-signature printer factory.
-* Built on `createPrinterFactory` — dispatches on `node.kind` instead of `node.type`.
+* Narrows a `SchemaNode` to the variant that matches `type`.
 *
 * @example
 * ```ts
-* type MyPrinter = PrinterFactoryOptions<'my', { mode: 'declaration' | 'call' }, string>
-*
-* export const myPrinter = defineFunctionPrinter<MyPrinter>((options) => ({
-*   name: 'my',
-*   options,
-*   nodes: {
-*     functionParameter(node) {
-*       return options.mode === 'declaration' && node.type ? `${node.name}: ${node.type}` : node.name
-*     },
-*     objectBindingParameter(node) {
-*       const inner = node.properties.map(p => this.print(p)).filter(Boolean).join(', ')
-*       return `{ ${inner} }`
-*     },
-*     functionParameters(node) {
-*       return node.params.map(p => this.print(p)).filter(Boolean).join(', ')
-*     },
-*   },
-* }))
+* const schema = createSchema({ type: 'string' })
+* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
 * ```
 */
-const defineFunctionPrinter = createPrinterFactory((node) => kindToHandlerKey[node.kind]);
-function rank(param) {
-	if (param.kind === "ObjectBindingParameter") {
-		if (param.default) return 2;
-		return param.optional ?? param.properties.every((p) => p.optional || p.default !== void 0) ? 1 : 0;
-	}
-	if (param.rest) return 3;
-	if (param.default) return 2;
-	return param.optional ? 1 : 0;
-}
-function sortParams(params) {
-	return [...params].sort((a, b) => rank(a) - rank(b));
+function narrowSchema(node, type) {
+	return node?.type === type ? node : void 0;
 }
-function sortChildParams(params) {
-	return [...params].sort((a, b) => rank(a) - rank(b));
+function isKind(kind) {
+	return (node) => node.kind === kind;
 }
 /**
-* Default function-signature printer. Covers the four standard output modes
-* used throughout Kubb plugins.
+* Returns `true` when the input is a `RootNode`.
 *
 * @example
 * ```ts
-* const printer = functionSignaturePrinter({ mode: 'declaration' })
+* if (isRootNode(node)) {
+*   console.log(node.schemas.length)
+* }
+* ```
+*/
+const isRootNode = isKind("Root");
+/**
+* Returns `true` when the input is an `OperationNode`.
 *
-* const sig = createFunctionParameters({
-*   params: [
-*     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
-*     createFunctionParameter({ name: 'config', type: 'Config', optional: false, default: '{}' }),
-*   ],
-* })
+* @example
+* ```ts
+* if (isOperationNode(node)) {
+*   console.log(node.operationId)
+* }
+* ```
+*/
+const isOperationNode = isKind("Operation");
+/**
+* Returns `true` when the input is a `SchemaNode`.
 *
-* printer.print(sig)  // → "petId: string, config: Config = {}"
+* @example
+* ```ts
+* if (isSchemaNode(node)) {
+*   console.log(node.type)
+* }
 * ```
 */
-const functionPrinter = defineFunctionPrinter((options) => ({
-	name: "functionParameters",
-	options,
-	nodes: {
-		functionParameter(node) {
-			const { mode, transformName, transformType } = this.options;
-			const name = transformName ? transformName(node.name) : node.name;
-			const type = node.type && transformType ? transformType(node.type) : node.type;
-			if (mode === "keys" || mode === "values") return node.rest ? `...${name}` : name;
-			if (mode === "call") return node.rest ? `...${name}` : name;
-			if (node.rest) return type ? `...${name}: ${type}` : `...${name}`;
-			if (type) {
-				if (node.optional) return `${name}?: ${type}`;
-				return node.default ? `${name}: ${type} = ${node.default}` : `${name}: ${type}`;
-			}
-			return node.default ? `${name} = ${node.default}` : name;
-		},
-		objectBindingParameter(node) {
-			const { mode, transformName, transformType } = this.options;
-			const sorted = sortChildParams(node.properties);
-			const isOptional = node.optional ?? sorted.every((p) => p.optional || p.default !== void 0);
-			if (node.inline) return sorted.map((p) => this.print(p)).filter(Boolean).join(", ");
-			if (mode === "keys" || mode === "values") return `{ ${sorted.map((p) => p.name).join(", ")} }`;
-			if (mode === "call") return `{ ${sorted.map((p) => p.name).join(", ")} }`;
-			const names = sorted.map((p) => {
-				return transformName ? transformName(p.name) : p.name;
-			});
-			const nameStr = names.length ? `{ ${names.join(", ")} }` : void 0;
-			if (!nameStr) return null;
-			let typeAnnotation = node.type;
-			if (!typeAnnotation) {
-				const typeParts = sorted.filter((p) => p.type).map((p) => {
-					const t = transformType && p.type ? transformType(p.type) : p.type;
-					return p.optional || p.default !== void 0 ? `${p.name}?: ${t}` : `${p.name}: ${t}`;
-				});
-				typeAnnotation = typeParts.length ? `{ ${typeParts.join("; ")} }` : void 0;
-			}
-			if (typeAnnotation) {
-				if (isOptional) return `${nameStr}: ${typeAnnotation} = ${node.default ?? "{}"}`;
-				return node.default ? `${nameStr}: ${typeAnnotation} = ${node.default}` : `${nameStr}: ${typeAnnotation}`;
-			}
-			return node.default ? `${nameStr} = ${node.default}` : nameStr;
-		},
-		functionParameters(node) {
-			return sortParams(node.params).map((p) => this.print(p)).filter(Boolean).join(", ");
-		}
-	}
-}));
-//#endregion
-//#region src/guards.ts
-/**
-* Narrows a `SchemaNode` to the specific variant matching `type`.
-*/
-function narrowSchema(node, type) {
-	return node?.type === type ? node : void 0;
-}
-function isKind(kind) {
-	return (node) => node.kind === kind;
-}
-/**
-* Type guard for `RootNode`.
-*/
-const isRootNode = isKind("Root");
-/**
-* Type guard for `OperationNode`.
-*/
-const isOperationNode = isKind("Operation");
-/**
-* Type guard for `SchemaNode`.
-*/
 const isSchemaNode = isKind("Schema");
 /**
-* Type guard for `PropertyNode`.
+* Returns `true` when the input is a `PropertyNode`.
 */
 const isPropertyNode = isKind("Property");
 /**
-* Type guard for `ParameterNode`.
+* Returns `true` when the input is a `ParameterNode`.
 */
 const isParameterNode = isKind("Parameter");
 /**
-* Type guard for `ResponseNode`.
+* Returns `true` when the input is a `ResponseNode`.
 */
 const isResponseNode = isKind("Response");
 /**
-* Type guard for `FunctionParameterNode`.
+* Returns `true` when the input is a `FunctionParameterNode`.
 */
 const isFunctionParameterNode = isKind("FunctionParameter");
 /**
-* Type guard for `ObjectBindingParameterNode`.
+* Returns `true` when the input is an `ObjectBindingParameterNode`.
 */
 const isObjectBindingParameterNode = isKind("ObjectBindingParameter");
 /**
-* Type guard for `FunctionParametersNode`.
+* Returns `true` when the input is a `FunctionParametersNode`.
 */
 const isFunctionParametersNode = isKind("FunctionParameters");
 //#endregion
-//#region src/refs.ts
-/**
-* Extracts the final segment from a reference string.
-* Falls back to the original string when no slash exists.
-*/
-function extractRefName(ref) {
-	return ref.split("/").at(-1) ?? ref;
-}
+//#region src/utils.ts
+const plainStringTypes = new Set([
+	"string",
+	"uuid",
+	"email",
+	"url",
+	"datetime"
+]);
 /**
-* Indexes named schemas from `root.schemas` by name. Unnamed schemas are skipped.
+* Returns `true` when a schema is emitted as a plain TypeScript `string`.
+*
+* - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
+* - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+*
+* @example
+* ```ts
+* isStringType(createSchema({ type: 'uuid' })) // true
+* isStringType(createSchema({ type: 'date', representation: 'date' })) // false
+* ```
 */
-function buildRefMap(root) {
-	const map = /* @__PURE__ */ new Map();
-	for (const schema of root.schemas) if (schema.name) map.set(schema.name, schema);
-	return map;
+function isStringType(node) {
+	if (plainStringTypes.has(node.type)) return true;
+	const temporal = narrowSchema(node, "date") ?? narrowSchema(node, "time");
+	if (temporal) return temporal.representation !== "date";
+	return false;
 }
 /**
-* Looks up a schema by name. Prefer over `RefMap.get()` to keep the resolution strategy swappable.
+* Applies casing rules to parameter names and returns a new parameter array.
+*
+* The input array is not mutated.
+* If `casing` is not set, the original array is returned unchanged.
+*
+* Use this before passing parameters to schema builders so that property keys
+* in generated output match the desired casing while preserving
+* `OperationNode.parameters` for other consumers.
+*
+* @example
+* ```ts
+* const params = [createParameter({ name: 'pet_id', in: 'query', schema: createSchema({ type: 'string' }) })]
+* const cased = caseParams(params, 'camelcase')
+* // cased[0].name === 'petId'
+* ```
 */
-function resolveRef(refMap, ref) {
-	return refMap.get(ref);
+function caseParams(params, casing) {
+	if (!casing) return params;
+	return params.map((param) => {
+		const transformed = casing === "camelcase" || !isValidVarName(param.name) ? camelCase(param.name) : param.name;
+		return {
+			...param,
+			name: transformed
+		};
+	});
 }
 /**
-* Converts a `RefMap` to a plain object.
+* Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+*
+* - `optional` is set for non-required, non-nullable schemas.
+* - `nullish` is set for non-required, nullable schemas.
 */
-function refMapToObject(refMap) {
-	return Object.fromEntries(refMap);
+function syncOptionality(required, schema) {
+	const nullable = schema.nullable ?? false;
+	return {
+		...schema,
+		optional: !required && !nullable ? true : void 0,
+		nullish: !required && nullable ? true : void 0
+	};
 }
 //#endregion
-//#region src/transforms.ts
+//#region src/factory.ts
 /**
-* Replaces the discriminator property's schema inside an object node with
-* an enum of the provided values.
+* Creates a `RootNode` with stable defaults for `schemas` and `operations`.
+*
+* @example
+* ```ts
+* const root = createRoot()
+* // { kind: 'Root', schemas: [], operations: [] }
+* ```
+*
+* @example
+* ```ts
+* const root = createRoot({ schemas: [petSchema] })
+* // keeps default operations: []
+* ```
 */
-function applyDiscriminatorEnum({ node, propertyName, values, enumName }) {
-	const objectNode = narrowSchema(node, "object");
-	if (!objectNode?.properties?.length) return node;
-	if (!objectNode.properties.some((prop) => prop.name === propertyName)) return node;
-	return createSchema({
-		...objectNode,
-		properties: objectNode.properties.map((prop) => {
-			if (prop.name !== propertyName) return prop;
-			return createProperty({
-				...prop,
-				schema: createSchema({
-					type: "enum",
-					primitive: "string",
-					enumValues: values,
-					name: enumName,
-					readOnly: prop.schema.readOnly,
-					writeOnly: prop.schema.writeOnly
-				})
-			});
-		})
-	});
+function createRoot(overrides = {}) {
+	return {
+		schemas: [],
+		operations: [],
+		...overrides,
+		kind: "Root"
+	};
 }
 /**
-* Merges adjacent anonymous object members into a single anonymous object.
+* Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
+*
+* @example
+* ```ts
+* const operation = createOperation({
+*   operationId: 'getPetById',
+*   method: 'GET',
+*   path: '/pet/{petId}',
+* })
+* // tags, parameters, and responses are []
+* ```
+*
+* @example
+* ```ts
+* const operation = createOperation({
+*   operationId: 'findPets',
+*   method: 'GET',
+*   path: '/pet/findByStatus',
+*   tags: ['pet'],
+* })
+* ```
 */
-function mergeAdjacentAnonymousObjects(members) {
-	return members.reduce((acc, member) => {
-		const objectMember = narrowSchema(member, "object");
-		if (objectMember && !objectMember.name) {
-			const previous = acc.at(-1);
-			const previousObject = previous ? narrowSchema(previous, "object") : void 0;
-			if (previousObject && !previousObject.name) {
-				acc[acc.length - 1] = createSchema({
-					...previousObject,
-					properties: [...previousObject.properties ?? [], ...objectMember.properties ?? []]
-				});
-				return acc;
-			}
-		}
-		acc.push(member);
-		return acc;
-	}, []);
+function createOperation(props) {
+	return {
+		tags: [],
+		parameters: [],
+		responses: [],
+		...props,
+		kind: "Operation"
+	};
 }
-/**
-* Removes enum members subsumed by broader scalar members in the same union.
-*/
-function simplifyUnionMembers(members) {
-	const scalarPrimitives = new Set(members.filter((member) => SCALAR_PRIMITIVE_TYPES.has(member.type)).map((m) => m.type));
-	if (!scalarPrimitives.size) return members;
-	return members.filter((member) => {
-		const enumNode = narrowSchema(member, "enum");
-		if (!enumNode) return true;
-		const primitive = enumNode.primitive;
-		if (!primitive) return true;
-		if (!enumNode.enumType) return true;
-		if (scalarPrimitives.has(primitive)) return false;
-		if ((primitive === "integer" || primitive === "number") && (scalarPrimitives.has("integer") || scalarPrimitives.has("number"))) return false;
-		return true;
-	});
+function createSchema(props) {
+	if (props["type"] === "object") return {
+		properties: [],
+		...props,
+		kind: "Schema"
+	};
+	return {
+		...props,
+		kind: "Schema"
+	};
 }
-//#endregion
-//#region ../../internals/utils/dist/index.js
 /**
-* Shared implementation for camelCase and PascalCase conversion.
-* Splits on common word boundaries (spaces, hyphens, underscores, dots, slashes, colons)
-* and capitalizes each word according to `pascal`.
+* Creates a `PropertyNode`.
 *
-* When `pascal` is `true` the first word is also capitalized (PascalCase), otherwise only subsequent words are.
+* `required` defaults to `false`.
+* `schema.optional` and `schema.nullish` are derived from `required` and `schema.nullable`.
+*
+* @example
+* ```ts
+* const property = createProperty({
+*   name: 'status',
+*   schema: createSchema({ type: 'string' }),
+* })
+* // required=false, schema.optional=true
+* ```
+*
+* @example
+* ```ts
+* const property = createProperty({
+*   name: 'status',
+*   required: true,
+*   schema: createSchema({ type: 'string', nullable: true }),
+* })
+* // required=true, no optional/nullish
+* ```
 */
-function toCamelOrPascal(text, pascal) {
-	return text.trim().replace(/([a-z\d])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/(\d)([a-z])/g, "$1 $2").split(/[\s\-_./\\:]+/).filter(Boolean).map((word, i) => {
-		if (word.length > 1 && word === word.toUpperCase()) return word;
-		if (i === 0 && !pascal) return word.charAt(0).toLowerCase() + word.slice(1);
-		return word.charAt(0).toUpperCase() + word.slice(1);
-	}).join("").replace(/[^a-zA-Z0-9]/g, "");
+function createProperty(props) {
+	const required = props.required ?? false;
+	return {
+		...props,
+		kind: "Property",
+		required,
+		schema: syncOptionality(required, props.schema)
+	};
 }
 /**
-* Splits `text` on `.` and applies `transformPart` to each segment.
-* The last segment receives `isLast = true`, all earlier segments receive `false`.
-* Segments are joined with `/` to form a file path.
+* Creates a `ParameterNode`.
 *
-* Only splits on dots followed by a letter so that version numbers
-* embedded in operationIds (e.g. `v2025.0`) are kept intact.
+* `required` defaults to `false`.
+* Nested schema flags are set from `required` and `schema.nullable`.
+*
+* @example
+* ```ts
+* const param = createParameter({
+*   name: 'petId',
+*   in: 'path',
+*   required: true,
+*   schema: createSchema({ type: 'string' }),
+* })
+* ```
+*
+* @example
+* ```ts
+* const param = createParameter({
+*   name: 'status',
+*   in: 'query',
+*   schema: createSchema({ type: 'string', nullable: true }),
+* })
+* // required=false, schema.nullish=true
+* ```
 */
-function applyToFileParts(text, transformPart) {
-	const parts = text.split(/\.(?=[a-zA-Z])/);
-	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).join("/");
+function createParameter(props) {
+	const required = props.required ?? false;
+	return {
+		...props,
+		kind: "Parameter",
+		required,
+		schema: syncOptionality(required, props.schema)
+	};
 }
 /**
-* Converts `text` to camelCase.
-* When `isFile` is `true`, dot-separated segments are each cased independently and joined with `/`.
+* Creates a `ResponseNode`.
 *
 * @example
-* camelCase('hello-world')                   // 'helloWorld'
-* camelCase('pet.petId', { isFile: true })   // 'pet/petId'
+* ```ts
+* const response = createResponse({
+*   statusCode: '200',
+*   description: 'Success',
+*   schema: createSchema({ type: 'object', properties: [] }),
+* })
+* ```
 */
-function camelCase(text, { isFile, prefix = "", suffix = "" } = {}) {
-	if (isFile) return applyToFileParts(text, (part, isLast) => camelCase(part, isLast ? {
-		prefix,
-		suffix
-	} : {}));
-	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
+function createResponse(props) {
+	return {
+		...props,
+		kind: "Response"
+	};
 }
-/** Returns a `CLIAdapter` with type inference. Pass a different adapter to `createCLI` to swap the CLI engine. */
-function defineCLIAdapter(adapter) {
-	return adapter;
+/**
+* Creates a single-property object schema used as a discriminator literal.
+*
+* @example
+* ```ts
+* createDiscriminantNode({ propertyName: 'type', value: 'dog' })
+* // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
+* ```
+*/
+function createDiscriminantNode({ propertyName, value }) {
+	return createSchema({
+		type: "object",
+		primitive: "object",
+		properties: [createProperty({
+			name: propertyName,
+			schema: createSchema({
+				type: "enum",
+				primitive: "string",
+				enumValues: [value]
+			}),
+			required: true
+		})]
+	});
 }
 /**
-* Serializes `CommandDefinition[]` to a plain, JSON-serializable structure.
-* Use to expose CLI capabilities to AI agents or MCP tools.
+* Creates a `FunctionParameterNode`.
+*
+* `optional` defaults to `false`.
+*
+* @example Required typed param
+* ```ts
+* createFunctionParameter({ name: 'petId', type: 'string' })
+* // → petId: string
+* ```
+*
+* @example Optional param
+* ```ts
+* createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
+* // → params?: QueryParams
+* ```
+*
+* @example Param with default (implicitly optional; cannot combine with `optional: true`)
+* ```ts
+* createFunctionParameter({ name: 'config', type: 'RequestConfig', default: '{}' })
+* // → config: RequestConfig = {}
+* ```
 */
-function getCommandSchema(defs) {
-	return defs.map(serializeCommand);
+function createFunctionParameter(props) {
+	return {
+		optional: false,
+		...props,
+		kind: "FunctionParameter"
+	};
 }
-function serializeCommand(def) {
+/**
+* Creates an `ObjectBindingParameterNode` for object-destructured parameter groups.
+*
+* @example Destructured object param
+* ```ts
+* createObjectBindingParameter({
+*   properties: [
+*     createFunctionParameter({ name: 'id', type: 'string', optional: false }),
+*     createFunctionParameter({ name: 'name', type: 'string', optional: true }),
+*   ],
+*   default: '{}',
+* })
+* // declaration → { id, name? }: { id: string; name?: string } = {}
+* // call        → { id, name }
+* ```
+*
+* @example Inline mode — children emitted as individual top-level parameters
+* ```ts
+* createObjectBindingParameter({
+*   properties: [createFunctionParameter({ name: 'petId', type: 'string', optional: false })],
+*   inline: true,
+* })
+* // declaration → petId: string
+* // call        → petId
+* ```
+*/
+function createObjectBindingParameter(props) {
 	return {
-		name: def.name,
-		description: def.description,
-		arguments: def.arguments,
-		options: serializeOptions(def.options ?? {}),
-		subCommands: def.subCommands ? def.subCommands.map(serializeCommand) : []
+		...props,
+		kind: "ObjectBindingParameter"
 	};
 }
-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 } : {}
-		};
-	});
+/**
+* Creates a `FunctionParametersNode` from an ordered list of parameters.
+*
+* @example
+* ```ts
+* createFunctionParameters({
+*   params: [
+*     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+*     createFunctionParameter({ name: 'config', type: 'RequestConfig', optional: false, default: '{}' }),
+*   ],
+* })
+* ```
+*
+* @example
+* ```ts
+* const empty = createFunctionParameters()
+* // { kind: 'FunctionParameters', params: [] }
+* ```
+*/
+function createFunctionParameters(props = {}) {
+	return {
+		params: [],
+		...props,
+		kind: "FunctionParameters"
+	};
 }
-/** 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();
+//#endregion
+//#region src/printers/printer.ts
+/**
+* Creates a schema printer factory.
+*
+* This function wraps a builder and makes options optional at call sites.
+*
+* The builder receives resolved options and returns:
+* - `name` — a unique identifier for the printer
+* - `options` — options stored on the returned printer instance
+* - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
+* - `print` _(optional)_ — top-level override exposed as `printer.print`
+*   - Inside this function, `this.print(node)` still dispatches to the `nodes` map
+*   - This keeps recursion safe and avoids self-calls
+*
+* When no `print` override is provided, `printer.print` is the node-level dispatcher directly.
+*
+* @example Basic usage — Zod schema printer
+* ```ts
+* type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
+*
+* export const zodPrinter = definePrinter<ZodPrinter>((options) => ({
+*   name: 'zod',
+*   options: { strict: options.strict ?? true },
+*   nodes: {
+*     string: () => 'z.string()',
+*     object(node) {
+*       const props = node.properties.map(p => `${p.name}: ${this.print(p.schema)}`).join(', ')
+*       return `z.object({ ${props} })`
+*     },
+*   },
+* }))
+* ```
+*/
+function definePrinter(build) {
+	return createPrinterFactory((node) => node.type)(build);
 }
-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 } : {}
+/**
+* Generic printer-factory function used by `definePrinter` and `defineFunctionPrinter`.
+**
+* @example
+* ```ts
+* export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
+*   (node) => kindToHandlerKey[node.kind],
+* )
+* ```
+*/
+function createPrinterFactory(getKey) {
+	return function(build) {
+		return (options) => {
+			const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? {});
+			const context = {
+				options: resolvedOptions,
+				print: (node) => {
+					const key = getKey(node);
+					if (key === void 0) return void 0;
+					const handler = nodes[key];
+					if (!handler) return void 0;
+					return handler.call(context, node);
+				}
+			};
+			return {
+				name,
+				options: resolvedOptions,
+				print: printOverride ? printOverride.bind(context) : context.print
+			};
+		};
 	};
-	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);
+//#endregion
+//#region src/printers/functionPrinter.ts
+const kindToHandlerKey = {
+	FunctionParameter: "functionParameter",
+	ObjectBindingParameter: "objectBindingParameter",
+	FunctionParameters: "functionParameters"
+};
+/**
+* Creates a function-parameter printer factory.
+*
+* This wrapper uses `createPrinterFactory` and dispatches handlers by `node.kind`
+* (for function nodes) rather than by `node.type` (for schema nodes).
+*
+* @example
+* ```ts
+* type MyPrinter = PrinterFactoryOptions<'my', { mode: 'declaration' | 'call' }, string>
+*
+* export const myPrinter = defineFunctionPrinter<MyPrinter>((options) => ({
+*   name: 'my',
+*   options,
+*   nodes: {
+*     functionParameter(node) {
+*       return options.mode === 'declaration' && node.type ? `${node.name}: ${node.type}` : node.name
+*     },
+*     objectBindingParameter(node) {
+*       const inner = node.properties.map(p => this.print(p)).filter(Boolean).join(', ')
+*       return `{ ${inner} }`
+*     },
+*     functionParameters(node) {
+*       return node.params.map(p => this.print(p)).filter(Boolean).join(', ')
+*     },
+*   },
+* }))
+* ```
+*/
+const defineFunctionPrinter = createPrinterFactory((node) => kindToHandlerKey[node.kind]);
+function rank(param) {
+	if (param.kind === "ObjectBindingParameter") {
+		if (param.default) return 2;
+		return param.optional ?? param.properties.every((p) => p.optional || p.default !== void 0) ? 1 : 0;
 	}
+	if (param.rest) return 3;
+	if (param.default) return 2;
+	return param.optional ? 1 : 0;
 }
-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`);
+function sortParams(params) {
+	return [...params].sort((a, b) => rank(a) - rank(b));
 }
-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);
+function sortChildParams(params) {
+	return [...params].sort((a, b) => rank(a) - rank(b));
+}
+/**
+* Default function-signature printer.
+* Covers the four standard output modes used across Kubb plugins.
+*
+* @example
+* ```ts
+* const printer = functionPrinter({ mode: 'declaration' })
+*
+* const sig = createFunctionParameters({
+*   params: [
+*     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+*     createFunctionParameter({ name: 'config', type: 'Config', optional: false, default: '{}' }),
+*   ],
+* })
+*
+* printer.print(sig)  // → "petId: string, config: Config = {}"
+* ```
+*/
+const functionPrinter = defineFunctionPrinter((options) => ({
+	name: "functionParameters",
+	options,
+	nodes: {
+		functionParameter(node) {
+			const { mode, transformName, transformType } = this.options;
+			const name = transformName ? transformName(node.name) : node.name;
+			const type = node.type && transformType ? transformType(node.type) : node.type;
+			if (mode === "keys" || mode === "values") return node.rest ? `...${name}` : name;
+			if (mode === "call") return node.rest ? `...${name}` : name;
+			if (node.rest) return type ? `...${name}: ${type}` : `...${name}`;
+			if (type) {
+				if (node.optional) return `${name}?: ${type}`;
+				return node.default ? `${name}: ${type} = ${node.default}` : `${name}: ${type}`;
 			}
-			if (!subDef) {
-				renderHelp(def, parentName);
-				process.exit(subName ? 1 : 0);
+			return node.default ? `${name} = ${node.default}` : name;
+		},
+		objectBindingParameter(node) {
+			const { mode, transformName, transformType } = this.options;
+			const sorted = sortChildParams(node.properties);
+			const isOptional = node.optional ?? sorted.every((p) => p.optional || p.default !== void 0);
+			if (node.inline) return sorted.map((p) => this.print(p)).filter(Boolean).join(", ");
+			if (mode === "keys" || mode === "values") return `{ ${sorted.map((p) => p.name).join(", ")} }`;
+			if (mode === "call") return `{ ${sorted.map((p) => p.name).join(", ")} }`;
+			const names = sorted.map((p) => {
+				return transformName ? transformName(p.name) : p.name;
+			});
+			const nameStr = names.length ? `{ ${names.join(", ")} }` : void 0;
+			if (!nameStr) return null;
+			let typeAnnotation = node.type;
+			if (!typeAnnotation) {
+				const typeParts = sorted.filter((p) => p.type).map((p) => {
+					const t = transformType && p.type ? transformType(p.type) : p.type;
+					return p.optional || p.default !== void 0 ? `${p.name}?: ${t}` : `${p.name}: ${t}`;
+				});
+				typeAnnotation = typeParts.length ? `{ ${typeParts.join("; ")} }` : void 0;
 			}
-			await runCommand(subDef, subRest, `${parentName} ${def.name}`);
-			return;
+			if (typeAnnotation) {
+				if (isOptional) return `${nameStr}: ${typeAnnotation} = ${node.default ?? "{}"}`;
+				return node.default ? `${nameStr}: ${typeAnnotation} = ${node.default}` : `${nameStr}: ${typeAnnotation}`;
+			}
+			return node.default ? `${nameStr} = ${node.default}` : nameStr;
+		},
+		functionParameters(node) {
+			return sortParams(node.params).map((p) => this.print(p)).filter(Boolean).join(", ");
 		}
-		await runCommand(def, commandArgv, parentName);
 	}
-});
-/**
-* 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
-	};
-}
+}));
+//#endregion
+//#region src/refs.ts
 /**
-* Returns a function that wraps a string in a 24-bit ANSI true-color escape sequence
-* for the given hex color.
+* Returns the last path segment of a reference string.
+*
+* Example: `#/components/schemas/Pet` becomes `Pet`.
+*
+* @example
+* ```ts
+* extractRefName('#/components/schemas/Pet') // 'Pet'
+* ```
 */
-function hex(color) {
-	const { r, g, b } = parseHex(color);
-	return (text) => `\x1b[38;2;${r};${g};${b}m${text}\x1b[0m`;
+function extractRefName(ref) {
+	return ref.split("/").at(-1) ?? ref;
 }
-hex("#F55A17"), hex("#F5A217"), hex("#F58517"), hex("#B45309"), hex("#FFFFFF"), hex("#adadc6"), hex("#FDA4AF");
 /**
-* Returns `true` when `name` is a syntactically valid JavaScript variable name.
+* Builds a `RefMap` from `root.schemas` using each schema's `name`.
+*
+* Unnamed schemas are skipped.
+*
+* @example
+* ```ts
+* const refMap = buildRefMap(root)
+* const pet = refMap.get('Pet')
+* ```
 */
-function isValidVarName(name) {
-	try {
-		new Function(`var ${name}`);
-	} catch {
-		return false;
-	}
-	return true;
+function buildRefMap(root) {
+	const map = /* @__PURE__ */ new Map();
+	for (const schema of root.schemas) if (schema.name) map.set(schema.name, schema);
+	return map;
 }
-//#endregion
-//#region src/utils.ts
-const plainStringTypes = new Set([
-	"string",
-	"uuid",
-	"email",
-	"url",
-	"datetime"
-]);
 /**
-* Returns `true` when a schema node will be represented as a plain string in generated code.
+* Resolves a schema by name from a `RefMap`.
 *
-* - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
-* - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+* @example
+* ```ts
+* const petSchema = resolveRef(refMap, 'Pet')
+* ```
 */
-function isPlainStringType(node) {
-	if (plainStringTypes.has(node.type)) return true;
-	const temporal = narrowSchema(node, "date") ?? narrowSchema(node, "time");
-	if (temporal) return temporal.representation !== "date";
-	return false;
+function resolveRef(refMap, ref) {
+	return refMap.get(ref);
 }
 /**
-* Transforms the `name` field of each parameter node according to the given casing strategy.
-*
-* The original `params` array is never mutated — a new array of cloned nodes is returned.
-* When no `casing` is provided the original array is returned as-is.
+* Converts a `RefMap` into a plain object.
 *
-* Use this before passing parameters to schema builders so that property keys
-* in the generated output match the desired casing while the original
-* `OperationNode.parameters` array remains untouched for other consumers.
+* @example
+* ```ts
+* const refsObject = refMapToObject(refMap)
+* ```
 */
-function applyParamsCasing(params, casing) {
-	if (!casing) return params;
-	return params.map((param) => {
-		const transformed = casing === "camelcase" || !isValidVarName(param.name) ? camelCase(param.name) : param.name;
-		return {
-			...param,
-			name: transformed
-		};
-	});
+function refMapToObject(refMap) {
+	return Object.fromEntries(refMap);
 }
 //#endregion
 //#region src/visitor.ts
 /**
-* Creates a concurrency-limiting wrapper. At most `concurrency` promises may be
-* in-flight simultaneously; additional calls are queued and dispatched as slots free.
+* Creates a small async concurrency limiter.
+*
+* At most `concurrency` tasks are in flight at once. Extra tasks are queued.
+*
+* @example
+* ```ts
+* const limit = createLimit(2)
+* await Promise.all([
+*   limit(() => taskA()),
+*   limit(() => taskB()),
+*   limit(() => taskC()),
+* ])
+* // only 2 tasks run at the same time
+* ```
 */
 function createLimit(concurrency) {
 	let active = 0;
@@ -921,8 +1059,15 @@ function createLimit(concurrency) {
 /**
 * Returns the immediate traversable children of `node`.
 *
-* For `Schema` nodes, children (properties, items, members) are only included
-* when `recurse` is `true`; shallow traversal omits them entirely.
+* For `Schema` nodes, children (`properties`, `items`, `members`, and non-boolean
+* `additionalProperties`) are only included
+* when `recurse` is `true`; shallow mode skips them.
+*
+* @example
+* ```ts
+* const children = getChildren(operationNode, true)
+* // returns parameters, requestBody schema (if present), and responses
+* ```
 */
 function getChildren(node, recurse) {
 	switch (node.kind) {
@@ -951,7 +1096,23 @@ function getChildren(node, recurse) {
 }
 /**
 * Depth-first traversal for side effects. Visitor return values are ignored.
-* Sibling nodes at each level are visited concurrently up to `options.concurrency` (default: 30).
+* Sibling nodes at each level are visited concurrently up to `options.concurrency`
+* (default: `WALK_CONCURRENCY`).
+*
+* @example
+* ```ts
+* await walk(root, {
+*   operation(node) {
+*     console.log(node.operationId)
+*   },
+* })
+* ```
+*
+* @example
+* ```ts
+* // Visit only the current node
+* await walk(root, { depth: 'shallow', root: () => {} })
+* ```
 */
 async function walk(node, options) {
 	return _walk(node, options, (options.depth ?? visitorDepths.deep) === visitorDepths.deep, createLimit(options.concurrency ?? 30), void 0);
@@ -1084,8 +1245,18 @@ function transform(node, options) {
 	}
 }
 /**
-* Combines multiple visitors into a single visitor that applies them sequentially (left to right).
-* For each node kind, the output of one visitor becomes the input of the next.
+* Composes multiple visitors into one visitor, applied left to right.
+*
+* For each node kind, output from one visitor is input to the next.
+* If a visitor returns `undefined`, the previous node value is kept.
+*
+* @example
+* ```ts
+* const visitor = composeTransformers(
+*   { operation: (node) => ({ ...node, operationId: `a_${node.operationId}` }) },
+*   { operation: (node) => ({ ...node, operationId: `b_${node.operationId}` }) },
+* )
+* ```
 */
 function composeTransformers(...visitors) {
 	return {
@@ -1110,7 +1281,24 @@ function composeTransformers(...visitors) {
 	};
 }
 /**
-* Depth-first synchronous reduction. Collects non-`undefined` visitor return values into an array.
+* Runs a depth-first synchronous collection pass.
+*
+* Non-`undefined` values returned by visitor callbacks are appended to the result.
+*
+* @example
+* ```ts
+* const ids = collect(root, {
+*   operation(node) {
+*     return node.operationId
+*   },
+* })
+* ```
+*
+* @example
+* ```ts
+* // Collect from only the current node
+* const values = collect(root, { depth: 'shallow', root: () => 'root' })
+* ```
 */
 function collect(node, options) {
 	const { depth, parent, ...visitor } = options;
@@ -1148,6 +1336,165 @@ function collect(node, options) {
 	return results;
 }
 //#endregion
-export { SCALAR_PRIMITIVE_TYPES, applyDiscriminatorEnum, applyParamsCasing, buildRefMap, collect, composeTransformers, createFunctionParameter, createFunctionParameters, createObjectBindingParameter, createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, definePrinter, extractRefName, functionPrinter, httpMethods, isFunctionParameterNode, isFunctionParametersNode, isObjectBindingParameterNode, isOperationNode, isParameterNode, isPlainStringType, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, mediaTypes, mergeAdjacentAnonymousObjects, narrowSchema, nodeKinds, refMapToObject, resolveRef, schemaTypes, simplifyUnionMembers, syncPropertySchema, transform, walk };
+//#region src/resolvers.ts
+function findDiscriminator(mapping, ref) {
+	if (!mapping || !ref) return void 0;
+	return Object.entries(mapping).find(([, value]) => value === ref)?.[0];
+}
+function childName(parentName, propName) {
+	return parentName ? pascalCase([parentName, propName].join(" ")) : void 0;
+}
+function enumPropName(parentName, propName, enumSuffix) {
+	return pascalCase([
+		parentName,
+		propName,
+		enumSuffix
+	].filter(Boolean).join(" "));
+}
+/**
+* Collects import entries for all `ref` schema nodes in `node`.
+*/
+function collectImports({ node, nameMapping, resolve }) {
+	return collect(node, { schema(schemaNode) {
+		const schemaRef = narrowSchema(schemaNode, "ref");
+		if (!schemaRef?.ref) return;
+		const rawName = extractRefName(schemaRef.ref);
+		const result = resolve(nameMapping.get(rawName) ?? rawName);
+		if (!result) return;
+		return result;
+	} });
+}
+//#endregion
+//#region src/transformers.ts
+/**
+* Replaces a discriminator property's schema with a string enum of allowed values.
+*
+* If `node` is not an object schema, or if the property does not exist, the input
+* node is returned as-is.
+*
+* @example
+* ```ts
+* const schema = createSchema({
+*   type: 'object',
+*   properties: [createProperty({ name: 'type', required: true, schema: createSchema({ type: 'string' }) })],
+* })
+* const result = setDiscriminatorEnum({ node: schema, propertyName: 'type', values: ['dog', 'cat'] })
+* ```
+*/
+function setDiscriminatorEnum({ node, propertyName, values, enumName }) {
+	const objectNode = narrowSchema(node, "object");
+	if (!objectNode?.properties?.length) return node;
+	if (!objectNode.properties.some((prop) => prop.name === propertyName)) return node;
+	return createSchema({
+		...objectNode,
+		properties: objectNode.properties.map((prop) => {
+			if (prop.name !== propertyName) return prop;
+			return createProperty({
+				...prop,
+				schema: createSchema({
+					type: "enum",
+					primitive: "string",
+					enumValues: values,
+					name: enumName,
+					readOnly: prop.schema.readOnly,
+					writeOnly: prop.schema.writeOnly
+				})
+			});
+		})
+	});
+}
+/**
+* Merges adjacent anonymous object members into a single anonymous object member.
+*
+* @example
+* ```ts
+* const merged = mergeAdjacentObjects([
+*   createSchema({ type: 'object', properties: [createProperty({ name: 'a', schema: createSchema({ type: 'string' }) })] }),
+*   createSchema({ type: 'object', properties: [createProperty({ name: 'b', schema: createSchema({ type: 'number' }) })] }),
+* ])
+* ```
+*/
+function mergeAdjacentObjects(members) {
+	return members.reduce((acc, member) => {
+		const objectMember = narrowSchema(member, "object");
+		if (objectMember && !objectMember.name) {
+			const previous = acc.at(-1);
+			const previousObject = previous ? narrowSchema(previous, "object") : void 0;
+			if (previousObject && !previousObject.name) {
+				acc[acc.length - 1] = createSchema({
+					...previousObject,
+					properties: [...previousObject.properties ?? [], ...objectMember.properties ?? []]
+				});
+				return acc;
+			}
+		}
+		acc.push(member);
+		return acc;
+	}, []);
+}
+/**
+* Removes enum members that are covered by broader scalar primitives in the same union.
+*
+* @example
+* ```ts
+* const simplified = simplifyUnion([
+*   createSchema({ type: 'enum', primitive: 'string', enumValues: ['active'] }),
+*   createSchema({ type: 'string' }),
+* ])
+* // keeps only string member
+* ```
+*/
+function simplifyUnion(members) {
+	const scalarPrimitives = new Set(members.filter((member) => SCALAR_PRIMITIVE_TYPES.has(member.type)).map((m) => m.type));
+	if (!scalarPrimitives.size) return members;
+	return members.filter((member) => {
+		const enumNode = narrowSchema(member, "enum");
+		if (!enumNode) return true;
+		const primitive = enumNode.primitive;
+		if (!primitive) return true;
+		if ((enumNode.namedEnumValues?.length ?? enumNode.enumValues?.length ?? 0) <= 1) return true;
+		if (scalarPrimitives.has(primitive)) return false;
+		if ((primitive === "integer" || primitive === "number") && (scalarPrimitives.has("integer") || scalarPrimitives.has("number"))) return false;
+		return true;
+	});
+}
+function setEnumName(propNode, parentName, propName, enumSuffix) {
+	const enumNode = narrowSchema(propNode, "enum");
+	if (enumNode?.primitive === "boolean") return {
+		...propNode,
+		name: void 0
+	};
+	if (enumNode) return {
+		...propNode,
+		name: enumPropName(parentName, propName, enumSuffix)
+	};
+	return propNode;
+}
+/**
+* Walks a schema tree and resolves `ref`/`enum` names through callbacks.
+*/
+function resolveNames({ node, nameMapping, resolveName, resolveEnumName }) {
+	return transform(node, { schema(schemaNode) {
+		const schemaRef = narrowSchema(schemaNode, "ref");
+		if (schemaRef && (schemaRef.ref || schemaRef.name)) {
+			const rawRef = schemaRef.ref ?? schemaRef.name;
+			const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef);
+			if (resolved) return {
+				...schemaNode,
+				name: resolved
+			};
+		}
+		const schemaEnum = narrowSchema(schemaNode, "enum");
+		if (schemaEnum?.name) {
+			const resolved = (resolveEnumName ?? resolveName)(schemaEnum.name);
+			if (resolved) return {
+				...schemaNode,
+				name: resolved
+			};
+		}
+	} });
+}
+//#endregion
+export { SCALAR_PRIMITIVE_TYPES, buildRefMap, caseParams, childName, collect, collectImports, composeTransformers, createDiscriminantNode, createFunctionParameter, createFunctionParameters, createObjectBindingParameter, createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, defineFunctionPrinter, definePrinter, enumPropName, extractRefName, findDiscriminator, functionPrinter, httpMethods, isFunctionParameterNode, isFunctionParametersNode, isObjectBindingParameterNode, isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, refMapToObject, resolveNames, resolveRef, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, transform, walk };
 
 //# sourceMappingURL=index.js.map