@kubb/plugin-cypress 5.0.0-beta.3 → 5.0.0-beta.31

package/dist/index.d.ts

@@ -16,26 +16,32 @@ type ResolverCypress = Resolver & {
    * `resolver.resolveName('show pet by id') // -> 'showPetById'`
    */
   resolveName(this: ResolverCypress, name: string): string;
+  /**
+   * Resolves the output file name for a Cypress request module.
+   */
+  resolvePathName(this: ResolverCypress, name: string, type?: 'file' | 'function' | 'type' | 'const'): string;
 };
 /**
  * Parameter handling mode that determines how path params and query/body params are arranged in function signatures.
  */
 type ParamsTypeOptions = {
   /**
-   * All parameters merged into a single destructured object.
+   * Every operation parameter is wrapped in a single destructured object argument.
    */
   paramsType: 'object';
   /**
-   * Not applicable when all parameters are merged into a single object.
+   * `pathParamsType` has no effect when `paramsType` is `'object'`.
    */
   pathParamsType?: never;
 } | {
   /**
-   * Each parameter group emitted as a separate function argument.
+   * Each parameter group is emitted as a separate positional function argument.
    */
   paramsType?: 'inline';
   /**
-   * How path parameters are arranged: grouped in an object or spread inline.
+   * How URL path parameters are arranged inside the inline argument list.
+   * - `'object'` groups them into one destructured object.
+   * - `'inline'` emits each path param as its own argument.
    *
    * @default 'inline'
    */
@@ -43,50 +49,56 @@ type ParamsTypeOptions = {
 };
 type Options = {
   /**
-   * Specify the export location for the files and define the behavior of the output.
-   * @default { path: 'cypress', barrelType: 'named' }
+   * Where the generated Cypress helpers are written and how they are exported.
+   *
+   * @default { path: 'cypress', barrel: { type: 'named' } }
    */
   output?: Output;
   /**
-   * Return type when calling cy.request: response data only or full response.
+   * Shape of the value returned from each helper.
+   * - `'data'` — only the response body.
+   * - `'full'` — the full Cypress response object (headers, status, body).
    *
    * @default 'data'
    */
   dataReturnType?: 'data' | 'full';
   /**
-   * Apply casing to parameter names.
+   * Rename parameter properties in the generated helpers (path, query, headers).
+   *
+   * @note Must match the value of `paramsCasing` on `@kubb/plugin-ts`.
    */
   paramsCasing?: 'camelcase';
   /**
-   * Base URL prepended to every generated request URL.
+   * Base URL prepended to every request URL. When omitted, falls back to the
+   * adapter's server URL (typically `servers[0].url`).
    */
   baseURL?: string;
   /**
-   * Group the Cypress requests based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group;
   /**
-   * Tags, operations, or paths to exclude from generation.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>;
   /**
-   * Tags, operations, or paths to include in generation.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>;
   /**
-   * Override options for specific tags, operations, or paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>;
   /**
-   * Override naming conventions for function names and types.
+   * Override how helper names and file paths are built.
    */
   resolver?: Partial<ResolverCypress> & ThisType<ResolverCypress>;
   /**
-   * AST visitor to transform generated nodes.
+   * AST visitor applied to each operation node before printing.
    */
   transformer?: ast.Visitor;
   /**
-   * Additional generators alongside the default generators.
+   * Custom generators that run alongside the built-in Cypress generators.
    */
   generators?: Array<Generator<PluginCypress>>;
 } & ParamsTypeOptions;
@@ -95,7 +107,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>;
   include: Array<Include> | undefined;
   override: Array<Override<ResolvedOptions>>;
-  group: Group | undefined;
+  group: Group | null;
   baseURL: Options['baseURL'] | undefined;
   dataReturnType: NonNullable<Options['dataReturnType']>;
   pathParamsType: NonNullable<NonNullable<Options['pathParamsType']>>;
@@ -126,7 +138,7 @@ type Props = {
    * TypeScript resolver for resolving param/data/response type names
    */
   resolver: ResolverTs;
-  baseURL: string | undefined;
+  baseURL: string | null | undefined;
   dataReturnType: PluginCypress['resolvedOptions']['dataReturnType'];
   paramsCasing: PluginCypress['resolvedOptions']['paramsCasing'];
   paramsType: PluginCypress['resolvedOptions']['paramsType'];
@@ -144,27 +156,39 @@ declare function Request({
 }: Props): KubbReactNode;
 //#endregion
 //#region src/generators/cypressGenerator.d.ts
+/**
+ * Built-in generator for `@kubb/plugin-cypress`. Emits one typed
+ * `cy.request()` wrapper per OpenAPI operation, ready to call inside Cypress
+ * test specs and custom commands.
+ */
 declare const cypressGenerator: _$_kubb_core0.Generator<PluginCypress, unknown>;
 //#endregion
 //#region src/plugin.d.ts
 /**
- * Canonical plugin name for `@kubb/plugin-cypress`, used to identify the plugin
- * in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-cypress`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 declare const pluginCypressName = "plugin-cypress";
 /**
- * The `@kubb/plugin-cypress` plugin factory.
- *
- * Generates Cypress `cy.request()` test functions from an OpenAPI/AST `RootNode`.
- * Walks operations, delegates rendering to the active generators,
- * and writes barrel files based on `output.barrelType`.
+ * Generates one typed `cy.request()` wrapper per OpenAPI operation. Each helper
+ * has typed path params, body, query, and a typed response, so failing API
+ * calls in Cypress show up at compile time instead of inside the test runner.
  *
  * @example
  * ```ts
- * import pluginCypress from '@kubb/plugin-cypress'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ * import { pluginCypress } from '@kubb/plugin-cypress'
  *
  * export default defineConfig({
- *   plugins: [pluginCypress({ output: { path: 'cypress' } })],
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs(),
+ *     pluginCypress({
+ *       output: { path: './cypress' },
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -172,12 +196,16 @@ declare const pluginCypress: (options?: Options | undefined) => _$_kubb_core0.Pl
 //#endregion
 //#region src/resolvers/resolverCypress.d.ts
 /**
- * Naming convention resolver for Cypress plugin.
+ * Default resolver used by `@kubb/plugin-cypress`. Decides the names and file
+ * paths for every generated `cy.request()` wrapper. Functions and files use
+ * camelCase, matching the convention from `@kubb/plugin-client`.
  *
- * Provides default naming helpers using camelCase for functions and file paths.
+ * @example Resolve a helper name
+ * ```ts
+ * import { resolverCypress } from '@kubb/plugin-cypress'
  *
- * @example
- * `resolverCypress.default('list pets', 'function')  // → 'listPets'`
+ * resolverCypress.default('list pets', 'function') // 'listPets'
+ * ```
  */
 declare const resolverCypress: ResolverCypress;
 //#endregion

package/dist/index.js

@@ -1,7 +1,7 @@
 import "./chunk--u3MIqq1.js";
 import { ast, defineGenerator, definePlugin, defineResolver } from "@kubb/core";
 import { functionPrinter, pluginTsName } from "@kubb/plugin-ts";
-import { File, Function, jsxRenderer } from "@kubb/renderer-jsx";
+import { File, Function, jsxRendererSync } from "@kubb/renderer-jsx";
 import { jsx, jsxs } from "@kubb/renderer-jsx/jsx-runtime";
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -214,16 +214,16 @@ var URLPath = class {
 	get object() {
 		return this.toObject();
 	}
-	/** Returns a map of path parameter names, or `undefined` when the path has no parameters.
+	/** Returns a map of path parameter names, or `null` when the path has no parameters.
 	*
 	* @example
 	* ```ts
 	* new URLPath('/pet/{petId}').params // { petId: 'petId' }
-	* new URLPath('/pet').params         // undefined
+	* new URLPath('/pet').params         // null
 	* ```
 	*/
 	get params() {
-		return this.getParams();
+		return this.toParamsObject();
 	}
 	#transformParam(raw) {
 		const param = isValidVarName(raw) ? raw : camelCase(raw);
@@ -241,7 +241,7 @@ var URLPath = class {
 	toObject({ type = "path", replacer, stringify } = {}) {
 		const object = {
 			url: type === "path" ? this.toURLPath() : this.toTemplateString({ replacer }),
-			params: this.getParams()
+			params: this.toParamsObject()
 		};
 		if (stringify) {
 			if (type === "template") return JSON.stringify(object).replaceAll("'", "").replaceAll(`"`, "");
@@ -257,12 +257,13 @@ var URLPath = class {
 	* @example
 	* new URLPath('/pet/{petId}').toTemplateString() // '`/pet/${petId}`'
 	*/
-	toTemplateString({ prefix = "", replacer } = {}) {
-		return `\`${prefix}${this.path.split(/\{([^}]+)\}/).map((part, i) => {
+	toTemplateString({ prefix, replacer } = {}) {
+		const result = this.path.split(/\{([^}]+)\}/).map((part, i) => {
 			if (i % 2 === 0) return part;
 			const param = this.#transformParam(part);
 			return `\${${replacer ? replacer(param) : param}}`;
-		}).join("")}\``;
+		}).join("");
+		return `\`${prefix ?? ""}${result}\``;
 	}
 	/**
 	* Extracts all `{param}` segments from the path and returns them as a key-value map.
@@ -271,17 +272,17 @@ var URLPath = class {
 	*
 	* @example
 	* ```ts
-	* new URLPath('/pet/{petId}/tag/{tagId}').getParams()
+	* new URLPath('/pet/{petId}/tag/{tagId}').toParamsObject()
 	* // { petId: 'petId', tagId: 'tagId' }
 	* ```
 	*/
-	getParams(replacer) {
+	toParamsObject(replacer) {
 		const params = {};
 		this.#eachParam((_raw, param) => {
 			const key = replacer ? replacer(param) : param;
 			params[key] = key;
 		});
-		return Object.keys(params).length > 0 ? params : void 0;
+		return Object.keys(params).length > 0 ? params : null;
 	}
 	/** Converts the OpenAPI path to Express-style colon syntax.
 	*
@@ -295,9 +296,100 @@ var URLPath = class {
 	}
 };
 //#endregion
+//#region ../../internals/shared/src/operation.ts
+function getOperationParameters(node, options = {}) {
+	const params = ast.caseParams(node.parameters, options.paramsCasing);
+	return {
+		path: params.filter((param) => param.in === "path"),
+		query: params.filter((param) => param.in === "query"),
+		header: params.filter((param) => param.in === "header"),
+		cookie: params.filter((param) => param.in === "cookie")
+	};
+}
+function getStatusCodeNumber(statusCode) {
+	const code = Number(statusCode);
+	return Number.isNaN(code) ? null : code;
+}
+function isErrorStatusCode(statusCode) {
+	const code = getStatusCodeNumber(statusCode);
+	return code !== null && code >= 400;
+}
+function resolveErrorNames(node, resolver) {
+	return node.responses.filter((response) => isErrorStatusCode(response.statusCode)).map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
+}
+function resolveStatusCodeNames(node, resolver) {
+	return node.responses.map((response) => resolver.resolveResponseStatusName(node, response.statusCode));
+}
+const typeNamesByResolver = /* @__PURE__ */ new WeakMap();
+function resolveOperationTypeNames(node, resolver, options = {}) {
+	const cacheKey = `${node.operationId}\0${options.paramsCasing ?? ""}\0${options.order ?? ""}\0${options.responseStatusNames ?? ""}\0${(options.exclude ?? []).join(",")}`;
+	let byResolver = typeNamesByResolver.get(resolver);
+	if (byResolver) {
+		const cached = byResolver.get(cacheKey);
+		if (cached) return cached;
+	} else {
+		byResolver = /* @__PURE__ */ new Map();
+		typeNamesByResolver.set(resolver, byResolver);
+	}
+	const { path, query, header } = getOperationParameters(node, { paramsCasing: options.paramsCasing });
+	const responseStatusNames = options.responseStatusNames === "error" ? resolveErrorNames(node, resolver) : options.responseStatusNames === false ? [] : resolveStatusCodeNames(node, resolver);
+	const exclude = new Set(options.exclude ?? []);
+	const paramNames = [
+		...path.map((param) => resolver.resolvePathParamsName(node, param)),
+		...query.map((param) => resolver.resolveQueryParamsName(node, param)),
+		...header.map((param) => resolver.resolveHeaderParamsName(node, param))
+	];
+	const bodyAndResponseNames = [node.requestBody?.content?.[0]?.schema ? resolver.resolveDataName(node) : null, resolver.resolveResponseName(node)];
+	const result = (options.order === "body-response-first" ? [
+		...bodyAndResponseNames,
+		...paramNames,
+		...responseStatusNames
+	] : [
+		...paramNames,
+		...bodyAndResponseNames,
+		...responseStatusNames
+	]).filter((name) => Boolean(name) && !exclude.has(name));
+	byResolver.set(cacheKey, result);
+	return result;
+}
+//#endregion
+//#region ../../internals/shared/src/group.ts
+/**
+* Builds the `group` config a Kubb plugin passes to `ctx.setOptions`, applying the
+* shared default naming so every plugin groups output consistently:
+*
+* - `path` groups use the second path segment (`/pet/findByStatus` → `pet`).
+* - other groups use `${camelCase(group)}${suffix}` (e.g. `petController`).
+*
+* Returns `null` when grouping is disabled, matching the per-plugin convention.
+*
+* @param group - The user-supplied group option, or `undefined` to disable grouping.
+* @param options.suffix - Appended to non-`path` group names, e.g. `'Controller'` or `'Requests'`.
+* @param options.honorName - When `true`, a user-provided `group.name` overrides the default namer.
+*
+* @example
+* ```ts
+* createGroupConfig(group, { suffix: 'Controller' })                  // plugin-ts, plugin-zod
+* createGroupConfig(group, { suffix: 'Controller', honorName: true }) // plugin-faker, plugin-client, …
+* createGroupConfig(group, { suffix: 'Requests', honorName: true })   // plugin-cypress, plugin-mcp
+* ```
+*/
+function createGroupConfig(group, options) {
+	if (!group) return null;
+	const defaultName = (ctx) => {
+		if (group.type === "path") return `${ctx.group.split("/")[1]}`;
+		return `${camelCase(ctx.group)}${options.suffix}`;
+	};
+	return {
+		...group,
+		name: options.honorName && group.name ? group.name : defaultName
+	};
+}
+//#endregion
 //#region src/components/Request.tsx
 const declarationPrinter = functionPrinter({ mode: "declaration" });
 function Request({ baseURL = "", name, dataReturnType, resolver, node, paramsType, pathParamsType, paramsCasing }) {
+	if (!ast.isHttpOperationNode(node)) return null;
 	const paramsNode = ast.createOperationParams(node, {
 		paramsType,
 		pathParamsType,
@@ -315,24 +407,24 @@ function Request({ baseURL = "", name, dataReturnType, resolver, node, paramsTyp
 	const paramsSignature = declarationPrinter.print(paramsNode) ?? "";
 	const responseType = resolver.resolveResponseName(node);
 	const returnType = dataReturnType === "data" ? `Cypress.Chainable<${responseType}>` : `Cypress.Chainable<Cypress.Response<${responseType}>>`;
-	const casedPathParams = ast.caseParams(node.parameters.filter((p) => p.in === "path"), paramsCasing);
+	const casedPathParams = getOperationParameters(node, { paramsCasing }).path;
 	const pathParamNameMap = new Map(casedPathParams.map((p) => [camelCase(p.name), p.name]));
 	const urlTemplate = new URLPath(node.path, { casing: paramsCasing }).toTemplateString({
 		prefix: baseURL,
 		replacer: (param) => pathParamNameMap.get(camelCase(param)) ?? param
 	});
 	const requestOptions = [`method: '${node.method}'`, `url: ${urlTemplate}`];
-	const queryParams = node.parameters.filter((p) => p.in === "query");
+	const queryParams = getOperationParameters(node).query;
 	if (queryParams.length > 0) {
-		const casedQueryParams = ast.caseParams(queryParams, paramsCasing);
+		const casedQueryParams = getOperationParameters(node, { paramsCasing }).query;
 		if (casedQueryParams.some((p, i) => p.name !== queryParams[i].name)) {
 			const pairs = queryParams.map((orig, i) => `${orig.name}: params.${casedQueryParams[i].name}`).join(", ");
 			requestOptions.push(`qs: params ? { ${pairs} } : undefined`);
 		} else requestOptions.push("qs: params");
 	}
-	const headerParams = node.parameters.filter((p) => p.in === "header");
+	const headerParams = getOperationParameters(node).header;
 	if (headerParams.length > 0) {
-		const casedHeaderParams = ast.caseParams(headerParams, paramsCasing);
+		const casedHeaderParams = getOperationParameters(node, { paramsCasing }).header;
 		if (casedHeaderParams.some((p, i) => p.name !== headerParams[i].name)) {
 			const pairs = headerParams.map((orig, i) => `'${orig.name}': headers.${casedHeaderParams[i].name}`).join(", ");
 			requestOptions.push(`headers: headers ? { ${pairs} } : undefined`);
@@ -359,26 +451,22 @@ function Request({ baseURL = "", name, dataReturnType, resolver, node, paramsTyp
 }
 //#endregion
 //#region src/generators/cypressGenerator.tsx
+/**
+* Built-in generator for `@kubb/plugin-cypress`. Emits one typed
+* `cy.request()` wrapper per OpenAPI operation, ready to call inside Cypress
+* test specs and custom commands.
+*/
 const cypressGenerator = defineGenerator({
 	name: "cypress",
-	renderer: jsxRenderer,
+	renderer: jsxRendererSync,
 	operation(node, ctx) {
-		const { adapter, config, resolver, driver, root } = ctx;
+		if (!ast.isHttpOperationNode(node)) return null;
+		const { config, resolver, driver, root } = ctx;
 		const { output, baseURL, dataReturnType, paramsCasing, paramsType, pathParamsType, group } = ctx.options;
 		const pluginTs = driver.getPlugin(pluginTsName);
 		if (!pluginTs) return null;
 		const tsResolver = driver.getResolver(pluginTsName);
-		const casedParams = ast.caseParams(node.parameters, paramsCasing);
-		const pathParams = casedParams.filter((p) => p.in === "path");
-		const queryParams = casedParams.filter((p) => p.in === "query");
-		const headerParams = casedParams.filter((p) => p.in === "header");
-		const importedTypeNames = [
-			...pathParams.map((p) => tsResolver.resolvePathParamsName(node, p)),
-			...queryParams.map((p) => tsResolver.resolveQueryParamsName(node, p)),
-			...headerParams.map((p) => tsResolver.resolveHeaderParamsName(node, p)),
-			node.requestBody?.content?.[0]?.schema ? tsResolver.resolveDataName(node) : void 0,
-			tsResolver.resolveResponseName(node)
-		].filter(Boolean);
+		const importedTypeNames = resolveOperationTypeNames(node, tsResolver, { paramsCasing });
 		const meta = {
 			name: resolver.resolveName(node.operationId),
 			file: resolver.resolveFile({
@@ -389,7 +477,7 @@ const cypressGenerator = defineGenerator({
 			}, {
 				root,
 				output,
-				group
+				group: group ?? void 0
 			}),
 			fileTs: tsResolver.resolveFile({
 				name: node.operationId,
@@ -399,23 +487,31 @@ const cypressGenerator = defineGenerator({
 			}, {
 				root,
 				output: pluginTs.options?.output ?? output,
-				group: pluginTs.options?.group
+				group: pluginTs.options?.group ?? void 0
 			})
 		};
 		return /* @__PURE__ */ jsxs(File, {
 			baseName: meta.file.baseName,
 			path: meta.file.path,
 			meta: meta.file.meta,
-			banner: resolver.resolveBanner(adapter.inputNode, {
+			banner: resolver.resolveBanner(ctx.meta, {
 				output,
-				config
+				config,
+				file: {
+					path: meta.file.path,
+					baseName: meta.file.baseName
+				}
 			}),
-			footer: resolver.resolveFooter(adapter.inputNode, {
+			footer: resolver.resolveFooter(ctx.meta, {
 				output,
-				config
+				config,
+				file: {
+					path: meta.file.path,
+					baseName: meta.file.baseName
+				}
 			}),
 			children: [meta.fileTs && importedTypeNames.length > 0 && /* @__PURE__ */ jsx(File.Import, {
-				name: Array.from(new Set(importedTypeNames)),
+				name: importedTypeNames,
 				root: meta.file.path,
 				path: meta.fileTs.path,
 				isTypeOnly: true
@@ -435,43 +531,57 @@ const cypressGenerator = defineGenerator({
 //#endregion
 //#region src/resolvers/resolverCypress.ts
 /**
-* Naming convention resolver for Cypress plugin.
+* Default resolver used by `@kubb/plugin-cypress`. Decides the names and file
+* paths for every generated `cy.request()` wrapper. Functions and files use
+* camelCase, matching the convention from `@kubb/plugin-client`.
 *
-* Provides default naming helpers using camelCase for functions and file paths.
+* @example Resolve a helper name
+* ```ts
+* import { resolverCypress } from '@kubb/plugin-cypress'
 *
-* @example
-* `resolverCypress.default('list pets', 'function')  // → 'listPets'`
+* resolverCypress.default('list pets', 'function') // 'listPets'
+* ```
 */
-const resolverCypress = defineResolver((ctx) => ({
+const resolverCypress = defineResolver(() => ({
 	name: "default",
 	pluginName: "plugin-cypress",
 	default(name, type) {
 		return camelCase(name, { isFile: type === "file" });
 	},
 	resolveName(name) {
-		return ctx.default(name, "function");
+		return this.default(name, "function");
+	},
+	resolvePathName(name, type) {
+		return this.default(name, type);
 	}
 }));
 //#endregion
 //#region src/plugin.ts
 /**
-* Canonical plugin name for `@kubb/plugin-cypress`, used to identify the plugin
-* in driver lookups and warnings.
+* Canonical plugin name for `@kubb/plugin-cypress`. Used for driver lookups and
+* cross-plugin dependency references.
 */
 const pluginCypressName = "plugin-cypress";
 /**
-* The `@kubb/plugin-cypress` plugin factory.
-*
-* Generates Cypress `cy.request()` test functions from an OpenAPI/AST `RootNode`.
-* Walks operations, delegates rendering to the active generators,
-* and writes barrel files based on `output.barrelType`.
+* Generates one typed `cy.request()` wrapper per OpenAPI operation. Each helper
+* has typed path params, body, query, and a typed response, so failing API
+* calls in Cypress show up at compile time instead of inside the test runner.
 *
 * @example
 * ```ts
-* import pluginCypress from '@kubb/plugin-cypress'
+* import { defineConfig } from 'kubb'
+* import { pluginTs } from '@kubb/plugin-ts'
+* import { pluginCypress } from '@kubb/plugin-cypress'
 *
 * export default defineConfig({
-*   plugins: [pluginCypress({ output: { path: 'cypress' } })],
+*   input: { path: './petStore.yaml' },
+*   output: { path: './src/gen' },
+*   plugins: [
+*     pluginTs(),
+*     pluginCypress({
+*       output: { path: './cypress' },
+*     }),
+*   ],
 * })
 * ```
 */
@@ -480,13 +590,10 @@ const pluginCypress = definePlugin((options) => {
 		path: "cypress",
 		barrelType: "named"
 	}, group, exclude = [], include, override = [], dataReturnType = "data", baseURL, paramsCasing, paramsType = "inline", pathParamsType = paramsType === "object" ? "object" : options.pathParamsType || "inline", resolver: userResolver, transformer: userTransformer, generators: userGenerators = [] } = options;
-	const groupConfig = group ? {
-		...group,
-		name: group.name ? group.name : (ctx) => {
-			if (group.type === "path") return `${ctx.group.split("/")[1]}`;
-			return `${camelCase(ctx.group)}Requests`;
-		}
-	} : void 0;
+	const groupConfig = createGroupConfig(group, {
+		suffix: "Requests",
+		honorName: true
+	});
 	return {
 		name: pluginCypressName,
 		options,