@babel/helper-validator-option 8.0.0

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-validator-option@8.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40babel/helper-validator-option@8.0.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

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:eeb2845ee39e6c46e8dec76fe215875cc3c7e0a268c686cb8973275ac997b999","constraints":{"executionContext":"node"},"contract":["OptionValidator constructor initializes descriptor and formatMessage prefixes error messages with descriptor","validateTopLevelOptions validates allowed options against TopLevelOptionShape and throws formatted error with suggestion for invalid keys","validateBooleanOption returns given boolean value, returns defaultValue when undefined, and throws when value is not a boolean","validateStringOption returns given string value, returns defaultValue when undefined, and throws when value is not a string","invariant throws formatted error when condition is falsy and passes when truthy","findSuggestion finds the candidate string with minimal Levenshtein distance"],"goal":"verify pkg:npm/%40babel/helper-validator-option@8.0.0","kind":"HOW","packages":["pkg:npm/%40babel/helper-validator-option@8.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40babel/helper-validator-option@8.0.0"],"schemaVersion":1,"subject":"pkg:npm/%40babel/helper-validator-option@8.0.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-babel-helper-validator-option",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-babel-helper-validator-option",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@babel/helper-validator-option": "8.0.0"
      }
    },
    "node_modules/@babel/helper-validator-option": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/@babel/helper-validator-option/-/helper-validator-option-8.0.0.tgz",
      "integrity": "sha512-U4Dybxh4WESWHt5XhBeExi4DrY0/DNK1aHpQbsrQXCUbFHuMweT0TpLEWKvaraV2Y6fS+ZXunsZ8zIuZIgvF2Q==",
      "license": "MIT",
      "engines": {
        "node": "^22.18.0 || >=24.11.0"
      }
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40babel/helper-validator-option@8.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40babel/helper-validator-option@8.0.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

const {
  OptionValidator,
  findSuggestion,
} = require('@babel/helper-validator-option');

/**
 * Creates an OptionValidator instance with the specified descriptor.
 * @param {string} descriptor - The descriptor name prefix.
 * @returns {OptionValidator}
 */
function createOptionValidator(descriptor) {
  return new OptionValidator(descriptor);
}

/**
 * Validates options object against allowed keys defined in allowedShape.
 * @param {OptionValidator} validator - The OptionValidator instance.
 * @param {object} options - User options object.
 * @param {object} allowedShape - Shape defining allowed options.
 */
function validateOptions(validator, options, allowedShape) {
  validator.validateTopLevelOptions(options, allowedShape);
}

/**
 * Validates a boolean option value.
 * @param {OptionValidator} validator - The OptionValidator instance.
 * @param {string} name - Option name.
 * @param {boolean} [value] - Option value.
 * @param {boolean} [defaultValue] - Default fallback value.
 * @returns {boolean}
 */
function validateBoolean(validator, name, value, defaultValue) {
  return validator.validateBooleanOption(name, value, defaultValue);
}

/**
 * Validates a string option value.
 * @param {OptionValidator} validator - The OptionValidator instance.
 * @param {string} name - Option name.
 * @param {string} [value] - Option value.
 * @param {string} [defaultValue] - Default fallback value.
 * @returns {string}
 */
function validateString(validator, name, value, defaultValue) {
  return validator.validateStringOption(name, value, defaultValue);
}

/**
 * Asserts invariant condition on the validator.
 * @param {OptionValidator} validator - The OptionValidator instance.
 * @param {boolean} condition - Invariant condition.
 * @param {string} message - Invariant failure message.
 */
function assertInvariant(validator, condition, message) {
  validator.invariant(condition, message);
}

/**
 * Finds the closest candidate match using Levenshtein distance.
 * @param {string} query - Target string.
 * @param {string[]} candidates - Array of candidate strings.
 * @returns {string}
 */
function getClosestSuggestion(query, candidates) {
  return findSuggestion(query, candidates);
}

module.exports = {
  createOptionValidator,
  validateOptions,
  validateBoolean,
  validateString,
  assertInvariant,
  getClosestSuggestion,
  OptionValidator,
  findSuggestion,
};

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

const require = createRequire(import.meta.url);
const {
  createOptionValidator,
  validateOptions,
  validateBoolean,
  validateString,
  assertInvariant,
  getClosestSuggestion,
  OptionValidator,
  findSuggestion,
} = require('../src/index.js');

async function runContract() {
  // 1. OptionValidator constructor initializes descriptor and formatMessage prefixes error messages with descriptor
  const validator = createOptionValidator('MyPlugin');
  assert.strictEqual(validator.descriptor, 'MyPlugin', 'descriptor should match initialized string');
  assert.strictEqual(
    validator.formatMessage('test message'),
    'MyPlugin: test message',
    'formatMessage should prefix with descriptor'
  );

  // 2. validateTopLevelOptions validates allowed options against TopLevelOptionShape and throws formatted error with suggestion for invalid keys
  const allowedShape = { target: true, loose: false, modules: 'auto' };
  assert.doesNotThrow(() => {
    validateOptions(validator, { target: 'es6', loose: true }, allowedShape);
  }, 'valid options should not throw');

  assert.throws(
    () => {
      validateOptions(validator, { targt: 'es6' }, allowedShape);
    },
    {
      name: 'Error',
      message: /MyPlugin: 'targt' is not a valid top-level option\.\n- Did you mean 'target'\?/,
    },
    'invalid option should throw with suggestion'
  );

  // 3. validateBooleanOption returns given boolean value, returns defaultValue when undefined, and throws when value is not a boolean
  assert.strictEqual(validateBoolean(validator, 'loose', true, false), true, 'should return true when value is true');
  assert.strictEqual(validateBoolean(validator, 'loose', false, true), false, 'should return false when value is false');
  assert.strictEqual(validateBoolean(validator, 'loose', undefined, true), true, 'should return defaultValue true when value is undefined');
  assert.strictEqual(validateBoolean(validator, 'loose', undefined, false), false, 'should return defaultValue false when value is undefined');
  assert.strictEqual(validateBoolean(validator, 'loose', undefined, undefined), undefined, 'should return undefined defaultValue when undefined');

  assert.throws(
    () => {
      validateBoolean(validator, 'loose', 'not-a-bool');
    },
    {
      name: 'Error',
      message: /MyPlugin: 'loose' option must be a boolean\./,
    },
    'non-boolean value should throw'
  );

  // 4. validateStringOption returns given string value, returns defaultValue when undefined, and throws when value is not a string
  assert.strictEqual(validateString(validator, 'module', 'commonjs', 'auto'), 'commonjs', 'should return string value');
  assert.strictEqual(validateString(validator, 'module', undefined, 'auto'), 'auto', 'should return defaultValue when undefined');
  assert.strictEqual(validateString(validator, 'module', undefined, undefined), undefined, 'should return undefined when no default');

  assert.throws(
    () => {
      validateString(validator, 'module', 123);
    },
    {
      name: 'Error',
      message: /MyPlugin: 'module' option must be a string\./,
    },
    'non-string value should throw'
  );

  // 5. invariant throws formatted error when condition is falsy and passes when truthy
  assert.doesNotThrow(() => {
    assertInvariant(validator, true, 'should not fail');
  }, 'truthy condition should not throw');

  assert.throws(
    () => {
      assertInvariant(validator, false, 'custom invariant condition failed');
    },
    {
      name: 'Error',
      message: 'MyPlugin: custom invariant condition failed',
    },
    'falsy condition should throw formatted error'
  );

  // 6. findSuggestion finds the candidate string with minimal Levenshtein distance
  assert.strictEqual(getClosestSuggestion('targt', ['target', 'source', 'output']), 'target', 'should find target');
  assert.strictEqual(getClosestSuggestion('moudles', ['targets', 'modules', 'loose']), 'modules', 'should find modules');
  assert.strictEqual(findSuggestion('looze', ['loose', 'strict', 'minify']), 'loose', 'should find loose');

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

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