@eslint-community/regexpp 4.12.2: RegExpValidator

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 RegExpValidator in pkg:npm/%40eslint-community/regexpp@4.12.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint-community/regexpp@4.12.2
Demonstrate these symbols/APIs:
  - RegExpValidator

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:4fab487ccb83e29f11b652c92976dbd9608c6ef4286151106a3398d547f9e2d1","contract":["RegExpValidator validates valid regular expression patterns and literals without errors","RegExpValidator throws RegExpSyntaxError with error index on invalid regex syntax","RegExpValidator validates regex flag strings and checks duplicate or invalid flag characters","RegExpValidator fires onCapturingGroupEnter and onCapturingGroupLeave callbacks with group names and boundaries","RegExpValidator fires onQuantifier callback with min, max, and greedy properties","RegExpValidator fires onLookaroundAssertionEnter callback with lookahead and lookbehind assertions","RegExpValidator fires onCharacter and onCharacterClassRange callbacks during AST validation","RegExpValidator supports ECMAScript version constraints and unicodeSets flag v-mode validation"],"goal":"verify RegExpValidator in pkg:npm/%40eslint-community/regexpp@4.12.2","kind":"HOW","packages":["pkg:npm/%40eslint-community/regexpp@4.12.2"],"schemaVersion":1,"symbols":["RegExpValidator"]},"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/%40eslint-community/regexpp@4.12.2"],"schemaVersion":1,"subject":"pkg:npm/%40eslint-community/regexpp@4.12.2","symbols":["RegExpValidator"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-eslint-community-regexpp",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-community-regexpp",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@eslint-community/regexpp": "4.12.2"
      }
    },
    "node_modules/@eslint-community/regexpp": {
      "version": "4.12.2",
      "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.2.tgz",
      "integrity": "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==",
      "license": "MIT",
      "engines": {
        "node": "^12.0.0 || ^14.0.0 || >=16.0.0"
      }
    }
  }
}

{
  "name": "sample-eslint-community-regexpp",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@eslint-community/regexpp": "4.12.2"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify RegExpValidator in pkg:npm/%40eslint-community/regexpp@4.12.2",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40eslint-community/regexpp@4.12.2"
  ],
  "symbols": [
    "RegExpValidator"
  ]
}

import { RegExpValidator, RegExpSyntaxError } from '@eslint-community/regexpp';

/**
 * Validates a regular expression pattern string.
 * @param {string} pattern The regex pattern string (e.g. "^[a-z]+$").
 * @param {object} [flags] Optional regex flags mode (e.g. { unicode: true, unicodeSets: false }).
 * @param {object} [options] Validator configuration options.
 * @returns {boolean} True if pattern is valid.
 */
export function validatePattern(pattern, flags = {}, options = {}) {
  const validator = new RegExpValidator(options);
  validator.validatePattern(pattern, 0, pattern.length, flags);
  return true;
}

/**
 * Validates a full regular expression literal string including delimiters and flags.
 * @param {string} literal The literal string (e.g. "/^[a-z]+$/iu").
 * @param {object} [options] Validator configuration options.
 * @returns {boolean} True if literal is valid.
 */
export function validateLiteral(literal, options = {}) {
  const validator = new RegExpValidator(options);
  validator.validateLiteral(literal, 0, literal.length);
  return true;
}

/**
 * Validates a regular expression flags string.
 * @param {string} flags The flags string (e.g. "gimsuy").
 * @param {object} [options] Validator configuration options.
 * @returns {boolean} True if flags are valid.
 */
export function validateFlags(flags, options = {}) {
  const validator = new RegExpValidator(options);
  validator.validateFlags(flags, 0, flags.length);
  return true;
}

/**
 * Parses and extracts capturing group information from a regular expression pattern.
 * @param {string} pattern The regex pattern string.
 * @param {object} [flags] Optional flags mode (e.g. { unicode: true }).
 * @param {object} [options] Validator options.
 * @returns {Array<{ start: number, name: string|null }>} List of capturing groups.
 */
export function extractCapturingGroups(pattern, flags = { unicode: true }, options = {}) {
  const groups = [];
  const validator = new RegExpValidator({
    ...options,
    onCapturingGroupEnter(start, name) {
      groups.push({ start, name: name ?? null });
    },
  });
  validator.validatePattern(pattern, 0, pattern.length, flags);
  return groups;
}

/**
 * Checks regular expression syntax safely without throwing errors.
 * @param {string} pattern The regex pattern string.
 * @param {object} [flags] Flags options.
 * @param {object} [options] Validator options.
 * @returns {{ valid: boolean, error?: string, index?: number }}
 */
export function checkPatternSyntax(pattern, flags = {}, options = {}) {
  try {
    validatePattern(pattern, flags, options);
    return { valid: true };
  } catch (err) {
    if (err instanceof RegExpSyntaxError) {
      return { valid: false, error: err.message, index: err.index };
    }
    throw err;
  }
}

export { RegExpValidator, RegExpSyntaxError };
export default RegExpValidator;

import assert from 'node:assert/strict';
import { RegExpValidator, RegExpSyntaxError } from '@eslint-community/regexpp';
import {
  validatePattern,
  validateLiteral,
  validateFlags,
  extractCapturingGroups,
  checkPatternSyntax,
} from '../src/index.mjs';

// 1. RegExpValidator validates valid regular expression patterns and literals without errors
{
  const validator = new RegExpValidator();

  // Validate standalone pattern string
  assert.doesNotThrow(() => {
    validator.validatePattern('^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$');
  });

  // Validate full regex literal with flags
  assert.doesNotThrow(() => {
    validator.validateLiteral('/(?<year>\\d{4})-(?<month>\\d{2})-(?<day>\\d{2})/u');
  });

  // Validate via helper wrappers
  assert.equal(validatePattern('^\\d{3}-\\d{2}-\\d{4}$'), true);
  assert.equal(validateLiteral('/^[A-Z][a-z]+$/i'), true);
}

// 2. RegExpValidator throws RegExpSyntaxError with error index on invalid regex syntax
{
  const validator = new RegExpValidator();

  // Unclosed parenthesis
  assert.throws(
    () => validator.validatePattern('(abc'),
    (err) => {
      assert.ok(err instanceof RegExpSyntaxError);
      assert.equal(typeof err.index, 'number');
      assert.ok(err.index >= 0);
      assert.match(err.message, /Invalid regular expression/);
      return true;
    }
  );

  // Invalid capture group identifier
  assert.throws(
    () => validator.validatePattern('(?<123invalid>abc)'),
    RegExpSyntaxError
  );

  // Helper checkPatternSyntax returns structured error object
  const validCheck = checkPatternSyntax('^[a-z]+$');
  assert.deepEqual(validCheck, { valid: true });

  const invalidCheck = checkPatternSyntax('(?<404>foo)');
  assert.equal(invalidCheck.valid, false);
  assert.equal(typeof invalidCheck.index, 'number');
  assert.ok(typeof invalidCheck.error === 'string' && invalidCheck.error.length > 0);
}

// 3. RegExpValidator validates regex flag strings and checks duplicate or invalid flag characters
{
  const validator = new RegExpValidator();

  // Valid flag strings
  assert.doesNotThrow(() => validator.validateFlags('gimsuy'));
  assert.doesNotThrow(() => validator.validateFlags('d'));
  assert.equal(validateFlags('i'), true);

  // Duplicate flag character throws RegExpSyntaxError
  assert.throws(
    () => validator.validateFlags('gimsg'),
    (err) => {
      assert.ok(err instanceof RegExpSyntaxError);
      assert.match(err.message, /Duplicated flag/);
      return true;
    }
  );

  // Unknown flag character throws RegExpSyntaxError
  assert.throws(
    () => validator.validateFlags('gimz'),
    (err) => {
      assert.ok(err instanceof RegExpSyntaxError);
      assert.match(err.message, /Invalid flag/);
      return true;
    }
  );
}

// 4. RegExpValidator fires onCapturingGroupEnter and onCapturingGroupLeave callbacks with group names and boundaries
{
  const enteredGroups = [];
  const leftGroups = [];

  const validator = new RegExpValidator({
    onCapturingGroupEnter(start, name) {
      enteredGroups.push({ start, name: name ?? null });
    },
    onCapturingGroupLeave(start, end, name) {
      leftGroups.push({ start, end, name: name ?? null });
    },
  });

  const pattern = '(?<prefix>[A-Z]{2})-(\\d{4})';
  validator.validatePattern(pattern, 0, pattern.length, { unicode: true });

  assert.deepEqual(enteredGroups, [
    { start: 0, name: 'prefix' },
    { start: 20, name: null },
  ]);

  assert.deepEqual(leftGroups, [
    { start: 0, end: 19, name: 'prefix' },
    { start: 20, end: 27, name: null },
  ]);

  // Helper extractCapturingGroups
  const extracted = extractCapturingGroups('(?<area>\\d{3})-(?<local>\\d{4})');
  assert.deepEqual(extracted, [
    { start: 0, name: 'area' },
    { start: 15, name: "local" },
  ]);
}

// 5. RegExpValidator fires onQuantifier callback with min, max, and greedy properties
{
  const quantifiers = [];

  const validator = new RegExpValidator({
    onQuantifier(start, end, min, max, greedy) {
      quantifiers.push({ start, end, min, max, greedy });
    },
  });

  const pattern = 'a{2,5}b+?c*d?';
  validator.validatePattern(pattern, 0, pattern.length, { unicode: true });

  assert.deepEqual(quantifiers, [
    { start: 1, end: 6, min: 2, max: 5, greedy: true },
    { start: 7, end: 9, min: 1, max: Infinity, greedy: false },
    { start: 10, end: 11, min: 0, max: Infinity, greedy: true },
    { start: 12, end: 13, min: 0, max: 1, greedy: true },
  ]);
}

// 6. RegExpValidator fires onLookaroundAssertionEnter callback with lookahead and lookbehind assertions
{
  const lookarounds = [];

  const validator = new RegExpValidator({
    ecmaVersion: 2024,
    onLookaroundAssertionEnter(start, kind, negate) {
      lookarounds.push({ start, kind, negate });
    },
  });

  // (?=positive_ahead), (?!negative_ahead), (?<=positive_behind), (?<!negative_behind)
  const pattern = '(?=foo)(?!bar)(?<=baz)(?<!qux)';
  validator.validatePattern(pattern, 0, pattern.length, { unicode: true });

  assert.deepEqual(lookarounds, [
    { start: 0, kind: 'lookahead', negate: false },
    { start: 7, kind: 'lookahead', negate: true },
    { start: 14, kind: 'lookbehind', negate: false },
    { start: 22, kind: 'lookbehind', negate: true },
  ]);
}

// 7. RegExpValidator fires onCharacter and onCharacterClassRange callbacks during AST validation
{
  const characters = [];
  const ranges = [];

  const validator = new RegExpValidator({
    onCharacter(start, end, value) {
      characters.push({ start, end, char: String.fromCodePoint(value) });
    },
    onCharacterClassRange(start, end, min, max) {
      ranges.push({
        start,
        end,
        min: String.fromCodePoint(min),
        max: String.fromCodePoint(max),
      });
    },
  });

  validator.validatePattern('abc', 0, 3, { unicode: true });
  assert.deepEqual(characters, [
    { start: 0, end: 1, char: 'a' },
    { start: 1, end: 2, char: 'b' },
    { start: 2, end: 3, char: 'c' },
  ]);

  validator.validatePattern('[a-z0-9]', 0, 8, { unicode: true });
  assert.deepEqual(ranges, [
    { start: 1, end: 4, min: 'a', max: 'z' },
    { start: 4, end: 7, min: '0', max: '9' },
  ]);
}

// 8. RegExpValidator supports ECMAScript version constraints and unicodeSets flag v-mode validation
{
  // ES5 mode rejects lookbehind assertions
  const es5Validator = new RegExpValidator({ ecmaVersion: 5 });
  assert.throws(
    () => es5Validator.validatePattern('(?<=foo)bar'),
    RegExpSyntaxError
  );

  // unicodeSets mode (v flag) validates character class set operations
  const intersections = [];
  const subtractions = [];

  const vModeValidator = new RegExpValidator({
    ecmaVersion: 2024,
    onClassIntersection(start, end) {
      intersections.push({ start, end });
    },
    onClassSubtraction(start, end) {
      subtractions.push({ start, end });
    },
  });

  // Intersection: [[a-z]&&[d-g]]
  assert.doesNotThrow(() => {
    vModeValidator.validatePattern('[[a-z]&&[d-g]]', 0, 14, { unicodeSets: true });
  });
  assert.equal(intersections.length, 1);

  // Subtraction: [[a-z]--[d-g]]
  assert.doesNotThrow(() => {
    vModeValidator.validatePattern('[[a-z]--[d-g]]', 0, 14, { unicodeSets: true });
  });
  assert.equal(subtractions.length, 1);
}

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