feat: support collapsing/overwriting technically-illegal duplicate plugin/preset PluginItems

Author: Xunnamius

README.md

@@ -318,8 +318,23 @@ this package.
 This is used to configure babel. If provided, the object will be
 [`lodash.mergeWith`][lodash.mergewith]'d with the [defaults][25] and each [test
 object's `babelOptions`][26]/[fixture's `babelOptions`][27], with the latter
-taking precedence. Note that arrays will be concatenated and explicitly
-undefined values will unset previously defined values during merging.
+taking precedence.
+
+Be aware that arrays will be concatenated and explicitly undefined values will
+unset previously defined values during merging.
+
+> [!IMPORTANT]
+>
+> For `babel-plugin-tester@>=12`, [duplicate entries][2] in
+> [`babelOptions.plugins`][55] and [`babelOptions.presets`][73] are reduced,
+> with latter entries _completely overwriting_ any that came before. In other
+> words: the last duplicate plugin or preset configuration wins. **They are not
+> merged.** This makes it easy to provide an alternative one-off configuration
+> for a plugin or preset that is also used elsewhere, such as a project's root
+> `babel.config.js` file.
+>
+> Attempting the same with `babel-plugin-tester@<12` will cause babel [to
+> throw][2] since duplicate entries are technically not allowed.
 
 Also note that [`babelOptions.babelrc`][28] and [`babelOptions.configFile`][29]
 are set to `false` by default, which disables automatic babel configuration
@@ -329,6 +344,8 @@ To simply reuse your project's [`babel.config.js`][31] or some other
 configuration file, set `babelOptions` like so:
 
 ```javascript
+// file: /repos/my-project/tests/unit-plugin.test.ts
+
 import path from 'node:path';
 import { pluginTester } from 'babel-plugin-tester';
 
@@ -795,9 +812,12 @@ of which are optional:
 
 This is used to configure babel. Properties specified here override
 ([`lodash.mergeWith`][lodash.mergewith]) those from the [`babelOptions`][65]
-option provided to babel-plugin-tester. Note that arrays will be concatenated
-and explicitly undefined values will unset previously defined values during
-merging.
+option provided to babel-plugin-tester.
+
+Note that arrays will be concatenated, explicitly undefined values will unset
+previously defined values, and (as of `babel-plugin-tester@>=12`) duplicate
+plugin/preset configurations will override each other (last configuration wins)
+during merging.
 
 ###### `pluginOptions`
 
@@ -1027,9 +1047,12 @@ which are optional:
 
 This is used to configure babel. Properties specified here override
 ([`lodash.mergeWith`][lodash.mergewith]) those from the [`babelOptions`][65]
-option provided to babel-plugin-tester. Note that arrays will be concatenated
-and explicitly undefined values will unset previously defined values during
-merging.
+option provided to babel-plugin-tester.
+
+Note that arrays will be concatenated, explicitly undefined values will unset
+previously defined values, and (as of `babel-plugin-tester@>=12`) duplicate
+plugin/preset configurations will override each other (last configuration wins)
+during merging.
 
 ###### `pluginOptions`
 
@@ -1687,6 +1710,8 @@ work, and you do not mind the [default run order][100], you can leverage
 [babel's automatic configuration loading][101] via the `babelOptions.babelrc`
 and/or `babelOptions.configFile` options.
 
+> [!TIP]
+>
 > Fixtures provided via the [`fixtures`][35] option **do not** need to provide a
 > separate `babelOptions.filename` since it will be set automatically. This
 > section only applies to [test objects][42].
@@ -1967,6 +1992,8 @@ The following [debug namespaces][109] are available for activation:
   - `babel-plugin-tester:tester:read-code`
   - `babel-plugin-tester:tester:eol`
   - `babel-plugin-tester:tester:finalize`
+    - `babel-plugin-tester:tester:finalize:order`
+    - `babel-plugin-tester:tester:finalize:duplicates`
 
 <!-- lint enable list-item-style -->
 
@@ -2257,6 +2284,8 @@ specification. Contributions of any kind welcome!
 [x-repo-sponsor]: https://github.com/sponsors/Xunnamius
 [x-repo-support]: /.github/SUPPORT.md
 [1]: https://www.npmjs.com/package/babel-plugin-tester?activeTab=versions
+[2]:
+  https://stackoverflow.com/questions/52798987/babel-7-fails-with-single-plugin-saying-duplicate-plugin-preset-detected
 [3]: https://babeljs.io/docs/en/presets
 [4]: https://jestjs.io
 [5]: https://mochajs.org
@@ -2311,6 +2340,7 @@ specification. Contributions of any kind welcome!
 [52]: #fixtureoutputext-1
 [53]: #titlenumbering
 [54]: #filepath
+[55]: https://babeljs.io/docs/options#plugins
 [56]: #outputjs
 [57]: #endofline
 [58]: #execjs
@@ -2330,6 +2360,7 @@ specification. Contributions of any kind welcome!
 [71]:
   https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-instanceof-array.md
 [72]: https://nodejs.org/api/vm.html#vm-executing-javascript
+[73]: https://babeljs.io/docs/options#presets
 [77]: https://stackoverflow.com/a/32750746/1367414
 [78]: #outputraw
 [79]: #teardown-1

src/plugin-tester.ts

@@ -13,6 +13,7 @@ import stripIndent from 'strip-indent~3';
 import { ErrorMessage } from 'universe:errors.ts';
 import { $type } from 'universe:symbols.ts';
 
+import type { PluginItem } from '@babel/core';
 import type { Class } from 'type-fest';
 
 import type {
@@ -830,6 +831,7 @@ function pluginTester(options: PluginTesterOptions = {}) {
 
           verbose3('partially constructed fixture-based test object: %O', testConfig);
 
+          // ! Invariant: test plugin/preset is always first/last respectively
           if (plugin) {
             testConfig.babelOptions.plugins.push([
               plugin,
@@ -843,6 +845,8 @@ function pluginTester(options: PluginTesterOptions = {}) {
           }
 
           finalizePluginAndPresetRunOrder(testConfig.babelOptions);
+          reduceDuplicatePluginsAndPresets(testConfig.babelOptions);
+
           verbose3('finalized fixture-based test object: %O', testConfig);
 
           validateTestConfig(testConfig);
@@ -998,6 +1002,8 @@ function pluginTester(options: PluginTesterOptions = {}) {
       }
 
       finalizePluginAndPresetRunOrder(testConfig.babelOptions);
+      reduceDuplicatePluginsAndPresets(testConfig.babelOptions);
+
       verbose3('finalized test object: %O', testConfig);
 
       validateTestConfig(testConfig, {
@@ -1630,7 +1636,7 @@ function trimAndFixLineEndings(
 function finalizePluginAndPresetRunOrder(
   babelOptions: PluginTesterOptions['babelOptions']
 ) {
-  const { verbose: verbose2 } = getDebuggers('finalize', debug1);
+  const { verbose: verbose2 } = getDebuggers('finalize:order', debug1);
 
   if (babelOptions?.plugins) {
     babelOptions.plugins = babelOptions.plugins.filter((p) => {
@@ -1686,6 +1692,116 @@ function finalizePluginAndPresetRunOrder(
   verbose2('finalized test object plugin and preset run order');
 }
 
+/**
+ * Collapses duplicate plugin/preset entries down to a single plugin/preset
+ * entry. The last duplicate plugin/preset (i.e. highest index) wins, the rest
+ * are essentially deleted.
+ *
+ * This function accounts for the three generic babel plugin/preset
+ * configurations: string, 2-tuple, and 3-tuple.
+ *
+ * @see {@link PluginItem}
+ */
+function reduceDuplicatePluginsAndPresets(
+  babelOptions: PluginTesterOptions['babelOptions']
+) {
+  const { verbose: verbose2 } = getDebuggers('finalize:duplicates', debug1);
+
+  if (babelOptions?.plugins) {
+    const plugins: typeof babelOptions.plugins = [];
+
+    babelOptions.plugins.forEach((incomingPlugin) => {
+      if (incomingPlugin && typeof incomingPlugin !== 'symbol') {
+        const incomingPluginName = pluginOrPresetToName(incomingPlugin);
+
+        if (incomingPluginName) {
+          const duplicatedPluginIndex = plugins.findIndex((outgoingPlugin) => {
+            if (outgoingPlugin && typeof outgoingPlugin !== 'symbol') {
+              const outgoingPluginName = pluginOrPresetToName(outgoingPlugin);
+              return outgoingPluginName === incomingPluginName;
+            }
+          });
+
+          if (duplicatedPluginIndex !== -1) {
+            verbose2(
+              'collapsed duplicate plugin configuration for %O (at index %O)',
+              incomingPluginName,
+              duplicatedPluginIndex
+            );
+
+            plugins[duplicatedPluginIndex] = incomingPlugin;
+            return;
+          }
+        }
+      }
+
+      plugins.push(incomingPlugin);
+    });
+
+    babelOptions.plugins = plugins;
+  }
+
+  if (babelOptions?.presets) {
+    const presets: typeof babelOptions.presets = [];
+
+    babelOptions.presets.forEach((incomingPreset) => {
+      if (incomingPreset && typeof incomingPreset !== 'symbol') {
+        const incomingPresetName = pluginOrPresetToName(incomingPreset);
+
+        if (incomingPresetName) {
+          const duplicatedPresetIndex = presets.findIndex((outgoingPreset) => {
+            if (outgoingPreset && typeof outgoingPreset !== 'symbol') {
+              const outgoingPresetName = pluginOrPresetToName(outgoingPreset);
+              return outgoingPresetName === incomingPresetName;
+            }
+          });
+
+          if (duplicatedPresetIndex !== -1) {
+            verbose2(
+              'collapsed duplicate preset configuration for %O (at index %O)',
+              incomingPresetName,
+              duplicatedPresetIndex
+            );
+
+            presets[duplicatedPresetIndex] = incomingPreset;
+            return;
+          }
+        }
+      }
+
+      presets.push(incomingPreset);
+    });
+
+    babelOptions.presets = presets;
+  }
+
+  verbose2('collapsed duplicate test object plugins and presets');
+
+  /**
+   * Note that, due to how flexible Babel configuration is, not all plugins or
+   * presets will have a name.
+   *
+   * This function is a _much_ more generic version of `tryInferPluginName`.
+   * TODO: perhaps they should be merged?
+   */
+  function pluginOrPresetToName(pluginOrPreset: PluginItem) {
+    if (typeof pluginOrPreset === 'string') {
+      return pluginOrPreset;
+    }
+
+    if (Array.isArray(pluginOrPreset)) {
+      const candidate = pluginOrPreset.at(2) ?? pluginOrPreset.at(0);
+      return typeof candidate === 'string' ? candidate : undefined;
+    }
+
+    if (typeof pluginOrPreset === 'object' && 'name' in pluginOrPreset) {
+      return typeof pluginOrPreset.name === 'string' ? pluginOrPreset.name : undefined;
+    }
+
+    return undefined;
+  }
+}
+
 /**
  * Determines if `numericPrefix` equals at least one number or is covered by at
  * least one range Range in the `ranges` array.

test/fixtures/README.md

@@ -8,6 +8,6 @@ structure similar to the following:
 
 ```text
 fixture-name-here
-└── fixture
+└── fixture (or some more specific sub-name)
     └── ... (one or more fixture-specific files like `code.js` or `options.js`)
 ```

test/fixtures/nested-options-js-deep-plugin/fixture/and-fixture/code.js

@@ -0,0 +1 @@
+'use strict';

test/fixtures/nested-options-js-deep-plugin/fixture/and-fixture/options.js

@@ -0,0 +1,8 @@
+module.exports = {
+  pluginOptions: {
+    appendExtension: '.mjs'
+  },
+  babelOptions: {
+    plugins: ['@babel/plugin-syntax-jsx']
+  }
+};

test/fixtures/nested-options-js-deep-plugin/fixture/and-fixture/output.mjs

@@ -0,0 +1 @@
+'use strict';

test/fixtures/nested-options-js-deep-plugin/fixture/options.js

@@ -0,0 +1,6 @@
+module.exports = {
+  babelOptions: {
+    filename: '/fake/filepath.ts',
+    plugins: [['@babel/plugin-syntax-typescript', { isTSX: true }]]
+  }
+};

test/fixtures/nested-options-js-deep-plugin/options.json

@@ -0,0 +1,27 @@
+{
+  "fixtureOutputExt": ".mjs",
+  "pluginOptions": {
+    "replaceExtensions": {
+      ".ts": ".xjs"
+    }
+  },
+  "babelOptions": {
+    "plugins": [
+      [
+        "@babel/plugin-syntax-typescript",
+        { "isTSX": true, "somethingOrOther": 5 }
+      ],
+      ["@babel/plugin-syntax-jsx", { "somethingOrOther": 6 }],
+      [
+        "@babel/plugin-syntax-typescript",
+        { "isTSX": true, "somethingOrOther": 7 },
+        "ok-duplicate-plugin-syntax-typescript"
+      ],
+      [
+        "@babel/plugin-syntax-jsx",
+        { "somethingOrOther": 8 },
+        "ok-duplicate-plugin-syntax-jsx"
+      ]
+    ]
+  }
+}

test/fixtures/nested-options-js-deep-preset/fixture/and-fixture/code.js

@@ -0,0 +1 @@
+'use strict';

test/fixtures/nested-options-js-deep-preset/fixture/and-fixture/options.js

@@ -0,0 +1,8 @@
+module.exports = {
+  presetOptions: {
+    appendExtension: '.mjs'
+  },
+  babelOptions: {
+    presets: ['@babel/preset-react']
+  }
+};