feat(core): add external option to mutator config (orval-labs#2735)

* feat(core): add external option to mutator config

Add support for esbuild's `external` option in mutator configuration.
This allows users to exclude specific modules or patterns from bundling
during mutator parsing.

Use case: Mutators that import HTTP clients from larger codebases often
have transitive dependencies on non-JS assets (scss, css, images).
Esbuild cannot bundle these, causing silent failures. With `external`,
users can skip problematic imports:

```js
mutator: {
  path: './api-mutator.ts',
  name: 'apiMutator',
  external: ['*.scss', '*.css'],
}
```

The user-provided patterns are merged with the existing `['*']` default
that externalizes bare module imports.

* Update packages/core/src/generators/mutator-info.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Melloware <mellowaredev@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

packages/core/src/generators/mutator-info.ts

@@ -16,20 +16,23 @@ export async function getMutatorInfo(
     root?: string;
     namedExport?: string;
     alias?: Record<string, string>;
+    external?: string[];
     tsconfig?: Tsconfig;
   },
 ): Promise<GeneratorMutatorParsingInfo | undefined> {
   const {
     root = process.cwd(),
     namedExport = 'default',
     alias,
+    external,
     tsconfig,
   } = options ?? {};
 
   const code = await bundleFile(
     root,
     path.resolve(filePath),
     alias,
+    external,
     tsconfig?.compilerOptions,
   );
 
@@ -44,6 +47,7 @@ async function bundleFile(
   root: string,
   fileName: string,
   alias?: Record<string, string>,
+  external?: string[],
   compilerOptions?: Tsconfig['compilerOptions'],
 ): Promise<string> {
   const result = await build({
@@ -62,7 +66,7 @@ async function bundleFile(
     treeShaking: false,
     keepNames: false,
     alias,
-    external: ['*'],
+    external: external || ['*'],
   } satisfies BuildOptions);
   const { text } = result.outputFiles[0];
 

packages/core/src/generators/mutator.ts

@@ -71,6 +71,7 @@ export async function generateMutator({
     root: path.resolve(workspace),
     namedExport: mutatorInfoName,
     alias: mutator.alias,
+    external: mutator.external,
     tsconfig,
   });
 

packages/core/src/types.ts

@@ -114,6 +114,7 @@ export type NormalizedMutator = {
   name?: string;
   default: boolean;
   alias?: Record<string, string>;
+  external?: string[];
   extension?: string;
 };
 
@@ -373,6 +374,7 @@ export type MutatorObject = {
   name?: string;
   default?: boolean;
   alias?: Record<string, string>;
+  external?: string[];
   extension?: string;
 };
 

tests/configs/fetch.config.ts

@@ -380,4 +380,21 @@ export default defineConfig({
       target: '../specifications/wildcard-responses.yaml',
     },
   },
+  mutatorWithExternal: {
+    output: {
+      target: '../generated/fetch/mutator-external/endpoints.ts',
+      schemas: '../generated/fetch/mutator-external/model',
+      client: 'fetch',
+      override: {
+        mutator: {
+          path: '../mutators/with-scss-import.ts',
+          name: 'customFetchWithScss',
+          external: ['*.scss'],
+        },
+      },
+    },
+    input: {
+      target: '../specifications/petstore.yaml',
+    },
+  },
 });

tests/mutators/styles.scss

@@ -0,0 +1,3 @@
+.test {
+  color: red;
+}

tests/mutators/with-scss-import.ts

@@ -0,0 +1,15 @@
+/**
+ * Mutator that imports a scss file.
+ * Tests the user-configurable `external` option for mutator bundling.
+ */
+import './styles.scss';
+
+export const customFetchWithScss = async <T>(
+  url: string,
+  options: RequestInit,
+): Promise<T> => {
+  const response = await fetch(url, options);
+  return response.json();
+};
+
+export default customFetchWithScss;