minimatch 10.2.6: verify AST

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/minimatch@10.2.6 AST
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/minimatch@10.2.6
Demonstrate these symbols/APIs:
  - AST
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:32f48bda05fc6cc9f1da01937e178e8640c8a1c75ecc44c8e114779ef8f0db85","constraints":{"executionContext":"node"},"contract":["minimatch.AST.fromGlob parses glob patterns with extglobs into an abstract syntax tree structure","minimatch.AST.prototype.toString reconstructs the original glob pattern from the parsed AST","minimatch.AST.prototype.toJSON serializes the nested AST tree representation into JSON array structure","minimatch.AST.prototype.toMMPattern compiles the AST into a regular expression matcher or literal pattern string","minimatch.AST.prototype.toRegExpSource returns the regex source tuple and magic detection flags for the AST"],"goal":"verify pkg:npm/minimatch@10.2.6 AST","kind":"HOW","packages":["pkg:npm/minimatch@10.2.6"],"schemaVersion":1,"symbols":["AST"]},"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/minimatch@10.2.6"],"schemaVersion":1,"symbols":["AST"],"verifierAdapter":"node-typescript@1"}

{
  "name": "minimatch-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "minimatch-sample",
      "version": "1.0.0",
      "dependencies": {
        "minimatch": "10.2.6"
      }
    },
    "node_modules/balanced-match": {
      "version": "4.0.4",
      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
      "license": "MIT",
      "engines": {
        "node": "18 || 20 || >=22"
      }
    },
    "node_modules/brace-expansion": {
      "version": "5.0.9",
      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
      "integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
      "license": "MIT",
      "dependencies": {
        "balanced-match": "^4.0.2"
      },
      "engines": {
        "node": "20 || >=22"
      }
    },
    "node_modules/minimatch": {
      "version": "10.2.6",
      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
      "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
      "license": "BlueOak-1.0.0",
      "dependencies": {
        "brace-expansion": "^5.0.8"
      },
      "engines": {
        "node": "18 || 20 || >=22"
      },
      "funding": {
        "url": "https://github.com/sponsors/isaacs"
      }
    }
  }
}

{
  "name": "minimatch-sample",
  "version": "1.0.0",
  "dependencies": {
    "minimatch": "10.2.6"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/minimatch@10.2.6 AST",
  "kind": "HOW",
  "packages": [
    "pkg:npm/minimatch@10.2.6"
  ],
  "symbols": [
    "AST"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const { AST } = require('minimatch');

/**
 * Parses a glob pattern into an Abstract Syntax Tree (AST).
 *
 * @param {string} pattern - Glob pattern string.
 * @param {object} [options] - Minimatch configuration options.
 * @returns {AST} Parsed AST node representing the root of the pattern.
 */
function parseGlobAST(pattern, options) {
  return AST.fromGlob(pattern, options);
}

/**
 * Reconstructs a glob pattern string from an AST instance.
 *
 * @param {AST} ast - AST node instance.
 * @returns {string} Stringified glob pattern.
 */
function stringifyAST(ast) {
  return ast.toString();
}

/**
 * Serializes an AST into a structured JSON array.
 *
 * @param {AST} ast - AST node instance.
 * @returns {unknown[]} Nested array representing the AST structure.
 */
function serializeASTToJSON(ast) {
  return ast.toJSON();
}

/**
 * Compiles an AST node into a Minimatch regular expression or literal pattern string.
 *
 * @param {AST} ast - AST node instance.
 * @returns {RegExp|string} Compiled regular expression matcher or literal pattern string.
 */
function compileASTPattern(ast) {
  return ast.toMMPattern();
}

/**
 * Extracts regular expression source information and magic metadata from an AST node.
 *
 * @param {AST} ast - AST node instance.
 * @param {boolean} [allowDot] - Whether to allow leading dots in wildcard matches.
 * @returns {[string, string, boolean, boolean]} Tuple containing [regexPattern, regexBody, hasMagic, uflag].
 */
function getASTRegExpInfo(ast, allowDot) {
  return ast.toRegExpSource(allowDot);
}

module.exports = {
  parseGlobAST,
  stringifyAST,
  serializeASTToJSON,
  compileASTPattern,
  getASTRegExpInfo,
};

const assert = require('node:assert/strict');
const { AST } = require('minimatch');
const {
  parseGlobAST,
  stringifyAST,
  serializeASTToJSON,
  compileASTPattern,
  getASTRegExpInfo,
} = require('../src/index.js');

// Contract 1: minimatch.AST.fromGlob parses glob patterns with extglobs into an abstract syntax tree structure
{
  const ast = parseGlobAST('@(foo|bar)/**/*.js');
  assert.ok(ast instanceof AST);
  assert.strictEqual(ast.type, null);
  assert.strictEqual(ast.depth, 0);
  assert.strictEqual(ast.hasMagic, true);

  const directAst = AST.fromGlob('@(foo|bar)/**/*.js');
  assert.ok(directAst instanceof AST);
}

// Contract 2: minimatch.AST.prototype.toString reconstructs the original glob pattern from the parsed AST
{
  const pattern1 = '+([0-9])/*.{ts,tsx}';
  const ast1 = parseGlobAST(pattern1);
  assert.strictEqual(stringifyAST(ast1), pattern1);
  assert.strictEqual(ast1.toString(), pattern1);

  const pattern2 = 'lib/**/*.min.js';
  const ast2 = parseGlobAST(pattern2);
  assert.strictEqual(stringifyAST(ast2), pattern2);
}

// Contract 3: minimatch.AST.prototype.toJSON serializes the nested AST tree representation into JSON array structure
{
  const ast = parseGlobAST('*(a|b)');
  const json = serializeASTToJSON(ast);
  assert.ok(Array.isArray(json));
  assert.deepStrictEqual(json, ast.toJSON());
  assert.deepStrictEqual(json, [[], ['*', [[], 'a'], [[], 'b']], {}]);
}

// Contract 4: minimatch.AST.prototype.toMMPattern compiles the AST into a regular expression matcher or literal pattern string
{
  const astRegex = parseGlobAST('@(core|lib)/*.js');
  const mmPatRegex = compileASTPattern(astRegex);
  assert.ok(mmPatRegex instanceof RegExp);
  assert.strictEqual(mmPatRegex.test('core/main.js'), true);
  assert.strictEqual(mmPatRegex.test('lib/utils.js'), true);
  assert.strictEqual(mmPatRegex.test('other/main.js'), false);

  const astLiteral = parseGlobAST('docs/readme.txt');
  const mmPatLiteral = compileASTPattern(astLiteral);
  assert.strictEqual(typeof mmPatLiteral, 'string');
  assert.strictEqual(mmPatLiteral, 'docs/readme.txt');
}

// Contract 5: minimatch.AST.prototype.toRegExpSource returns the regex source tuple and magic detection flags for the AST
{
  const ast = parseGlobAST('*.test.js');
  const [reSource, reBody, hasMagic, uflag] = getASTRegExpInfo(ast);
  assert.strictEqual(typeof reSource, 'string');
  assert.strictEqual(typeof reBody, 'string');
  assert.strictEqual(hasMagic, true);
  assert.strictEqual(typeof uflag, 'boolean');

  const directInfo = ast.toRegExpSource();
  assert.deepStrictEqual([reSource, reBody, hasMagic, uflag], directInfo);
}