ignore 5.3.2: Filter and test file paths against gitignore rules using ignore

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: Filter and test file paths against gitignore rules using ignore
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ignore@5.3.2
Demonstrate these symbols/APIs:
  - Ignore#add
  - Ignore#createFilter
  - Ignore#filter
  - Ignore#ignores
  - Ignore#test
  - ignore
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:52be1d3058bf8f0882c023f67e62b6427fa943fdfbb682c9c3d2bd3ea39347ce","constraints":{"executionContext":"node"},"contract":["assert ignore() creates and returns an Ignore instance","assert Ignore#add registers gitignore rules from strings and arrays and supports method chaining","assert Ignore#ignores returns true for ignored paths and false for non-ignored or negated paths","assert Ignore#filter filters an array of file paths and returns only unignored paths","assert Ignore#createFilter returns a predicate function suitable for Array#filter matching Ignore#filter behavior","assert Ignore#test returns an object with { ignored, unignored } boolean flags reflecting matching gitignore rules"],"goal":"Filter and test file paths against gitignore rules using ignore","kind":"HOW","packages":["pkg:npm/ignore@5.3.2"],"schemaVersion":1,"symbols":["Ignore#add","Ignore#createFilter","Ignore#filter","Ignore#ignores","Ignore#test","ignore"]},"contractCommand":["node","test/contract.cjs"],"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/ignore@5.3.2"],"schemaVersion":1,"subject":"pkg:npm/ignore@5.3.2","symbols":["Ignore#add","Ignore#createFilter","Ignore#filter","Ignore#ignores","Ignore#test","ignore"],"verifierAdapter":"node-typescript@1"}

'use strict';

const ignore = require('ignore');

/**
 * Creates an Ignore instance initialized with the specified gitignore patterns.
 *
 * @param {string|string[]} patterns - Glob patterns or list of patterns.
 * @param {object} [options] - Options passed to the ignore factory.
 * @returns {import('ignore').Ignore} An Ignore instance with registered rules.
 */
function createPathFilter(patterns, options) {
  const ig = ignore(options);
  if (patterns) {
    ig.add(patterns);
  }
  return ig;
}

/**
 * Filters an array of relative file paths, returning only those not ignored.
 *
 * @param {string[]} paths - Candidate file paths.
 * @param {string|string[]} patterns - Gitignore patterns to match against.
 * @param {object} [options] - Options passed to the ignore factory.
 * @returns {string[]} Array of unignored file paths.
 */
function filterPaths(paths, patterns, options) {
  const ig = createPathFilter(patterns, options);
  return ig.filter(paths);
}

/**
 * Checks whether a single relative file path is ignored.
 *
 * @param {string} pathname - Relative file path to test.
 * @param {string|string[]} patterns - Gitignore patterns.
 * @param {object} [options] - Options passed to the ignore factory.
 * @returns {boolean} True if the path matches ignore rules.
 */
function isPathIgnored(pathname, patterns, options) {
  const ig = createPathFilter(patterns, options);
  return ig.ignores(pathname);
}

/**
 * Tests a path against gitignore rules and returns match details.
 *
 * @param {string} pathname - Relative file path to test.
 * @param {string|string[]} patterns - Gitignore patterns.
 * @param {object} [options] - Options passed to the ignore factory.
 * @returns {{ ignored: boolean, unignored: boolean }} Result with ignored/unignored status.
 */
function testPath(pathname, patterns, options) {
  const ig = createPathFilter(patterns, options);
  return ig.test(pathname);
}

module.exports = {
  createPathFilter,
  filterPaths,
  isPathIgnored,
  testPath,
  ignore,
};

{
  "name": "ignore-path-filter",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "ignore-path-filter",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ignore": "5.3.2"
      }
    },
    "node_modules/ignore": {
      "version": "5.3.2",
      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
      "license": "MIT",
      "engines": {
        "node": ">= 4"
      }
    }
  }
}

{
  "name": "ignore-path-filter",
  "version": "1.0.0",
  "private": true,
  "description": "Filter and test file paths against gitignore rules using ignore",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "dependencies": {
    "ignore": "5.3.2"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "Filter and test file paths against gitignore rules using ignore",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ignore@5.3.2"
  ],
  "symbols": [
    "Ignore#add",
    "Ignore#createFilter",
    "Ignore#filter",
    "Ignore#ignores",
    "Ignore#test",
    "ignore"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

'use strict';

const assert = require('node:assert');
const ignore = require('ignore');
const {
  createPathFilter,
  filterPaths,
  isPathIgnored,
  testPath,
} = require('../index.js');

// 1. Factory function: ignore()
const ig = ignore();
assert(ig && typeof ig.add === 'function', 'ignore() should return an Ignore instance');

// 2. Ignore#add method and method chaining
const chainResult = ig.add('*.tmp').add(['build/*', '!build/output.json', 'temp/']);
assert.strictEqual(chainResult, ig, 'Ignore#add should return the instance for method chaining');

// 3. Ignore#ignores method
assert.strictEqual(ig.ignores('cache.tmp'), true, 'Should ignore *.tmp files');
assert.strictEqual(ig.ignores('src/app.js'), false, 'Should not ignore unlisted files');
assert.strictEqual(ig.ignores('build/debug.log'), true, 'Should ignore files inside build/*');
assert.strictEqual(ig.ignores('build/output.json'), false, 'Should not ignore negated !build/output.json');
assert.strictEqual(ig.ignores('temp/nested/file.txt'), true, 'Should ignore paths under temp/ directory');

// 4. Ignore#filter method
const fileList = [
  'src/index.js',
  'cache.tmp',
  'build/debug.log',
  'build/output.json',
  'temp/data.csv',
  'docs/readme.md',
];
const filteredFiles = ig.filter(fileList);
assert.deepStrictEqual(
  filteredFiles,
  ['src/index.js', 'build/output.json', 'docs/readme.md'],
  'Ignore#filter should only keep unignored paths'
);

// 5. Ignore#createFilter method
const filterPredicate = ig.createFilter();
assert.strictEqual(typeof filterPredicate, 'function', 'Ignore#createFilter should return a function');
const predicateFiltered = fileList.filter(filterPredicate);
assert.deepStrictEqual(
  predicateFiltered,
  ['src/index.js', 'build/output.json', 'docs/readme.md'],
  'Ignore#createFilter predicate should produce identical results to Ignore#filter'
);

// 6. Ignore#test method
const testIgnored = ig.test('cache.tmp');
assert.deepStrictEqual(
  testIgnored,
  { ignored: true, unignored: false },
  'Ignore#test should return { ignored: true, unignored: false } for ignored paths'
);

const testNegated = ig.test('build/output.json');
assert.deepStrictEqual(
  testNegated,
  { ignored: false, unignored: true },
  'Ignore#test should return { ignored: false, unignored: true } for negated unignored paths'
);

const testUnmatched = ig.test('src/index.js');
assert.deepStrictEqual(
  testUnmatched,
  { ignored: false, unignored: false },
  'Ignore#test should return { ignored: false, unignored: false } for unreferenced paths'
);

// 7. Verify helper module functions
const helperIg = createPathFilter(['*.bak', 'dist/*']);
assert.strictEqual(isPathIgnored('file.bak', ['*.bak']), true);
assert.strictEqual(isPathIgnored('file.txt', ['*.bak']), false);

const helperFiltered = filterPaths(['a.txt', 'b.bak', 'c.md'], ['*.bak']);
assert.deepStrictEqual(helperFiltered, ['a.txt', 'c.md']);

const helperTest = testPath('b.bak', ['*.bak']);
assert.strictEqual(helperTest.ignored, true);

console.log('All contract assertions passed successfully.');