@babel/helper-plugin-utils 7.29.7

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40babel/helper-plugin-utils@7.29.7
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40babel/helper-plugin-utils@7.29.7

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:6c5c5180b98084ea6894e794dae98a12d0b930be982370735e8b24387e47fdce","contract":["declare wraps a plugin factory function and passes through api, options, and dirname","declare polyfills missing targets method returning an empty object","declare polyfills missing assumption method returning undefined","declare polyfills missing addExternalDependency method as a callable no-op","declare polyfills assertVersion which throws BABEL_VERSION_UNSUPPORTED when version is incompatible","declare preserves pre-existing api methods without overwriting them","declare defaults options parameter to an empty object when omitted or undefined","declarePreset functions as an exact alias of declare"],"goal":"verify pkg:npm/%40babel/helper-plugin-utils@7.29.7","kind":"HOW","packages":["pkg:npm/%40babel/helper-plugin-utils@7.29.7"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40babel/helper-plugin-utils@7.29.7"],"schemaVersion":1,"subject":"pkg:npm/%40babel/helper-plugin-utils@7.29.7","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-babel-helper-plugin-utils",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-babel-helper-plugin-utils",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@babel/helper-plugin-utils": "7.29.7"
      }
    },
    "node_modules/@babel/helper-plugin-utils": {
      "version": "7.29.7",
      "resolved": "https://registry.npmjs.org/@babel/helper-plugin-utils/-/helper-plugin-utils-7.29.7.tgz",
      "integrity": "sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==",
      "license": "MIT",
      "engines": {
        "node": ">=6.9.0"
      }
    }
  }
}

{
  "name": "sample-babel-helper-plugin-utils",
  "version": "1.0.0",
  "description": "Minimal sample verifying @babel/helper-plugin-utils",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@babel/helper-plugin-utils": "7.29.7"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40babel/helper-plugin-utils@7.29.7",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40babel/helper-plugin-utils@7.29.7"
  ]
}

const { declare, declarePreset } = require('@babel/helper-plugin-utils');

/**
 * Declares a Babel plugin using helper-plugin-utils.
 * @param {Function} builder - The plugin builder function (api, options, dirname) => pluginObject
 * @returns {Function} Wrapped plugin factory function
 */
function createPlugin(builder) {
  return declare(builder);
}

/**
 * Declares a Babel preset using helper-plugin-utils.
 * @param {Function} builder - The preset builder function (api, options, dirname) => presetObject
 * @returns {Function} Wrapped preset factory function
 */
function createPreset(builder) {
  return declarePreset(builder);
}

/**
 * Invokes a declared plugin or preset factory with the given API and options.
 * @param {Function} factory - The declared plugin or preset factory function
 * @param {object} api - The Babel API object (or minimal API object)
 * @param {object} [options] - Plugin configuration options
 * @param {string} [dirname] - Directory name context
 * @returns {*} The result produced by the builder
 */
function invokePluginFactory(factory, api, options, dirname) {
  return factory(api, options, dirname);
}

module.exports = {
  createPlugin,
  createPreset,
  invokePluginFactory,
  declare,
  declarePreset,
};

import assert from 'node:assert';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  createPlugin,
  createPreset,
  invokePluginFactory,
  declare,
  declarePreset,
} = require('../src/index.js');

async function runContract() {
  // 1. declare wraps a plugin factory function and passes through api, options, and dirname
  let builderExecuted = false;
  const plugin = createPlugin((api, options, dirname) => {
    builderExecuted = true;
    return {
      name: 'transform-sample-custom',
      api,
      options,
      dirname,
    };
  });

  const mockApi = {
    version: '7.29.7',
  };
  const optionsInput = { loose: true, legacy: false };
  const dirnameInput = '/mock/project/path';

  const pluginInstance = invokePluginFactory(plugin, mockApi, optionsInput, dirnameInput);

  assert.strictEqual(builderExecuted, true, 'builder function should be invoked');
  assert.strictEqual(pluginInstance.name, 'transform-sample-custom', 'plugin name should match');
  assert.strictEqual(pluginInstance.dirname, dirnameInput, 'dirname should pass through');
  assert.deepStrictEqual(pluginInstance.options, optionsInput, 'options should pass through');

  // 2. declare polyfills missing targets method returning an empty object
  assert.strictEqual(typeof pluginInstance.api.targets, 'function', 'targets method should be polyfilled');
  assert.deepStrictEqual(pluginInstance.api.targets(), {}, 'polyfilled targets should return an empty object');

  // 3. declare polyfills missing assumption method returning undefined
  assert.strictEqual(typeof pluginInstance.api.assumption, 'function', 'assumption method should be polyfilled');
  assert.strictEqual(pluginInstance.api.assumption('pureGetters'), undefined, 'polyfilled assumption should return undefined');

  // 4. declare polyfills missing addExternalDependency method as a callable no-op
  assert.strictEqual(typeof pluginInstance.api.addExternalDependency, 'function', 'addExternalDependency method should be polyfilled');
  assert.strictEqual(pluginInstance.api.addExternalDependency('some-config.json'), undefined, 'addExternalDependency should be callable no-op');

  // 5. declare polyfills assertVersion which throws BABEL_VERSION_UNSUPPORTED when version is incompatible
  assert.strictEqual(typeof pluginInstance.api.assertVersion, 'function', 'assertVersion method should be polyfilled');
  assert.throws(
    () => {
      pluginInstance.api.assertVersion('^8.0.0');
    },
    (err) => {
      return err.code === 'BABEL_VERSION_UNSUPPORTED';
    },
    'assertVersion should throw BABEL_VERSION_UNSUPPORTED for incompatible version range'
  );

  // 6. declare preserves pre-existing api methods without overwriting them
  const customTargets = { node: '18.0.0' };
  const customApi = {
    version: '7.29.7',
    targets: () => customTargets,
    assumption: (name) => name === 'noDocumentAll',
    addExternalDependency: (file) => `registered:${file}`,
    assertVersion: (_range) => true,
  };

  const customPlugin = createPlugin((api) => api);
  const receivedApi = invokePluginFactory(customPlugin, customApi);

  assert.strictEqual(receivedApi.targets(), customTargets, 'custom targets method should be preserved');
  assert.strictEqual(receivedApi.assumption('noDocumentAll'), true, 'custom assumption method should be preserved');
  assert.strictEqual(receivedApi.assumption('unknown'), false, 'custom assumption method should return expected value');
  assert.strictEqual(receivedApi.addExternalDependency('dep.js'), 'registered:dep.js', 'custom addExternalDependency should be preserved');
  assert.strictEqual(receivedApi.assertVersion('^7.0.0'), true, 'custom assertVersion should be preserved');

  // 7. declare defaults options parameter to an empty object when omitted or undefined
  const optionsTestingPlugin = createPlugin((_api, options) => options);
  const defaultOptionsWhenOmitted = invokePluginFactory(optionsTestingPlugin, mockApi);
  const defaultOptionsWhenNull = invokePluginFactory(optionsTestingPlugin, mockApi, null);
  const defaultOptionsWhenUndefined = invokePluginFactory(optionsTestingPlugin, mockApi, undefined);

  assert.deepStrictEqual(defaultOptionsWhenOmitted, {}, 'options should default to empty object when omitted');
  assert.deepStrictEqual(defaultOptionsWhenNull, {}, 'options should default to empty object when null');
  assert.deepStrictEqual(defaultOptionsWhenUndefined, {}, 'options should default to empty object when undefined');

  // 8. declarePreset functions as an exact alias of declare
  assert.strictEqual(declarePreset, declare, 'declarePreset should be an exact alias of declare');

  const preset = createPreset((api, options) => ({ presetOption: options.presetOption, polyfilled: typeof api.targets === 'function' }));
  const presetResult = invokePluginFactory(preset, mockApi, { presetOption: 'active' });

  assert.strictEqual(presetResult.presetOption, 'active', 'preset options should be passed');
  assert.strictEqual(presetResult.polyfilled, true, 'preset api should receive polyfills');

  console.log('Contract tests passed successfully.');
}

runContract().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});