@kubb/core 5.0.0-alpha.5 → 5.0.0-alpha.50

package/dist/PluginDriver-mXeqWp-U.js

@@ -0,0 +1,979 @@
+import "./chunk--u3MIqq1.js";
+import path, { extname, resolve } from "node:path";
+import { createFile, isOperationNode, isSchemaNode } from "@kubb/ast";
+import { deflateSync } from "fflate";
+import { x } from "tinyexec";
+//#region ../../internals/utils/src/casing.ts
+/**
+* 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 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, "");
+}
+/**
+* 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.
+*
+* Empty segments are filtered before joining. They arise when the text starts with
+* a dot followed immediately by a letter (e.g. `..Schema` splits into `['..', 'Schema']`
+* and `'..'` transforms to an empty string). Without this filter the join would produce
+* a leading `/`, which `path.resolve` would interpret as an absolute path, allowing
+* generated files to escape the configured output directory.
+*/
+function applyToFileParts(text, transformPart) {
+	const parts = text.split(/\.(?=[a-zA-Z])/);
+	return parts.map((part, i) => transformPart(part, i === parts.length - 1)).filter(Boolean).join("/");
+}
+/**
+* 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 camelCase(text, { isFile, prefix = "", suffix = "" } = {}) {
+	if (isFile) return applyToFileParts(text, (part, isLast) => camelCase(part, isLast ? {
+		prefix,
+		suffix
+	} : {}));
+	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, false);
+}
+/**
+* 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 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);
+}
+//#endregion
+//#region ../../internals/utils/src/string.ts
+/**
+* Strips the file extension from a path or file name.
+* Only removes the last `.ext` segment when the dot is not part of a directory name.
+*
+* @example
+* trimExtName('petStore.ts')             // 'petStore'
+* trimExtName('/src/models/pet.ts')      // '/src/models/pet'
+* trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'
+* trimExtName('noExtension')             // 'noExtension'
+*/
+function trimExtName(text) {
+	const dotIndex = text.lastIndexOf(".");
+	if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
+	return text;
+}
+//#endregion
+//#region src/constants.ts
+/**
+* Base URL for the Kubb Studio web app.
+*/
+const DEFAULT_STUDIO_URL = "https://studio.kubb.dev";
+/**
+* Basename (without extension) of generated barrel files.
+*
+* Used to detect whether a path already points at a barrel so the generator
+* avoids re-creating one on top of it.
+*/
+const BARREL_BASENAME = "index";
+/**
+* File name used for generated barrel (index) files.
+*/
+const BARREL_FILENAME = `${BARREL_BASENAME}.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,
+	warn: 1,
+	info: 3,
+	verbose: 4,
+	debug: 5
+};
+//#endregion
+//#region src/defineResolver.ts
+const stringPatternCache = /* @__PURE__ */ new Map();
+function testPattern(value, pattern) {
+	if (typeof pattern === "string") {
+		let regex = stringPatternCache.get(pattern);
+		if (!regex) {
+			regex = new RegExp(pattern);
+			stringPatternCache.set(pattern, regex);
+		}
+		return regex.test(value);
+	}
+	return value.match(pattern) !== null;
+}
+/**
+* Checks if an operation matches a pattern for a given filter type (`tag`, `operationId`, `path`, `method`).
+*/
+function matchesOperationPattern(node, type, pattern) {
+	switch (type) {
+		case "tag": return node.tags.some((tag) => testPattern(tag, pattern));
+		case "operationId": return testPattern(node.operationId, pattern);
+		case "path": return testPattern(node.path, pattern);
+		case "method": return testPattern(node.method.toLowerCase(), pattern);
+		case "contentType": return node.requestBody?.contentType ? testPattern(node.requestBody.contentType, pattern) : false;
+		default: return false;
+	}
+}
+/**
+* Checks if a schema matches a pattern for a given filter type (`schemaName`).
+*
+* Returns `null` when the filter type doesn't apply to schemas.
+*/
+function matchesSchemaPattern(node, type, pattern) {
+	switch (type) {
+		case "schemaName": return node.name ? testPattern(node.name, pattern) : false;
+		default: return null;
+	}
+}
+/**
+* Default name resolver used by `defineResolver`.
+*
+* - `camelCase` for `function` and `file` types.
+* - `PascalCase` for `type`.
+* - `camelCase` for everything else.
+*/
+function defaultResolver(name, type) {
+	let resolvedName = camelCase(name);
+	if (type === "file" || type === "function") resolvedName = camelCase(name, { isFile: type === "file" });
+	if (type === "type") resolvedName = pascalCase(name);
+	return resolvedName;
+}
+/**
+* Default option resolver — applies include/exclude filters and merges matching override options.
+*
+* Returns `null` when the node is filtered out by an `exclude` rule or not matched by any `include` rule.
+*
+* @example Include/exclude filtering
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { output: 'types' },
+*   exclude: [{ type: 'tag', pattern: 'internal' }],
+* })
+* // → null when node has tag 'internal'
+* ```
+*
+* @example Override merging
+* ```ts
+* const options = defaultResolveOptions(operationNode, {
+*   options: { enumType: 'asConst' },
+*   override: [{ type: 'operationId', pattern: 'listPets', options: { enumType: 'enum' } }],
+* })
+* // → { enumType: 'enum' } when operationId matches
+* ```
+*/
+function defaultResolveOptions(node, { options, exclude = [], include, override = [] }) {
+	if (isOperationNode(node)) {
+		if (exclude.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) return null;
+		if (include && !include.some(({ type, pattern }) => matchesOperationPattern(node, type, pattern))) return null;
+		const overrideOptions = override.find(({ type, pattern }) => matchesOperationPattern(node, type, pattern))?.options;
+		return {
+			...options,
+			...overrideOptions
+		};
+	}
+	if (isSchemaNode(node)) {
+		if (exclude.some(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)) return null;
+		if (include) {
+			const applicable = include.map(({ type, pattern }) => matchesSchemaPattern(node, type, pattern)).filter((r) => r !== null);
+			if (applicable.length > 0 && !applicable.includes(true)) return null;
+		}
+		const overrideOptions = override.find(({ type, pattern }) => matchesSchemaPattern(node, type, pattern) === true)?.options;
+		return {
+			...options,
+			...overrideOptions
+		};
+	}
+	return options;
+}
+/**
+* Default path resolver used by `defineResolver`.
+*
+* - Returns the output directory in `single` mode.
+* - Resolves into a tag- or path-based subdirectory when `group` and a `tag`/`path` value are provided.
+* - Falls back to a flat `output/baseName` path otherwise.
+*
+* A custom `group.name` function overrides the default subdirectory naming.
+* For `tag` groups the default is `${camelCase(tag)}Controller`.
+* For `path` groups the default is the first path segment after `/`.
+*
+* @example Flat output
+* ```ts
+* defaultResolvePath({ baseName: 'petTypes.ts' }, { root: '/src', output: { path: 'types' } })
+* // → '/src/types/petTypes.ts'
+* ```
+*
+* @example Tag-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → '/src/types/petsController/petTypes.ts'
+* ```
+*
+* @example Path-based grouping
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', path: '/pets/list' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'path' } },
+* )
+* // → '/src/types/pets/petTypes.ts'
+* ```
+*
+* @example Single-file mode
+* ```ts
+* defaultResolvePath(
+*   { baseName: 'petTypes.ts', pathMode: 'single' },
+*   { root: '/src', output: { path: 'types' } },
+* )
+* // → '/src/types'
+* ```
+*/
+function defaultResolvePath({ baseName, pathMode, tag, path: groupPath }, { root, output, group }) {
+	if ((pathMode ?? PluginDriver.getMode(path.resolve(root, output.path))) === "single") return path.resolve(root, output.path);
+	let result;
+	if (group && (groupPath || tag)) {
+		const groupValue = group.type === "path" ? groupPath : tag;
+		const defaultName = group.type === "tag" ? ({ group: g }) => `${camelCase(g)}Controller` : ({ group: g }) => {
+			const segment = g.split("/").filter((s) => s !== "" && s !== "." && s !== "..")[0];
+			return segment ? camelCase(segment) : "";
+		};
+		const resolveName = group.name ?? defaultName;
+		result = path.resolve(root, output.path, resolveName({ group: groupValue }), baseName);
+	} else result = path.resolve(root, output.path, baseName);
+	const outputDir = path.resolve(root, output.path);
+	const outputDirWithSep = outputDir.endsWith(path.sep) ? outputDir : `${outputDir}${path.sep}`;
+	if (result !== outputDir && !result.startsWith(outputDirWithSep)) throw new Error(`[Kubb] Resolved path "${result}" is outside the output directory "${outputDir}". This may indicate a path traversal attempt in the OpenAPI specification or a misconfigured group.name function.`);
+	return result;
+}
+/**
+* Default file resolver used by `defineResolver`.
+*
+* Resolves a `FileNode` by combining name resolution (`resolver.default`) with
+* path resolution (`resolver.resolvePath`). The resolved file always has empty
+* `sources`, `imports`, and `exports` arrays — consumers populate those separately.
+*
+* In `single` mode the name is omitted and the file sits directly in the output directory.
+*
+* @example Resolve a schema file
+* ```ts
+* const file = defaultResolveFile.call(resolver,
+*   { name: 'pet', extname: '.ts' },
+*   { root: '/src', output: { path: 'types' } },
+* )
+* // → { baseName: 'pet.ts', path: '/src/types/pet.ts', sources: [], ... }
+* ```
+*
+* @example Resolve an operation file with tag grouping
+* ```ts
+* const file = defaultResolveFile.call(resolver,
+*   { name: 'listPets', extname: '.ts', tag: 'pets' },
+*   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
+* )
+* // → { baseName: 'listPets.ts', path: '/src/types/petsController/listPets.ts', ... }
+* ```
+*/
+function defaultResolveFile({ name, extname, tag, path: groupPath }, context) {
+	const pathMode = PluginDriver.getMode(path.resolve(context.root, context.output.path));
+	const baseName = `${pathMode === "single" ? "" : this.default(name, "file")}${extname}`;
+	const filePath = this.resolvePath({
+		baseName,
+		pathMode,
+		tag,
+		path: groupPath
+	}, context);
+	return createFile({
+		path: filePath,
+		baseName: path.basename(filePath),
+		meta: { pluginName: this.pluginName },
+		sources: [],
+		imports: [],
+		exports: []
+	});
+}
+/**
+* Generates the default "Generated by Kubb" banner from config and optional node metadata.
+*/
+function buildDefaultBanner({ title, description, version, config }) {
+	try {
+		let source = "";
+		if (Array.isArray(config.input)) {
+			const first = config.input[0];
+			if (first && "path" in first) source = path.basename(first.path);
+		} else if ("path" in config.input) source = path.basename(config.input.path);
+		else if ("data" in config.input) source = "text content";
+		let banner = "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n";
+		if (config.output.defaultBanner === "simple") {
+			banner += "*/\n";
+			return banner;
+		}
+		if (source) banner += `* Source: ${source}\n`;
+		if (title) banner += `* Title: ${title}\n`;
+		if (description) {
+			const formattedDescription = description.replace(/\n/gm, "\n* ");
+			banner += `* Description: ${formattedDescription}\n`;
+		}
+		if (version) banner += `* OpenAPI spec version: ${version}\n`;
+		banner += "*/\n";
+		return banner;
+	} catch (_error) {
+		return "/**\n* Generated by Kubb (https://kubb.dev/).\n* Do not edit manually.\n*/";
+	}
+}
+/**
+* Default banner resolver — returns the banner string for a generated file.
+*
+* A user-supplied `output.banner` overrides the default Kubb "Generated by Kubb" notice.
+* When no `output.banner` is set, the Kubb notice is used (including `title` and `version`
+* from the OAS spec when a `node` is provided).
+*
+* - When `output.banner` is a function and `node` is provided, returns `output.banner(node)`.
+* - When `output.banner` is a function and `node` is absent, falls back to the Kubb notice.
+* - When `output.banner` is a string, returns it directly.
+* - When `config.output.defaultBanner` is `false`, returns `undefined`.
+* - Otherwise returns the Kubb "Generated by Kubb" notice.
+*
+* @example String banner overrides default
+* ```ts
+* defaultResolveBanner(undefined, { output: { banner: '// my banner' }, config })
+* // → '// my banner'
+* ```
+*
+* @example Function banner with node
+* ```ts
+* defaultResolveBanner(inputNode, { output: { banner: (node) => `// v${node.version}` }, config })
+* // → '// v3.0.0'
+* ```
+*
+* @example No user banner — Kubb notice with OAS metadata
+* ```ts
+* defaultResolveBanner(inputNode, { config })
+* // → '/** Generated by Kubb ... Title: Pet Store ... *\/'
+* ```
+*
+* @example Disabled default banner
+* ```ts
+* defaultResolveBanner(undefined, { config: { output: { defaultBanner: false }, ...config } })
+* // → undefined
+* ```
+*/
+function defaultResolveBanner(node, { output, config }) {
+	if (typeof output?.banner === "function") return output.banner(node);
+	if (typeof output?.banner === "string") return output.banner;
+	if (config.output.defaultBanner === false) return;
+	return buildDefaultBanner({
+		title: node?.meta?.title,
+		version: node?.meta?.version,
+		config
+	});
+}
+/**
+* Default footer resolver — returns the footer string for a generated file.
+*
+* - When `output.footer` is a function and `node` is provided, calls it with the node.
+* - When `output.footer` is a function and `node` is absent, returns `undefined`.
+* - When `output.footer` is a string, returns it directly.
+* - Otherwise returns `undefined`.
+*
+* @example String footer
+* ```ts
+* defaultResolveFooter(undefined, { output: { footer: '// end of file' }, config })
+* // → '// end of file'
+* ```
+*
+* @example Function footer with node
+* ```ts
+* defaultResolveFooter(inputNode, { output: { footer: (node) => `// ${node.title}` }, config })
+* // → '// Pet Store'
+* ```
+*/
+function defaultResolveFooter(node, { output }) {
+	if (typeof output?.footer === "function") return node ? output.footer(node) : void 0;
+	if (typeof output?.footer === "string") return output.footer;
+}
+/**
+* Defines a resolver for a plugin, injecting built-in defaults for name casing,
+* include/exclude/override filtering, path resolution, and file construction.
+*
+* All four defaults can be overridden by providing them in the builder function:
+* - `default` — name casing strategy (camelCase / PascalCase)
+* - `resolveOptions` — include/exclude/override filtering
+* - `resolvePath` — output path computation
+* - `resolveFile` — full `FileNode` construction
+*
+* Methods in the builder have access to `this` (the full resolver object), so they
+* can call other resolver methods without circular imports.
+*
+* @example Basic resolver with naming helpers
+* ```ts
+* export const resolver = defineResolver<PluginTs>(() => ({
+*   name: 'default',
+*   resolveName(node) {
+*     return this.default(node.name, 'function')
+*   },
+*   resolveTypedName(node) {
+*     return this.default(node.name, 'type')
+*   },
+* }))
+* ```
+*
+* @example Override resolvePath for a custom output structure
+* ```ts
+* export const resolver = defineResolver<PluginTs>(() => ({
+*   name: 'custom',
+*   resolvePath({ baseName }, { root, output }) {
+*     return path.resolve(root, output.path, 'generated', baseName)
+*   },
+* }))
+* ```
+*
+* @example Use this.default inside a helper
+* ```ts
+* export const resolver = defineResolver<PluginTs>(() => ({
+*   name: 'default',
+*   resolveParamName(node, param) {
+*     return this.default(`${node.operationId} ${param.in} ${param.name}`, 'type')
+*   },
+* }))
+* ```
+*/
+function defineResolver(build) {
+	return {
+		default: defaultResolver,
+		resolveOptions: defaultResolveOptions,
+		resolvePath: defaultResolvePath,
+		resolveFile: defaultResolveFile,
+		resolveBanner: defaultResolveBanner,
+		resolveFooter: defaultResolveFooter,
+		...build()
+	};
+}
+//#endregion
+//#region src/devtools.ts
+/**
+* Encodes an `InputNode` as a compressed, URL-safe string.
+*
+* The JSON representation is deflate-compressed with {@link deflateSync} before
+* base64url encoding, which typically reduces payload size by 70–80 % and
+* keeps URLs well within browser and server path-length limits.
+*
+* Use {@link decodeAst} to reverse.
+*/
+function encodeAst(input) {
+	const compressed = deflateSync(new TextEncoder().encode(JSON.stringify(input)));
+	return Buffer.from(compressed).toString("base64url");
+}
+/**
+* Constructs the Kubb Studio URL for the given `InputNode`.
+* When `options.ast` is `true`, navigates to the AST inspector (`/ast`).
+* The `input` is encoded and attached as the `?root=` query parameter so Studio
+* can decode and render it without a round-trip to any server.
+*/
+function getStudioUrl(input, studioUrl, options = {}) {
+	return `${studioUrl.replace(/\/$/, "")}${options.ast ? "/ast" : ""}?root=${encodeAst(input)}`;
+}
+/**
+* Opens the Kubb Studio URL for the given `InputNode` in the default browser —
+*
+* Falls back to printing the URL if the browser cannot be launched.
+*/
+async function openInStudio(input, studioUrl, options = {}) {
+	const url = getStudioUrl(input, studioUrl, options);
+	const cmd = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+	const args = process.platform === "win32" ? [
+		"/c",
+		"start",
+		"",
+		url
+	] : [url];
+	try {
+		await x(cmd, args);
+	} catch {
+		console.log(`\n  ${url}\n`);
+	}
+}
+//#endregion
+//#region src/FileManager.ts
+function mergeFile(a, b) {
+	return {
+		...a,
+		sources: [...a.sources || [], ...b.sources || []],
+		imports: [...a.imports || [], ...b.imports || []],
+		exports: [...a.exports || [], ...b.exports || []]
+	};
+}
+/**
+* In-memory file store for generated files.
+*
+* Files with the same `path` are merged — sources, imports, and exports are concatenated.
+* The `files` getter returns all stored files sorted by path length (shortest first).
+*
+* @example
+* ```ts
+* import { FileManager } from '@kubb/core'
+*
+* const manager = new FileManager()
+* manager.upsert(myFile)
+* console.log(manager.files) // all stored files
+* ```
+*/
+var FileManager = class {
+	#cache = /* @__PURE__ */ new Map();
+	#filesCache = null;
+	/**
+	* Adds one or more files. Files with the same path are merged — sources, imports,
+	* and exports from all calls with the same path are concatenated together.
+	*/
+	add(...files) {
+		const resolvedFiles = [];
+		const mergedFiles = /* @__PURE__ */ new Map();
+		for (const file of files) {
+			const existing = mergedFiles.get(file.path);
+			mergedFiles.set(file.path, existing ? mergeFile(existing, file) : file);
+		}
+		for (const file of mergedFiles.values()) {
+			const resolvedFile = createFile(file);
+			this.#cache.set(resolvedFile.path, resolvedFile);
+			resolvedFiles.push(resolvedFile);
+		}
+		this.#filesCache = null;
+		return resolvedFiles;
+	}
+	/**
+	* Adds or merges one or more files.
+	* If a file with the same path already exists, its sources/imports/exports are merged together.
+	*/
+	upsert(...files) {
+		const resolvedFiles = [];
+		const mergedFiles = /* @__PURE__ */ new Map();
+		for (const file of files) {
+			const existing = mergedFiles.get(file.path);
+			mergedFiles.set(file.path, existing ? mergeFile(existing, file) : file);
+		}
+		for (const file of mergedFiles.values()) {
+			const existing = this.#cache.get(file.path);
+			const resolvedFile = createFile(existing ? mergeFile(existing, file) : file);
+			this.#cache.set(resolvedFile.path, resolvedFile);
+			resolvedFiles.push(resolvedFile);
+		}
+		this.#filesCache = null;
+		return resolvedFiles;
+	}
+	getByPath(path) {
+		return this.#cache.get(path) ?? null;
+	}
+	deleteByPath(path) {
+		this.#cache.delete(path);
+		this.#filesCache = null;
+	}
+	clear() {
+		this.#cache.clear();
+		this.#filesCache = null;
+	}
+	/**
+	* All stored files, sorted by path length (shorter paths first).
+	* Barrel/index files (e.g. index.ts) are sorted last within each length bucket.
+	*/
+	get files() {
+		if (this.#filesCache) return this.#filesCache;
+		const keys = [...this.#cache.keys()];
+		const meta = /* @__PURE__ */ new Map();
+		for (const key of keys) meta.set(key, {
+			length: key.length,
+			isIndex: trimExtName(key).endsWith(BARREL_BASENAME)
+		});
+		keys.sort((a, b) => {
+			const ma = meta.get(a);
+			const mb = meta.get(b);
+			if (ma.length !== mb.length) return ma.length - mb.length;
+			if (ma.isIndex !== mb.isIndex) return ma.isIndex ? 1 : -1;
+			return 0;
+		});
+		const files = [];
+		for (const key of keys) {
+			const file = this.#cache.get(key);
+			if (file) files.push(file);
+		}
+		this.#filesCache = files;
+		return files;
+	}
+};
+//#endregion
+//#region src/renderNode.ts
+/**
+* Handles the return value of a plugin AST hook or generator method.
+*
+* - Renderer output → rendered via the provided `rendererFactory` (e.g. JSX), files stored in `driver.fileManager`
+* - `Array<FileNode>` → added directly into `driver.fileManager`
+* - `void` / `null` / `undefined` → no-op (plugin handled it via `this.upsertFile`)
+*
+* Pass a `rendererFactory` (e.g. `jsxRenderer` from `@kubb/renderer-jsx`) when the result
+* may be a renderer element. Generators that only return `Array<FileNode>` do not need one.
+*/
+async function applyHookResult(result, driver, rendererFactory) {
+	if (!result) return;
+	if (Array.isArray(result)) {
+		driver.fileManager.upsert(...result);
+		return;
+	}
+	if (!rendererFactory) return;
+	const renderer = rendererFactory();
+	await renderer.render(result);
+	driver.fileManager.upsert(...renderer.files);
+	renderer.unmount();
+}
+//#endregion
+//#region src/PluginDriver.ts
+var PluginDriver = class PluginDriver {
+	config;
+	options;
+	/**
+	* Returns `'single'` when `fileOrFolder` has a file extension, `'split'` otherwise.
+	*
+	* @example
+	* ```ts
+	* PluginDriver.getMode('src/gen/types.ts')  // 'single'
+	* PluginDriver.getMode('src/gen/types')     // 'split'
+	* ```
+	*/
+	static getMode(fileOrFolder) {
+		if (!fileOrFolder) return "split";
+		return extname(fileOrFolder) ? "single" : "split";
+	}
+	/**
+	* The universal `@kubb/ast` `InputNode` produced by the adapter, set by
+	* the build pipeline after the adapter's `parse()` resolves.
+	*/
+	inputNode = void 0;
+	adapter = void 0;
+	#studioIsOpen = false;
+	/**
+	* Central file store for all generated files.
+	* Plugins should use `this.addFile()` / `this.upsertFile()` (via their context) to
+	* add files; this property gives direct read/write access when needed.
+	*/
+	fileManager = new FileManager();
+	plugins = /* @__PURE__ */ new Map();
+	/**
+	* Tracks which plugins have generators registered via `addGenerator()` (event-based path).
+	* Used by the build loop to decide whether to emit generator events for a given plugin.
+	*/
+	#pluginsWithEventGenerators = /* @__PURE__ */ new Set();
+	#resolvers = /* @__PURE__ */ new Map();
+	#defaultResolvers = /* @__PURE__ */ new Map();
+	#hookListeners = /* @__PURE__ */ new Map();
+	constructor(config, options) {
+		this.config = config;
+		this.options = options;
+		config.plugins.map((rawPlugin) => this.#normalizePlugin(rawPlugin)).filter((plugin) => {
+			if (typeof plugin.apply === "function") return plugin.apply(config);
+			return true;
+		}).sort((a, b) => {
+			if (b.dependencies?.includes(a.name)) return -1;
+			if (a.dependencies?.includes(b.name)) return 1;
+			return 0;
+		}).forEach((plugin) => {
+			this.plugins.set(plugin.name, plugin);
+		});
+	}
+	get hooks() {
+		return this.options.hooks;
+	}
+	/**
+	* Creates an `NormalizedPlugin` from a hook-style plugin and registers
+	* its lifecycle handlers on the `AsyncEventEmitter`.
+	*/
+	#normalizePlugin(hookPlugin) {
+		const normalizedPlugin = {
+			name: hookPlugin.name,
+			dependencies: hookPlugin.dependencies,
+			options: {
+				output: { path: "." },
+				exclude: [],
+				override: []
+			}
+		};
+		this.registerPluginHooks(hookPlugin, normalizedPlugin);
+		return normalizedPlugin;
+	}
+	/**
+	* Registers a hook-style plugin's lifecycle handlers on the shared `AsyncEventEmitter`.
+	*
+	* For `kubb:plugin:setup`, the registered listener wraps the globally emitted context with a
+	* plugin-specific one so that `addGenerator`, `setResolver`, `setTransformer`, and
+	* `setRenderer` all target the correct `normalizedPlugin` entry in the plugins map.
+	*
+	* All other hooks are iterated and registered directly as pass-through listeners.
+	* Any event key present in the global `KubbHooks` interface can be subscribed to.
+	*
+	* External tooling can subscribe to any of these events via `hooks.on(...)` to observe
+	* the plugin lifecycle without modifying plugin behavior.
+	*
+	* @internal
+	*/
+	registerPluginHooks(hookPlugin, normalizedPlugin) {
+		const { hooks } = hookPlugin;
+		if (hooks["kubb:plugin:setup"]) {
+			const setupHandler = (globalCtx) => {
+				const pluginCtx = {
+					...globalCtx,
+					options: hookPlugin.options ?? {},
+					addGenerator: (gen) => {
+						this.registerGenerator(normalizedPlugin.name, gen);
+					},
+					setResolver: (resolver) => {
+						this.setPluginResolver(normalizedPlugin.name, resolver);
+					},
+					setTransformer: (visitor) => {
+						normalizedPlugin.transformer = visitor;
+					},
+					setRenderer: (renderer) => {
+						normalizedPlugin.renderer = renderer;
+					},
+					setOptions: (opts) => {
+						normalizedPlugin.options = {
+							...normalizedPlugin.options,
+							...opts
+						};
+					},
+					injectFile: ({ sources = [], ...rest }) => {
+						this.fileManager.add(createFile({
+							imports: [],
+							exports: [],
+							sources,
+							...rest
+						}));
+					}
+				};
+				return hooks["kubb:plugin:setup"](pluginCtx);
+			};
+			this.hooks.on("kubb:plugin:setup", setupHandler);
+			this.#trackHookListener("kubb:plugin:setup", setupHandler);
+		}
+		for (const [event, handler] of Object.entries(hooks)) {
+			if (event === "kubb:plugin:setup" || !handler) continue;
+			this.hooks.on(event, handler);
+			this.#trackHookListener(event, handler);
+		}
+	}
+	/**
+	* Emits the `kubb:plugin:setup` event so that all registered hook-style plugin listeners
+	* can configure generators, resolvers, transformers and renderers before `buildStart` runs.
+	*
+	* Call this once from `safeBuild` before the plugin execution loop begins.
+	*/
+	async emitSetupHooks() {
+		const noop = () => {};
+		await this.hooks.emit("kubb:plugin:setup", {
+			config: this.config,
+			options: {},
+			addGenerator: noop,
+			setResolver: noop,
+			setTransformer: noop,
+			setRenderer: noop,
+			setOptions: noop,
+			injectFile: noop,
+			updateConfig: noop
+		});
+	}
+	/**
+	* Registers a generator for the given plugin on the shared event emitter.
+	*
+	* The generator's `schema`, `operation`, and `operations` methods are registered as
+	* listeners on `kubb:generate:schema`, `kubb:generate:operation`, and `kubb:generate:operations`
+	* respectively. Each listener is scoped to the owning plugin via a `ctx.plugin.name` check
+	* so that generators from different plugins do not cross-fire.
+	*
+	* The renderer resolution chain is: `generator.renderer → plugin.renderer → config.renderer`.
+	* Set `generator.renderer = null` to explicitly opt out of rendering even when the plugin
+	* declares a renderer.
+	*
+	* Call this method inside `addGenerator()` (in `kubb:plugin:setup`) to wire up a generator.
+	*/
+	registerGenerator(pluginName, gen) {
+		const resolveRenderer = () => {
+			const plugin = this.plugins.get(pluginName);
+			return gen.renderer === null ? void 0 : gen.renderer ?? plugin?.renderer ?? this.config.renderer;
+		};
+		if (gen.schema) {
+			const schemaHandler = async (node, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				await applyHookResult(await gen.schema(node, ctx), this, resolveRenderer());
+			};
+			this.hooks.on("kubb:generate:schema", schemaHandler);
+			this.#trackHookListener("kubb:generate:schema", schemaHandler);
+		}
+		if (gen.operation) {
+			const operationHandler = async (node, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				await applyHookResult(await gen.operation(node, ctx), this, resolveRenderer());
+			};
+			this.hooks.on("kubb:generate:operation", operationHandler);
+			this.#trackHookListener("kubb:generate:operation", operationHandler);
+		}
+		if (gen.operations) {
+			const operationsHandler = async (nodes, ctx) => {
+				if (ctx.plugin.name !== pluginName) return;
+				await applyHookResult(await gen.operations(nodes, ctx), this, resolveRenderer());
+			};
+			this.hooks.on("kubb:generate:operations", operationsHandler);
+			this.#trackHookListener("kubb:generate:operations", operationsHandler);
+		}
+		this.#pluginsWithEventGenerators.add(pluginName);
+	}
+	/**
+	* Returns `true` when at least one generator was registered for the given plugin
+	* via `addGenerator()` in `kubb:plugin:setup` (event-based path).
+	*
+	* Used by the build loop to decide whether to walk the AST and emit generator events
+	* for a plugin that has no static `plugin.generators`.
+	*/
+	hasRegisteredGenerators(pluginName) {
+		return this.#pluginsWithEventGenerators.has(pluginName);
+	}
+	/**
+	* Unregisters all plugin lifecycle listeners from the shared event emitter.
+	* Called at the end of a build to prevent listener leaks across repeated builds.
+	*
+	* @internal
+	*/
+	dispose() {
+		for (const [event, handlers] of this.#hookListeners) for (const handler of handlers) this.hooks.off(event, handler);
+		this.#hookListeners.clear();
+		this.#pluginsWithEventGenerators.clear();
+	}
+	#trackHookListener(event, handler) {
+		let handlers = this.#hookListeners.get(event);
+		if (!handlers) {
+			handlers = /* @__PURE__ */ new Set();
+			this.#hookListeners.set(event, handlers);
+		}
+		handlers.add(handler);
+	}
+	#createDefaultResolver(pluginName) {
+		const existingResolver = this.#defaultResolvers.get(pluginName);
+		if (existingResolver) return existingResolver;
+		const resolver = defineResolver(() => ({
+			name: "default",
+			pluginName
+		}));
+		this.#defaultResolvers.set(pluginName, resolver);
+		return resolver;
+	}
+	/**
+	* Merges `partial` with the plugin's default resolver and stores the result.
+	* Also mirrors it onto `plugin.resolver` so callers using `getPlugin(name).resolver`
+	* get the up-to-date resolver without going through `getResolver()`.
+	*/
+	setPluginResolver(pluginName, partial) {
+		const merged = {
+			...this.#createDefaultResolver(pluginName),
+			...partial
+		};
+		this.#resolvers.set(pluginName, merged);
+		const plugin = this.plugins.get(pluginName);
+		if (plugin) plugin.resolver = merged;
+	}
+	getResolver(pluginName) {
+		return this.#resolvers.get(pluginName) ?? this.plugins.get(pluginName)?.resolver ?? this.#createDefaultResolver(pluginName);
+	}
+	getContext(plugin) {
+		const driver = this;
+		return {
+			config: driver.config,
+			get root() {
+				return resolve(driver.config.root, driver.config.output.path);
+			},
+			getMode(output) {
+				return PluginDriver.getMode(resolve(driver.config.root, driver.config.output.path, output.path));
+			},
+			hooks: driver.hooks,
+			plugin,
+			getPlugin: driver.getPlugin.bind(driver),
+			requirePlugin: driver.requirePlugin.bind(driver),
+			getResolver: driver.getResolver.bind(driver),
+			driver,
+			addFile: async (...files) => {
+				driver.fileManager.add(...files);
+			},
+			upsertFile: async (...files) => {
+				driver.fileManager.upsert(...files);
+			},
+			get inputNode() {
+				return driver.inputNode;
+			},
+			get adapter() {
+				return driver.adapter;
+			},
+			get resolver() {
+				return driver.getResolver(plugin.name);
+			},
+			get transformer() {
+				return plugin.transformer;
+			},
+			warn(message) {
+				driver.hooks.emit("kubb:warn", message);
+			},
+			error(error) {
+				driver.hooks.emit("kubb:error", typeof error === "string" ? new Error(error) : error);
+			},
+			info(message) {
+				driver.hooks.emit("kubb:info", message);
+			},
+			openInStudio(options) {
+				if (!driver.config.devtools || driver.#studioIsOpen) return;
+				if (typeof driver.config.devtools !== "object") throw new Error("Devtools must be an object");
+				if (!driver.inputNode || !driver.adapter) throw new Error("adapter is not defined, make sure you have set the parser in kubb.config.ts");
+				driver.#studioIsOpen = true;
+				const studioUrl = driver.config.devtools?.studioUrl ?? "https://studio.kubb.dev";
+				return openInStudio(driver.inputNode, studioUrl, options);
+			}
+		};
+	}
+	getPlugin(pluginName) {
+		return this.plugins.get(pluginName);
+	}
+	requirePlugin(pluginName) {
+		const plugin = this.plugins.get(pluginName);
+		if (!plugin) throw new Error(`[kubb] Plugin "${pluginName}" is required but not found. Make sure it is included in your Kubb config.`);
+		return plugin;
+	}
+};
+//#endregion
+export { BARREL_BASENAME as a, DEFAULT_EXTENSION as c, camelCase as d, defineResolver as i, DEFAULT_STUDIO_URL as l, applyHookResult as n, BARREL_FILENAME as o, FileManager as r, DEFAULT_BANNER as s, PluginDriver as t, logLevel as u };
+
+//# sourceMappingURL=PluginDriver-mXeqWp-U.js.map