@jest/pattern 30.4.0: TestPathPatterns

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 @jest/pattern.TestPathPatterns in pkg:npm/%40jest/pattern@30.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40jest/pattern@30.4.0
Demonstrate these symbols/APIs:
  - @jest/pattern.TestPathPatterns

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:4ebdb7a6bdd679b8cee64bb5f9dfe994f4ccfce5ff29d4e903afd7df8ad60334","contract":["TestPathPatterns can be constructed with empty patterns and reports isSet false, isValid true, toPretty empty, and serializes via toJSON","TestPathPatterns can be constructed with multiple pattern strings and reports isSet true, toPretty joined by pipe, and toJSON with patterns array","TestPathPatterns detects invalid regular expressions and reports isValid false","TestPathPatterns.toExecutor produces an executor that validates paths relative to rootDir","TestPathPatterns.toExecutor matches leading dot-slash patterns anchored to the root directory relative path"],"goal":"verify @jest/pattern.TestPathPatterns in pkg:npm/%40jest/pattern@30.4.0","kind":"HOW","packages":["pkg:npm/%40jest/pattern@30.4.0"],"schemaVersion":1,"symbols":["@jest/pattern.TestPathPatterns"]},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40jest/pattern@30.4.0"],"schemaVersion":1,"subject":"pkg:npm/%40jest/pattern@30.4.0","symbols":["@jest/pattern.TestPathPatterns"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-jest-pattern",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-jest-pattern",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@jest/pattern": "30.4.0"
      }
    },
    "node_modules/@jest/pattern": {
      "version": "30.4.0",
      "resolved": "https://registry.npmjs.org/@jest/pattern/-/pattern-30.4.0.tgz",
      "integrity": "sha512-RAWn3+f9u8BsHijKJ71uHcFp6vmyEt6VvoWXkl6hKF3qVIuWNmudVjg12DlBPGup/frIl5UcUlH5HfEuvHpEXg==",
      "license": "MIT",
      "dependencies": {
        "@types/node": "*",
        "jest-regex-util": "30.4.0"
      },
      "engines": {
        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
      }
    },
    "node_modules/@types/node": {
      "version": "26.4.1",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.4.1.tgz",
      "integrity": "sha512-k97ENvZWtvA6yqz5/FS6a7duDgOPEeOQOc2iKS/nY6mX6qJUKtLnWzQS+Xj6tXweyj6ZcTAK2Qecetnvi9nCLA==",
      "license": "MIT",
      "dependencies": {
        "undici-types": "~8.3.0"
      }
    },
    "node_modules/jest-regex-util": {
      "version": "30.4.0",
      "resolved": "https://registry.npmjs.org/jest-regex-util/-/jest-regex-util-30.4.0.tgz",
      "integrity": "sha512-mWlvLviKIgIQ8VCuM1xRdD0TWp3zlzionlmDBjuXVBs+VkmXq6FgW9T4Emr7oGz/Rk6feDCGyiugolcQEyp3mg==",
      "license": "MIT",
      "engines": {
        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
      }
    },
    "node_modules/undici-types": {
      "version": "8.3.0",
      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz",
      "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-jest-pattern",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for @jest/pattern TestPathPatterns",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "@jest/pattern": "30.4.0"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify @jest/pattern.TestPathPatterns in pkg:npm/%40jest/pattern@30.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40jest/pattern@30.4.0"
  ],
  "symbols": [
    "@jest/pattern.TestPathPatterns"
  ]
}

const { TestPathPatterns, TestPathPatternsExecutor } = require('@jest/pattern');

/**
 * Creates a TestPathPatterns instance from an array of pattern strings.
 * @param {string[]} patterns
 * @returns {TestPathPatterns}
 */
function createPathPatterns(patterns = []) {
  return new TestPathPatterns(patterns);
}

/**
 * Creates a TestPathPatternsExecutor instance for the given patterns and root directory.
 * @param {string[]} patterns
 * @param {string} rootDir
 * @returns {TestPathPatternsExecutor}
 */
function createPathMatcher(patterns, rootDir) {
  const testPatterns = createPathPatterns(patterns);
  return testPatterns.toExecutor({ rootDir });
}

/**
 * Checks whether all patterns in the array are valid regular expressions.
 * @param {string[]} patterns
 * @returns {boolean}
 */
function validatePatterns(patterns) {
  const testPatterns = createPathPatterns(patterns);
  return testPatterns.isValid();
}

/**
 * Formats patterns into a pipe-delimited string.
 * @param {string[]} patterns
 * @returns {string}
 */
function formatPatterns(patterns) {
  const testPatterns = createPathPatterns(patterns);
  return testPatterns.toPretty();
}

/**
 * Tests whether an absolute path matches the given patterns relative to rootDir.
 * @param {string[]} patterns
 * @param {string} rootDir
 * @param {string} absPath
 * @returns {boolean}
 */
function matchesPattern(patterns, rootDir, absPath) {
  const executor = createPathMatcher(patterns, rootDir);
  return executor.isMatch(absPath);
}

module.exports = {
  TestPathPatterns,
  TestPathPatternsExecutor,
  createPathPatterns,
  createPathMatcher,
  validatePatterns,
  formatPatterns,
  matchesPattern,
};

const assert = require('node:assert');
const {
  TestPathPatterns,
  TestPathPatternsExecutor,
  createPathPatterns,
  createPathMatcher,
  validatePatterns,
  formatPatterns,
  matchesPattern,
} = require('../src/index.js');

// 1. TestPathPatterns can be constructed with empty patterns and reports isSet false, isValid true, toPretty empty, and serializes via toJSON
{
  const empty = createPathPatterns([]);
  assert.strictEqual(empty instanceof TestPathPatterns, true);
  assert.strictEqual(empty.isSet(), false);
  assert.strictEqual(empty.isValid(), true);
  assert.strictEqual(empty.toPretty(), '');
  assert.deepStrictEqual(empty.toJSON(), {
    patterns: [],
    type: 'TestPathPatterns',
  });
}

// 2. TestPathPatterns can be constructed with multiple pattern strings and reports isSet true, toPretty joined by pipe, and toJSON with patterns array
{
  const patterns = ['tests/unit/.*\\.test\\.js', 'src/services/.*'];
  const testPatterns = createPathPatterns(patterns);
  assert.strictEqual(testPatterns.isSet(), true);
  assert.strictEqual(testPatterns.isValid(), true);
  assert.strictEqual(testPatterns.toPretty(), 'tests/unit/.*\\.test\\.js|src/services/.*');
  assert.strictEqual(formatPatterns(patterns), 'tests/unit/.*\\.test\\.js|src/services/.*');
  assert.deepStrictEqual(testPatterns.toJSON(), {
    patterns: ['tests/unit/.*\\.test\\.js', 'src/services/.*'],
    type: 'TestPathPatterns',
  });
}

// 3. TestPathPatterns detects invalid regular expressions and reports isValid false
{
  const invalid = createPathPatterns(['[unterminated-regex(']);
  assert.strictEqual(invalid.isSet(), true);
  assert.strictEqual(invalid.isValid(), false);
  assert.strictEqual(validatePatterns(['[unterminated-regex(']), false);

  const valid = createPathPatterns(['valid/path/.*']);
  assert.strictEqual(valid.isValid(), true);
  assert.strictEqual(validatePatterns(['valid/path/.*']), true);
}

// 4. TestPathPatterns.toExecutor produces an executor that validates paths relative to rootDir
{
  const rootDir = '/workspace/test-project';
  const patterns = ['src/components/.*', 'tests/.*\\.spec\\.js'];
  const executor = createPathMatcher(patterns, rootDir);

  assert.strictEqual(executor instanceof TestPathPatternsExecutor, true);
  assert.strictEqual(executor.isSet(), true);
  assert.strictEqual(executor.isValid(), true);
  assert.strictEqual(executor.toPretty(), 'src/components/.*|tests/.*\\.spec\\.js');

  // Matches path within rootDir conforming to patterns
  assert.strictEqual(executor.isMatch('/workspace/test-project/src/components/Modal.jsx'), true);
  assert.strictEqual(executor.isMatch('/workspace/test-project/tests/Button.spec.js'), true);

  // Does not match non-matching relative path within rootDir
  assert.strictEqual(executor.isMatch('/workspace/test-project/docs/api.md'), false);
  assert.strictEqual(executor.isMatch('/workspace/test-project/src/utils/calc.js'), false);

  assert.strictEqual(matchesPattern(patterns, rootDir, '/workspace/test-project/src/components/Modal.jsx'), true);
  assert.strictEqual(matchesPattern(patterns, rootDir, '/workspace/test-project/docs/api.md'), false);

  // Empty patterns matches any path
  const emptyExecutor = createPathMatcher([], rootDir);
  assert.strictEqual(emptyExecutor.isMatch('/workspace/test-project/anything.js'), true);
  assert.strictEqual(emptyExecutor.isMatch('/outside/workspace/other.js'), true);
}

// 5. TestPathPatterns.toExecutor matches leading dot-slash patterns anchored to the root directory relative path
{
  const rootDir = '/workspace/test-project';
  const dotSlashExecutor = createPathMatcher(['./src/api'], rootDir);

  // Matches relative path starting with src/api (anchored at start by ^)
  assert.strictEqual(dotSlashExecutor.isMatch('/workspace/test-project/src/api/client.js'), true);
  // Does not match when src/api is not at the root of relative path
  assert.strictEqual(dotSlashExecutor.isMatch('/workspace/test-project/nested/src/api/client.js'), false);

  assert.strictEqual(matchesPattern(['./src/api'], rootDir, '/workspace/test-project/src/api/client.js'), true);
  assert.strictEqual(matchesPattern(['./src/api'], rootDir, '/workspace/test-project/nested/src/api/client.js'), false);
}

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