feat: warn when duplicate plugins are specified

.changeset/warn-duplicate-plugins.md

@@ -0,0 +1,6 @@
+---
+"@hey-api/openapi-ts": patch
+"@hey-api/shared": patch
+---
+
+**config**: warn on duplicated plugin configurations

packages/openapi-python/src/config/plugins.ts

@@ -1,5 +1,9 @@
 import type { AnyPluginName, PluginContext, PluginNames } from '@hey-api/shared';
-import { dependencyFactory, valueToObject } from '@hey-api/shared';
+import {
+  dependencyFactory,
+  valueToObject,
+  warnOnConflictingDuplicatePlugins,
+} from '@hey-api/shared';
 
 import { defaultPluginConfigs } from '../plugins/config';
 import type { Config, UserConfig } from './types';
@@ -143,6 +147,8 @@ export function getPlugins({
     }
   }
 
+  warnOnConflictingDuplicatePlugins(definedPlugins);
+
   const userPlugins = definedPlugins
     .map((plugin) => {
       if (typeof plugin === 'string') {

packages/openapi-ts/src/config/plugins.ts

@@ -1,5 +1,9 @@
 import type { AnyPluginName, PluginContext, PluginNames } from '@hey-api/shared';
-import { dependencyFactory, valueToObject } from '@hey-api/shared';
+import {
+  dependencyFactory,
+  valueToObject,
+  warnOnConflictingDuplicatePlugins,
+} from '@hey-api/shared';
 
 import { defaultPluginConfigs } from '../plugins/config';
 import type { Config, UserConfig } from './types';
@@ -146,6 +150,8 @@ export function getPlugins({
     }
   }
 
+  warnOnConflictingDuplicatePlugins(definedPlugins);
+
   const userPlugins = definedPlugins
     .map((plugin) => {
       if (typeof plugin === 'string') {

packages/shared/src/index.ts

@@ -99,6 +99,7 @@ export type {
   OpenApiSchemaObject,
 } from './openApi/types';
 export type { GetNameContext, Hooks } from './parser/hooks';
+export { warnOnConflictingDuplicatePlugins } from './plugins/duplicate';
 export type { SchemaWithType } from './plugins/shared/types/schema';
 export { definePluginConfig, mappers } from './plugins/shared/utils/config';
 export type { PluginInstanceTypes } from './plugins/shared/utils/instance';

packages/shared/src/plugins/__tests__/duplicate.test.ts

@@ -0,0 +1,193 @@
+import { log } from '@hey-api/codegen-core';
+
+import { warnOnConflictingDuplicatePlugins } from '../duplicate';
+
+describe('warnOnConflictingDuplicatePlugins', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const warningMessage =
+    'Plugin "@hey-api/client-fetch" is configured multiple times. Only the last instance will take effect.';
+
+  it('does not warn for duplicate string plugins', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins(['@hey-api/client-fetch', '@hey-api/client-fetch']);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn for duplicate plugins with identical config in different key order', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        foo: 'bar',
+        name: '@hey-api/client-fetch',
+        output: 'sdk',
+      },
+      {
+        output: 'sdk',
+        // eslint-disable-next-line sort-keys-fix/sort-keys-fix
+        foo: 'bar',
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn when a string and an object with only name are specified', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins(['@hey-api/client-fetch', { name: '@hey-api/client-fetch' }]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn for duplicate plugins with identical object config', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        foo: 'bar',
+        name: '@hey-api/client-fetch',
+      },
+      {
+        foo: 'bar',
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn when nested object configs differ only in key order', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        definitions: { case: 'PascalCase', name: 'foo' },
+        name: '@hey-api/client-fetch',
+      },
+      {
+        // eslint-disable-next-line sort-keys-fix/sort-keys-fix
+        definitions: { name: 'foo', case: 'PascalCase' },
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns for duplicate plugins with conflicting config', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        foo: 'bar',
+        name: '@hey-api/client-fetch',
+      },
+      {
+        foo: 'baz',
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledWith(warningMessage);
+  });
+
+  it('warns when a string plugin conflicts with an object plugin of the same name', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      '@hey-api/client-fetch',
+      {
+        name: '@hey-api/client-fetch',
+        output: 'sdk',
+      },
+    ]);
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+  });
+
+  it('does not warn when array-valued options differ only in element key order', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        items: [{ from: 'foo', name: 'bar' }],
+        name: '@hey-api/client-fetch',
+      },
+      {
+        // eslint-disable-next-line sort-keys-fix/sort-keys-fix
+        items: [{ name: 'bar', from: 'foo' }],
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns when array-valued options differ in element order', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        items: [
+          { from: 'a', name: 'x' },
+          { from: 'b', name: 'y' },
+        ],
+        name: '@hey-api/client-fetch',
+      },
+      {
+        items: [
+          { from: 'b', name: 'y' },
+          { from: 'a', name: 'x' },
+        ],
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledWith(warningMessage);
+  });
+
+  it('does not warn when function-valued options have identical source', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+    const transform = (value: string) => value.toUpperCase();
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        definitions: { name: transform },
+        name: '@hey-api/client-fetch',
+      },
+      {
+        definitions: { name: transform },
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('warns when function-valued options differ', () => {
+    const warnSpy = vi.spyOn(log, 'warn').mockImplementation(() => {});
+
+    warnOnConflictingDuplicatePlugins([
+      {
+        definitions: { name: (value: string) => value.toUpperCase() },
+        name: '@hey-api/client-fetch',
+      },
+      {
+        definitions: { name: (value: string) => value.toLowerCase() },
+        name: '@hey-api/client-fetch',
+      },
+    ]);
+
+    expect(warnSpy).toHaveBeenCalledOnce();
+    expect(warnSpy).toHaveBeenCalledWith(warningMessage);
+  });
+});

packages/shared/src/plugins/duplicate.ts

@@ -0,0 +1,64 @@
+import { log } from '@hey-api/codegen-core';
+
+import type { PluginNames } from './types';
+
+type PluginConfig = {
+  name: PluginNames;
+};
+
+type PluginDefinition<TConfig extends PluginConfig = PluginConfig> = PluginNames | TConfig;
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_, v) => {
+    if (typeof v === 'function') {
+      return `[function:${(v as () => unknown).toString()}]`;
+    }
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      return Object.fromEntries(
+        Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)),
+      );
+    }
+    return v;
+  });
+}
+
+function normalizePluginEntry<TConfig extends PluginConfig>(
+  plugin: PluginDefinition<TConfig>,
+): {
+  name: PluginNames;
+  serialized: string;
+} {
+  if (typeof plugin === 'string') {
+    return {
+      name: plugin,
+      serialized: '{}',
+    };
+  }
+
+  const { name, ...config } = plugin;
+
+  return {
+    name,
+    serialized: stableStringify(config),
+  };
+}
+
+export function warnOnConflictingDuplicatePlugins<TConfig extends PluginConfig>(
+  plugins: ReadonlyArray<PluginDefinition<TConfig>>,
+): void {
+  const seen = new Map<string, string>();
+
+  for (const plugin of plugins) {
+    const { name, serialized } = normalizePluginEntry(plugin);
+    if (!name) continue;
+
+    const previous = seen.get(name);
+    if (previous !== undefined && previous !== serialized) {
+      log.warn(
+        `Plugin "${name}" is configured multiple times. Only the last instance will take effect.`,
+      );
+    }
+
+    seen.set(name, serialized);
+  }
+}