@kubb/core 5.0.0-beta.87 → 5.0.0-beta.89

package/dist/{Diagnostics-aWJg-H2d.d.ts → Diagnostics-CM0-Ae30.d.ts}

@@ -496,23 +496,14 @@ type ResolverDefault = {
    */
   name(name: string): string;
   options<TOptions>(node: Node, context: ResolveOptionsContext<TOptions>): TOptions | null;
-  path(params: ResolverPathParams, context: ResolverContext): string;
-  file(params: ResolverFileParams, context: ResolverContext): FileNode;
+  path(options: ResolvePathOptions): string;
+  file(options: ResolveFileOptions): FileNode;
   banner(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
   footer(meta: InputMeta | undefined, context: ResolveBannerContext): string | null;
 };
 /**
- * File-specific parameters for `resolver.default.path`.
- * Provide `tag` for tag-based grouping or `path` for path-based grouping.
- *
- * @example
- * ```ts
- * resolver.default.path(
- *   { baseName: 'petTypes.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → '/src/types/pets/petTypes.ts'
- * ```
+ * The name request for `resolver.default.path`: a `baseName` plus the optional `tag`/`path` that
+ * grouping keys off.
  */
 type ResolverPathParams = {
   baseName: FileNode['baseName'];
@@ -526,27 +517,32 @@ type ResolverPathParams = {
   path?: string;
 };
 /**
- * Shared context passed as the second argument to `resolver.default.path` and
- * `resolver.default.file`: where output is rooted, which output config is active,
- * and the optional grouping strategy.
+ * Options for `resolver.default.path`: the name request (`baseName`, `tag`, `path`) plus where the
+ * output goes (`root`, `output`, `group`).
+ *
+ * @example
+ * ```ts
+ * resolver.default.path({ baseName: 'petTypes.ts', tag: 'pets', root: '/src', output: { path: 'types' }, group: { type: 'tag' } })
+ * // → '/src/types/pets/petTypes.ts'
+ * ```
  */
-type ResolverContext = {
+type ResolvePathOptions = ResolverPathParams & {
+  /**
+   * Absolute project root that the output path is resolved against.
+   */
   root: string;
+  /**
+   * Active output config; `output.path` is the base directory.
+   */
   output: Output;
+  /**
+   * Optional grouping strategy applied to `tag` (tag grouping) or `path` (path grouping).
+   */
   group?: Group;
 };
 /**
- * File-specific parameters for `resolver.default.file`.
- * `tag` and `path` are used only when a matching `group` is present in the context.
- *
- * @example
- * ```ts
- * resolver.default.file(
- *   { name: 'listPets', extname: '.ts', tag: 'pets' },
- *   { root: '/src', output: { path: 'types' }, group: { type: 'tag' } },
- * )
- * // → { baseName: 'listPets.ts', path: '/src/types/pets/listPets.ts', ... }
- * ```
+ * The file request for `resolver.file` and `resolver.default.file`: the `name` and `extname` plus
+ * the optional `tag`/`path` that grouping keys off.
  */
 type ResolverFileParams = {
   name: string;
@@ -559,13 +555,68 @@ type ResolverFileParams = {
    * Path value used when `group.type === 'path'`.
    */
   path?: string;
+};
+/**
+ * Options for `resolver.file` and `resolver.default.file`: the file request (`name`, `extname`,
+ * `tag`, `path`) plus where the output goes (`root`, `output`, `group`).
+ *
+ * @example
+ * ```ts
+ * resolver.default.file({ name: 'listPets', extname: '.ts', tag: 'pets', root: '/src', output: { path: 'types' }, group: { type: 'tag' } })
+ * // → { baseName: 'listPets.ts', path: '/src/types/pets/listPets.ts', ... }
+ * ```
+ */
+type ResolveFileOptions = ResolverFileParams & {
+  root: string;
+  output: Output;
+  group?: Group;
+};
+/**
+ * The `file` field of a resolver: decides what a generated file is called and, optionally, where
+ * it lives. This is how a resolver renames or relocates its files, replacing the older per-call
+ * `resolveName` hook.
+ *
+ * @example Suffix every generated file
+ * ```ts
+ * file: {
+ *   baseName({ name, extname }) {
+ *     return `${name}Faker${extname}`
+ *   },
+ * }
+ * ```
+ *
+ * @example Own the full path
+ * ```ts
+ * file: {
+ *   path({ baseName, output }) {
+ *     return `${output.path}/mocks/${baseName}`
+ *   },
+ * }
+ * ```
+ */
+type ResolverFile = {
   /**
-   * Casing applied to `name` to build the file base name. A plugin's `file` override
-   * threads its own caser here to change file naming without reimplementing the builder.
-   *
-   * @default toFilePath
+   * Builds the file's complete base name, extension included, from the identifier and the target
+   * `extname`. Defaults to `toFilePath(name)` with `extname` appended. Reaches sibling resolver
+   * helpers through `this`.
    */
-  resolveName?: (name: string) => string;
+  baseName?(params: Pick<ResolverFileParams, 'name' | 'extname'>): FileNode['baseName'];
+  /**
+   * Returns the file's complete path, resolved against the project `root`. Bypasses `output.path`
+   * and `group`, so the resolver owns the layout. The returned path may not escape `root`. Reaches
+   * sibling resolver helpers through `this`.
+   */
+  path?(params: ResolverFilePathParams): string;
+};
+/**
+ * The argument to a resolver's `file.path`: the resolved `baseName` (what `file.baseName` produced,
+ * with the extension already appended) and the active `output`. `tag`, `path`, and `group` are
+ * omitted because `file.path` owns the whole path and bypasses grouping, and `root` because the
+ * returned path is resolved against it.
+ */
+type ResolverFilePathParams = {
+  baseName: FileNode['baseName'];
+  output: Output;
 };
 /**
  * Per-file context describing the file a banner/footer is being resolved for, so a
@@ -631,18 +682,27 @@ type ResolveBannerContext = {
 type ResolverBuildOptions = {
   pluginName: string;
   name?: (name: string) => string;
-  file?: (params: ResolverFileParams, context: ResolverContext) => FileNode;
+  file?: ResolverFile;
   [key: string]: unknown;
 };
 /**
  * Partial resolver fields accepted by `Resolver.merge` and `setResolver`. Parameterize with a
- * concrete resolver type (e.g. `ResolverPatch<ResolverTs>`) to type-check namespace overrides
- * and bind `this` to the full resolver. The bare form accepts any resolver's fields.
+ * concrete resolver type (e.g. `ResolverPatch<ResolverTs>`) to type-check overrides and bind
+ * `this` to the full resolver. Namespaces are partial, so a patch may override a single method
+ * (`query.name`) and the rest keep the plugin defaults. Overriding a whole resolver is not the
+ * job of this patch, that is what a custom plugin is for.
  */
-type ResolverPatch<T extends Resolver = Resolver> = Partial<Omit<T, keyof Resolver>> & {
+type ResolverPatch<T extends Resolver = Resolver> = { [K in keyof Omit<T, keyof Resolver>]?: T[K] extends ((...args: Array<never>) => unknown) ? T[K] : Partial<T[K]> } & {
   name?: T['name'];
-  file?: T['file'];
+  file?: ResolverFile;
 } & ThisType<T>;
+/**
+ * Shared brand for reaching a resolver's build options. `Resolver.merge` reads this instead of
+ * relying on `instanceof`, which fails when a CommonJS config and the ESM CLI each load their own
+ * copy of `@kubb/core`. `Symbol.for` resolves to one key across those copies, so the options stay
+ * reachable and a `file` override is never dropped.
+ */
+declare const resolverOptions: unique symbol;
 /**
  * Base constraint for all plugin resolver objects.
  *
@@ -671,16 +731,21 @@ declare class Resolver {
   #private;
   readonly pluginName: string;
   constructor(options: ResolverBuildOptions);
+  /** Exposes the raw build options so `Resolver.merge` can read them across `@kubb/core` copies. */
+  get [resolverOptions](): ResolverBuildOptions;
   /**
    * The built-in resolution machinery. Always reaches the untouched defaults, even when a
    * plugin overrides the top-level `name` or `file`.
    */
   get default(): ResolverDefault;
   name(name: string): string;
-  file(params: ResolverFileParams, context: ResolverContext): FileNode;
+  file(options: ResolveFileOptions): FileNode;
   /**
-   * Merges `override` over `base` and returns a new resolver with helpers re-bound.
-   * Each key is replaced wholesale. Used when applying `setResolver` partial overrides.
+   * Merges `override` over `base` and returns a new resolver with helpers re-bound. Top-level
+   * keys replace, and a namespace (or `file`) merges per method, so overriding `query.name`
+   * keeps the base `query.keyName`. Used when applying `setResolver` partial overrides. Reads a
+   * resolver's options through the shared brand rather than `instanceof`, so a `file` override
+   * survives even when `base` and `override` come from different `@kubb/core` copies.
    */
   static merge<T extends Resolver>(base: T, override: ResolverPatch<T> | Resolver): T;
 }
@@ -1377,11 +1442,7 @@ declare class KubbDriver {
    * the failure as a {@link Diagnostic} instead of propagating. Each plugin also
    * contributes a `timing` diagnostic for the run summary.
    */
-  run({
-    storage
-  }: {
-    storage: Storage;
-  }): Promise<{
+  run(): Promise<{
     diagnostics: Array<Diagnostic>;
   }>;
   /**
@@ -1499,7 +1560,7 @@ type GeneratorContext<TOptions extends PluginFactoryOptions = PluginFactoryOptio
    * `ctx.resolver.name('pet') // 'pet'`
    *
    * @example Resolve an output file
-   * `ctx.resolver.file({ name: 'pet', extname: '.ts' }, { root, output })`
+   * `ctx.resolver.file({ name: 'pet', extname: '.ts', root, output })`
    */
   resolver: TOptions['resolver'];
   /**
@@ -2789,5 +2850,5 @@ declare class Diagnostics {
   static formatLines(diagnostic: Diagnostic): Array<string>;
 }
 //#endregion
-export { Include as $, KubbHookStartContext as A, UserReporter as At, Kubb$1 as B, KubbFilesProcessingEndContext as C, createRenderer as Ct, KubbGenerationStartContext as D, Reporter as Dt, KubbGenerationEndContext as E, GenerationResult as Et, KubbSuccessContext as F, AdapterSource as Ft, KubbDriver as G, Generator as H, KubbWarnContext as I, createAdapter as It, Parser as J, FileManagerHooks as K, PossibleConfig as L, KubbInfoContext as M, logLevel as Mt, KubbLifecycleStartContext as N, Adapter as Nt, KubbHookEndContext as O, ReporterContext as Ot, KubbPluginsEndContext as P, AdapterFactoryOptions as Pt, Group as Q, UserConfig as R, KubbFileProcessingUpdate as S, RendererFactory as St, KubbFilesProcessingUpdateContext as T, createStorage as Tt, GeneratorContext as U, createKubb as V, defineGenerator as W, Exclude$1 as X, defineParser as Y, Filter as Z, InputPath as _, ResolverDefault as _t, DiagnosticLocation as a, OutputMode as at, KubbDiagnosticContext as b, ResolverPathParams as bt, PerformanceDiagnostic as c, Plugin as ct, SerializedDiagnostic as d, BannerMeta as dt, KubbPluginEndContext as et, UpdateDiagnostic as f, ResolveBannerContext as ft, InputData as g, ResolverContext as gt, Config as h, Resolver as ht, DiagnosticKind as i, Output as it, KubbHooks as j, createReporter as jt, KubbHookLineContext as k, ReporterName as kt, ProblemCode as l, PluginFactoryOptions as lt, CLIOptions as m, ResolveOptionsContext as mt, DiagnosticByCode as n, KubbPluginStartContext as nt, DiagnosticSeverity as o, OutputOptions as ot, BuildOutput as p, ResolveBannerFile as pt, Hookable as q, DiagnosticDoc as r, NormalizedPlugin as rt, Diagnostics as s, Override as st, Diagnostic as t, KubbPluginSetupContext as tt, ProblemDiagnostic as u, definePlugin as ut, KubbBuildEndContext as v, ResolverFileParams as vt, KubbFilesProcessingStartContext as w, Storage as wt, KubbErrorContext as x, Renderer as xt, KubbBuildStartContext as y, ResolverPatch as yt, CreateKubbOptions as z };
-//# sourceMappingURL=Diagnostics-aWJg-H2d.d.ts.map
+export { Include as $, KubbHookStartContext as A, Reporter as At, Kubb$1 as B, KubbFilesProcessingEndContext as C, ResolverPathParams as Ct, KubbGenerationStartContext as D, Storage as Dt, KubbGenerationEndContext as E, createRenderer as Et, KubbSuccessContext as F, logLevel as Ft, KubbDriver as G, Generator as H, KubbWarnContext as I, Adapter as It, Parser as J, FileManagerHooks as K, PossibleConfig as L, AdapterFactoryOptions as Lt, KubbInfoContext as M, ReporterName as Mt, KubbLifecycleStartContext as N, UserReporter as Nt, KubbHookEndContext as O, createStorage as Ot, KubbPluginsEndContext as P, createReporter as Pt, Group as Q, UserConfig as R, AdapterSource as Rt, KubbFileProcessingUpdate as S, ResolverPatch as St, KubbFilesProcessingUpdateContext as T, RendererFactory as Tt, GeneratorContext as U, createKubb as V, defineGenerator as W, Exclude$1 as X, defineParser as Y, Filter as Z, InputPath as _, Resolver as _t, DiagnosticLocation as a, OutputMode as at, KubbDiagnosticContext as b, ResolverFileParams as bt, PerformanceDiagnostic as c, Plugin as ct, SerializedDiagnostic as d, BannerMeta as dt, KubbPluginEndContext as et, UpdateDiagnostic as f, ResolveBannerContext as ft, InputData as g, ResolvePathOptions as gt, Config as h, ResolveOptionsContext as ht, DiagnosticKind as i, Output as it, KubbHooks as j, ReporterContext as jt, KubbHookLineContext as k, GenerationResult as kt, ProblemCode as l, PluginFactoryOptions as lt, CLIOptions as m, ResolveFileOptions as mt, DiagnosticByCode as n, KubbPluginStartContext as nt, DiagnosticSeverity as o, OutputOptions as ot, BuildOutput as p, ResolveBannerFile as pt, Hookable as q, DiagnosticDoc as r, NormalizedPlugin as rt, Diagnostics as s, Override as st, Diagnostic as t, KubbPluginSetupContext as tt, ProblemDiagnostic as u, definePlugin as ut, KubbBuildEndContext as v, ResolverDefault as vt, KubbFilesProcessingStartContext as w, Renderer as wt, KubbErrorContext as x, ResolverFilePathParams as xt, KubbBuildStartContext as y, ResolverFile as yt, CreateKubbOptions as z, createAdapter as zt };
+//# sourceMappingURL=Diagnostics-CM0-Ae30.d.ts.map

package/dist/index.cjs

@@ -172,7 +172,7 @@ function memoize(store, factory) {
 }
 //#endregion
 //#region package.json
-var version = "5.0.0-beta.87";
+var version = "5.0.0-beta.89";
 //#endregion
 //#region src/constants.ts
 /**
@@ -747,6 +747,19 @@ function isNamespace(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
+* Shared brand for reaching a resolver's build options. `Resolver.merge` reads this instead of
+* relying on `instanceof`, which fails when a CommonJS config and the ESM CLI each load their own
+* copy of `@kubb/core`. `Symbol.for` resolves to one key across those copies, so the options stay
+* reachable and a `file` override is never dropped.
+*/
+const resolverOptions = Symbol.for("@kubb/core/resolver/options");
+/**
+* Built-in `file.baseName`: casts the identifier with `toFilePath` and appends the extension.
+*/
+function toBaseName({ name, extname }) {
+	return `${require_usingCtx.toFilePath(name)}${extname}`;
+}
+/**
 * Base constraint for all plugin resolver objects.
 *
 * The built-in machinery lives under `default`. Generators call the top-level `name` and
@@ -775,11 +788,19 @@ var Resolver = class Resolver {
 	static #optionsCache = /* @__PURE__ */ new WeakMap();
 	pluginName;
 	#options;
+	#baseName;
+	#filePath;
 	constructor(options) {
 		this.pluginName = options.pluginName;
 		this.#options = options;
+		this.#baseName = options.file?.baseName ? options.file.baseName.bind(this) : toBaseName;
+		this.#filePath = options.file?.path ? options.file.path.bind(this) : void 0;
 		this.#apply(options);
 	}
+	/** Exposes the raw build options so `Resolver.merge` can read them across `@kubb/core` copies. */
+	get [resolverOptions]() {
+		return this.#options;
+	}
 	/**
 	* The built-in resolution machinery. Always reaches the untouched defaults, even when a
 	* plugin overrides the top-level `name` or `file`.
@@ -797,19 +818,28 @@ var Resolver = class Resolver {
 	name(name) {
 		return this.default.name(name);
 	}
-	file(params, context) {
-		return this.default.file(params, context);
+	file(options) {
+		return this.#resolveFile(options);
 	}
 	/**
-	* Merges `override` over `base` and returns a new resolver with helpers re-bound.
-	* Each key is replaced wholesale. Used when applying `setResolver` partial overrides.
+	* Merges `override` over `base` and returns a new resolver with helpers re-bound. Top-level
+	* keys replace, and a namespace (or `file`) merges per method, so overriding `query.name`
+	* keeps the base `query.keyName`. Used when applying `setResolver` partial overrides. Reads a
+	* resolver's options through the shared brand rather than `instanceof`, so a `file` override
+	* survives even when `base` and `override` come from different `@kubb/core` copies.
 	*/
 	static merge(base, override) {
-		const patch = override instanceof Resolver ? override.#options : override;
-		return new Resolver({
-			...base.#options,
-			...patch
-		});
+		const patch = resolverOptions in override ? override[resolverOptions] : override;
+		const merged = { ...base[resolverOptions] };
+		for (const [key, value] of Object.entries(patch)) {
+			if (value === void 0) continue;
+			const current = merged[key];
+			merged[key] = isNamespace(value) && isNamespace(current) ? {
+				...current,
+				...value
+			} : value;
+		}
+		return new Resolver(merged);
 	}
 	/**
 	* Binds each entry of `options` onto the resolver, so `this.name`, `this.default`, and
@@ -820,7 +850,7 @@ var Resolver = class Resolver {
 		const root = this;
 		const bind = (value) => typeof value === "function" ? value.bind(root) : value;
 		for (const [key, value] of Object.entries(options)) {
-			if (key === "pluginName" || key === "default" || value === void 0) continue;
+			if (key === "pluginName" || key === "default" || key === "file" || value === void 0) continue;
 			root[key] = isNamespace(value) ? Object.fromEntries(Object.entries(value).map(([method, member]) => [method, bind(member)])) : bind(value);
 		}
 	}
@@ -905,7 +935,7 @@ var Resolver = class Resolver {
 	* to `output.path/{baseName}`, or into a subdirectory when `group` and a `tag`/`path` value
 	* are provided.
 	*/
-	#resolvePath({ baseName, tag, path: groupPath }, { root, output, group }) {
+	#resolvePath({ baseName, tag, path: groupPath, root, output, group }) {
 		if (output.mode === "file") return node_path.default.resolve(root, output.path);
 		const outputDir = node_path.default.resolve(root, output.path);
 		const result = group && (groupPath || tag) ? node_path.default.resolve(outputDir, Resolver.#resolveGroupDir(group, group.type === "path" ? groupPath : tag), baseName) : node_path.default.resolve(outputDir, baseName);
@@ -920,17 +950,45 @@ var Resolver = class Resolver {
 		return result;
 	}
 	/**
-	* Builds a `FileNode` by combining file-name casing (`params.resolveName`) with path
-	* resolution. The resolved file starts with empty `sources`, `imports`, and `exports`,
-	* which consumers populate separately.
+	* Resolves a resolver-supplied full path (`file.path`) against `root`, bypassing `output.path`
+	* and `group`. The path may not escape `root`, which keeps a `file.path` that interpolates
+	* spec-derived values from writing outside the project.
+	*/
+	#resolveOverridePath(filePath, root) {
+		const resolved = node_path.default.resolve(root, filePath);
+		const rootWithSep = root.endsWith(node_path.default.sep) ? root : `${root}${node_path.default.sep}`;
+		if (resolved !== root && !resolved.startsWith(rootWithSep)) throw new Diagnostics.Error({
+			code: Diagnostics.code.pathTraversal,
+			severity: "error",
+			message: `Resolved path "${resolved}" is outside the project root "${root}".`,
+			help: "A resolver `file.path` must return a path inside the project root.",
+			location: { kind: "config" }
+		});
+		return resolved;
+	}
+	/**
+	* Builds a `FileNode`. When `#filePath` (the resolver's `file.path`) is set it owns the whole
+	* path; otherwise the base name (from `#baseName`, the resolver's `file.baseName` or the
+	* built-in `toBaseName`) is placed by the `output.path`/`group` layout. The resolved file starts
+	* with empty `sources`, `imports`, and `exports`, which consumers populate separately.
 	*/
-	#resolveFile({ name, extname, tag, path: groupPath, resolveName = require_usingCtx.toFilePath }, context) {
-		const resolvedName = context.output.mode === "file" ? "" : resolveName(name);
-		const filePath = this.#resolvePath({
-			baseName: `${resolvedName}${extname}`,
+	#resolveFile(options) {
+		const { name, extname, tag, path: groupPath, root, output, group } = options;
+		const baseName = this.#baseName({
+			name,
+			extname
+		});
+		const filePath = this.#filePath ? this.#resolveOverridePath(this.#filePath({
+			baseName,
+			output
+		}), root) : this.#resolvePath({
+			baseName,
 			tag,
-			path: groupPath
-		}, context);
+			path: groupPath,
+			root,
+			output,
+			group
+		});
 		return _kubb_ast.ast.factory.createFile({
 			path: filePath,
 			baseName: node_path.default.basename(filePath),
@@ -1007,15 +1065,39 @@ var Resolver = class Resolver {
 * (`query`, `schema`, …). Every method reaches sibling helpers and the built-in machinery
 * through `this.name`, `this.file`, and `this.default`.
 *
-* @example Custom identifier and file casing
+* @example Custom identifier casing
 * ```ts
 * export const resolverTs = createResolver<PluginTs>({
 *   pluginName: 'plugin-ts',
 *   name(name) {
 *     return ensureValidVarName(pascalCase(name))
 *   },
-*   file(params, context) {
-*     return this.default.file({ ...params, resolveName: (name) => toFilePath(name, pascalCase) }, context)
+* })
+* ```
+*
+* @example Rename generated files with `file.baseName`
+* ```ts
+* export const resolverFaker = createResolver<PluginFaker>({
+*   pluginName: 'plugin-faker',
+*   name(name) {
+*     return camelCase(name, { prefix: 'create' })
+*   },
+*   file: {
+*     baseName({ name, extname }) {
+*       return `${camelCase(name, { prefix: 'create' })}${extname}`
+*     },
+*   },
+* })
+* ```
+*
+* @example Own the full path with `file.path`
+* ```ts
+* export const resolverFaker = createResolver<PluginFaker>({
+*   pluginName: 'plugin-faker',
+*   file: {
+*     path({ baseName, output }) {
+*       return `${output.path}/mocks/${baseName}`
+*     },
 *   },
 * })
 * ```
@@ -1326,7 +1408,7 @@ var KubbDriver = class {
 	* the failure as a {@link Diagnostic} instead of propagating. Each plugin also
 	* contributes a `timing` diagnostic for the run summary.
 	*/
-	async run({ storage }) {
+	async run() {
 		const { hooks, config, fileManager } = this;
 		const diagnostics = [];
 		const parsersMap = /* @__PURE__ */ new Map();
@@ -1408,7 +1490,7 @@ var KubbDriver = class {
 				diagnostics.push(...await this.#runGenerators(generatorPlugins));
 				await hooks.callHook("kubb:plugins:end", Object.assign({ config }, this.#filesPayload()));
 				await fileManager.write(fileManager.files, {
-					storage,
+					storage: config.storage,
 					parsers: parsersMap,
 					extension: config.output.extension
 				});
@@ -1976,7 +2058,7 @@ var Kubb = class {
 			const self = _usingCtx$1.u(this);
 			const driver = self.driver;
 			const storage = self.storage;
-			const { diagnostics } = await driver.run({ storage });
+			const { diagnostics } = await driver.run();
 			return {
 				diagnostics,
 				files: driver.fileManager.files,