micromatch 4.0.8: matcher

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 micromatch.matcher in pkg:npm/micromatch@4.0.8
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/micromatch@4.0.8
Demonstrate these symbols/APIs:
  - micromatch.matcher

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:3d61edc60194c75c1e3647624ef11b1a0b1dbb64034e78883850edd522432314","contract":["micromatch.matcher returns a compiled function that evaluates whether a string matches the glob pattern","micromatch.matcher supports globstar patterns for matching nested directory structures","micromatch.matcher supports arrays of glob patterns","micromatch.matcher supports pattern negations and ignore options","micromatch.matcher supports options including nocase, dot, and basename matching","micromatch.matcher returns a detailed result object instead of a boolean when a truthy returnObject argument is supplied","Passing micromatch.matcher directly to Array.prototype.filter passes non-zero index as returnObject resulting in truthy objects; wrapping the call preserves boolean filtering","micromatch.matcher throws a TypeError when pattern is null or undefined"],"goal":"verify micromatch.matcher in pkg:npm/micromatch@4.0.8","kind":"HOW","packages":["pkg:npm/micromatch@4.0.8"],"schemaVersion":1,"symbols":["micromatch.matcher"]},"contractCommand":["node","test/contract.js"],"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/micromatch@4.0.8"],"schemaVersion":1,"subject":"pkg:npm/micromatch@4.0.8","symbols":["micromatch.matcher"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-micromatch-matcher",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-micromatch-matcher",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "micromatch": "4.0.8"
      }
    },
    "node_modules/braces": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
      "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
      "license": "MIT",
      "dependencies": {
        "fill-range": "^7.1.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/fill-range": {
      "version": "7.1.1",
      "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
      "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
      "license": "MIT",
      "dependencies": {
        "to-regex-range": "^5.0.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/is-number": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
      "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
      "license": "MIT",
      "engines": {
        "node": ">=0.12.0"
      }
    },
    "node_modules/micromatch": {
      "version": "4.0.8",
      "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
      "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
      "license": "MIT",
      "dependencies": {
        "braces": "^3.0.3",
        "picomatch": "^2.3.1"
      },
      "engines": {
        "node": ">=8.6"
      }
    },
    "node_modules/picomatch": {
      "version": "2.3.2",
      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
      "license": "MIT",
      "engines": {
        "node": ">=8.6"
      },
      "funding": {
        "url": "https://github.com/sponsors/jonschlinkert"
      }
    },
    "node_modules/to-regex-range": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
      "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
      "license": "MIT",
      "dependencies": {
        "is-number": "^7.0.0"
      },
      "engines": {
        "node": ">=8.0"
      }
    }
  }
}

{
  "name": "sample-micromatch-matcher",
  "version": "1.0.0",
  "private": true,
  "description": "verify micromatch.matcher in pkg:npm/micromatch@4.0.8",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "micromatch": "4.0.8"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify micromatch.matcher in pkg:npm/micromatch@4.0.8",
  "kind": "HOW",
  "packages": [
    "pkg:npm/micromatch@4.0.8"
  ],
  "symbols": [
    "micromatch.matcher"
  ]
}

'use strict';

const micromatch = require('micromatch');

/**
 * Creates a reusable matcher function for glob pattern(s).
 *
 * @param {string|string[]} pattern - Glob pattern or array of patterns.
 * @param {object} [options] - Optional micromatch options.
 * @returns {Function} Matcher function that accepts a string input and optional returnObject flag.
 */
function createMatcher(pattern, options) {
  return micromatch.matcher(pattern, options);
}

/**
 * Safely filters a list of file paths against a glob pattern.
 *
 * Wraps the matcher call to avoid passing Array.prototype.filter's index argument
 * into micromatch.matcher's second returnObject argument.
 *
 * @param {string[]} paths - Array of string paths to filter.
 * @param {string|string[]} pattern - Glob pattern or array of patterns.
 * @param {object} [options] - Optional micromatch options.
 * @returns {string[]} Array of paths matching the pattern.
 */
function filterPaths(paths, pattern, options) {
  const isMatch = micromatch.matcher(pattern, options);
  return paths.filter((item) => isMatch(item));
}

module.exports = {
  createMatcher,
  filterPaths,
  micromatch
};

'use strict';

const assert = require('node:assert');
const micromatch = require('micromatch');
const { createMatcher, filterPaths } = require('../src/index.js');

// 1. micromatch.matcher returns a compiled function that evaluates whether a string matches the glob pattern
const isJs = micromatch.matcher('*.js');
assert.strictEqual(typeof isJs, 'function', 'micromatch.matcher must return a function');
assert.strictEqual(isJs('index.js'), true, 'matcher should match valid file extension');
assert.strictEqual(isJs('index.ts'), false, 'matcher should not match different extension');
assert.strictEqual(isJs('dir/index.js'), false, 'single star pattern should not match path separators');

// 2. micromatch.matcher supports globstar patterns for matching nested directory structures
const isSourceJs = micromatch.matcher('src/**/*.js');
assert.strictEqual(isSourceJs('src/index.js'), true, 'globstar matches direct child file');
assert.strictEqual(isSourceJs('src/components/button/index.js'), true, 'globstar matches nested child file');
assert.strictEqual(isSourceJs('lib/index.js'), false, 'globstar does not match different root directory');

// 3. micromatch.matcher supports arrays of glob patterns
const isCodeFile = micromatch.matcher(['*.js', '*.ts']);
assert.strictEqual(isCodeFile('server.js'), true, 'matches first pattern in pattern array');
assert.strictEqual(isCodeFile('server.ts'), true, 'matches second pattern in pattern array');
assert.strictEqual(isCodeFile('server.py'), false, 'does not match when none of patterns match');

// 4. micromatch.matcher supports pattern negations and ignore options
const isNotMinified = micromatch.matcher('!*.min.js');
assert.strictEqual(isNotMinified('bundle.js'), true, 'negated pattern matches non-matching file');
assert.strictEqual(isNotMinified('bundle.min.js'), false, 'negated pattern rejects target filename');

const isJsExceptTests = micromatch.matcher('*.js', { ignore: ['*.test.js'] });
assert.strictEqual(isJsExceptTests('utils.js'), true, 'matches target when not in ignore list');
assert.strictEqual(isJsExceptTests('utils.test.js'), false, 'rejects target when matched by ignore option');

// 5. micromatch.matcher supports options including nocase, dot, and basename matching
const isCaseInsensitiveImage = micromatch.matcher('*.png', { nocase: true });
assert.strictEqual(isCaseInsensitiveImage('logo.PNG'), true, 'matches uppercase extension when nocase is true');
assert.strictEqual(isCaseInsensitiveImage('logo.png'), true, 'matches lowercase extension when nocase is true');
assert.strictEqual(isCaseInsensitiveImage('logo.jpg'), false, 'does not match different extension');

const isDotFileMatch = micromatch.matcher('*.json', { dot: true });
const isNoDotFileMatch = micromatch.matcher('*.json');
assert.strictEqual(isDotFileMatch('.config.json'), true, 'matches dotfile when dot option is true');
assert.strictEqual(isNoDotFileMatch('.config.json'), false, 'does not match dotfile by default');

const isBasenameMatch = micromatch.matcher('*.js', { basename: true });
assert.strictEqual(isBasenameMatch('src/nested/deep/app.js'), true, 'matches basename across directory paths');
assert.strictEqual(isBasenameMatch('src/nested/deep/app.txt'), false, 'does not match basename with wrong extension');

// 6. micromatch.matcher returns a detailed result object instead of a boolean when a truthy returnObject argument is supplied
const matchResultTrue = isJs('app.js', true);
assert.strictEqual(typeof matchResultTrue, 'object', 'matcher with returnObject true returns object');
assert.strictEqual(matchResultTrue.isMatch, true, 'result object has isMatch true for matching file');
assert.strictEqual(matchResultTrue.glob, '*.js', 'result object captures glob pattern');

const matchResultFalse = isJs('app.ts', true);
assert.strictEqual(typeof matchResultFalse, 'object', 'matcher with returnObject true returns object for non-matching file');
assert.strictEqual(matchResultFalse.isMatch, false, 'result object has isMatch false for non-matching file');

// 7. Passing micromatch.matcher directly to Array.prototype.filter passes non-zero index as returnObject resulting in truthy objects; wrapping the call preserves boolean filtering
const fileList = ['main.js', 'main.ts', 'helper.js', 'style.css', 'README.md'];

// Direct pass passes (element, index) where index >= 1 triggers returnObject mode returning truthy objects
const unwrappedFiltered = fileList.filter(isJs);
assert.strictEqual(unwrappedFiltered.length, 5, 'direct filter keeps non-matching items at index >= 1 due to truthy returnObject');

// Proper usage wraps the callback to enforce single-argument boolean evaluation
const safeFiltered = fileList.filter((file) => isJs(file));
assert.deepStrictEqual(safeFiltered, ['main.js', 'helper.js'], 'wrapped filter correctly filters matching files');

const helperCreated = createMatcher('*.ts');
assert.strictEqual(helperCreated('main.ts'), true, 'createMatcher helper produces working matcher');

const filteredWithHelper = filterPaths(fileList, '*.js');
assert.deepStrictEqual(filteredWithHelper, ['main.js', 'helper.js'], 'filterPaths helper correctly filters array');

// 8. micromatch.matcher throws a TypeError when pattern is null or undefined
assert.throws(
  () => micromatch.matcher(null),
  {
    name: 'TypeError'
  },
  'micromatch.matcher should throw TypeError when pattern is null'
);

assert.throws(
  () => micromatch.matcher(undefined),
  {
    name: 'TypeError'
  },
  'micromatch.matcher should throw TypeError when pattern is undefined'
);

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