fdir 6.5.0: fdir

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 fdir.fdir in pkg:npm/fdir@6.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fdir@6.5.0
Demonstrate these symbols/APIs:
  - fdir.fdir

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:04b5c2d1e0be9910fdfe8f8f666cb719a44d40f2c4bd46a7ab2a54fcf454aee8","contract":["fdir constructor returns a crawler builder supporting chained configuration","crawl synchronizes directory traversal returning file paths synchronously with sync","crawl executes directory traversal asynchronously returning file paths via withPromise and withCallback","withDirs and onlyDirs include or isolate directory paths during crawl","filter and exclude selectively match or prune directory traversal paths","onlyCounts returns file and directory counts instead of path arrays","withRelativePaths and withBasePath configure relative or absolute path resolution"],"goal":"verify fdir.fdir in pkg:npm/fdir@6.5.0","kind":"HOW","packages":["pkg:npm/fdir@6.5.0"],"schemaVersion":1,"symbols":["fdir.fdir"]},"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/fdir@6.5.0"],"schemaVersion":1,"subject":"pkg:npm/fdir@6.5.0","symbols":["fdir.fdir"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-fdir",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fdir",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "fdir": "6.5.0"
      }
    },
    "node_modules/fdir": {
      "version": "6.5.0",
      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
      "license": "MIT",
      "engines": {
        "node": ">=12.0.0"
      },
      "peerDependencies": {
        "picomatch": "^3 || ^4"
      },
      "peerDependenciesMeta": {
        "picomatch": {
          "optional": true
        }
      }
    }
  }
}

{
  "name": "sample-fdir",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for fdir@6.5.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "fdir": "6.5.0"
  }
}

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

'use strict';

const { fdir } = require('fdir');

/**
 * Creates a configured fdir crawler instance.
 *
 * @param {object} [options] - Optional fdir configuration options.
 * @returns {fdir} An fdir crawler builder instance.
 */
function createCrawler(options) {
  return new fdir(options);
}

/**
 * Crawls a root directory synchronously.
 *
 * @param {string} root - Path to directory to crawl.
 * @returns {string[]} Discovered file paths.
 */
function crawlSync(root) {
  return new fdir().crawl(root).sync();
}

/**
 * Crawls a root directory asynchronously using Promises.
 *
 * @param {string} root - Path to directory to crawl.
 * @returns {Promise<string[]>} Discovered file paths.
 */
async function crawlAsync(root) {
  return new fdir().crawl(root).withPromise();
}

/**
 * Crawls a root directory and returns count statistics.
 *
 * @param {string} root - Path to directory to crawl.
 * @returns {{ files: number, directories: number }} File and directory counts.
 */
function countEntriesSync(root) {
  return new fdir().onlyCounts().crawl(root).sync();
}

module.exports = {
  fdir,
  createCrawler,
  crawlSync,
  crawlAsync,
  countEntriesSync
};

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { fdir, createCrawler, crawlSync, crawlAsync, countEntriesSync } = require('../src/index.js');

function setupTestFixture() {
  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-fdir-test-'));
  const nestedDir = path.join(tempDir, 'nested');
  const deepDir = path.join(nestedDir, 'deep');

  fs.mkdirSync(deepDir, { recursive: true });

  fs.writeFileSync(path.join(tempDir, 'root.txt'), 'root content');
  fs.writeFileSync(path.join(tempDir, 'file1.log'), 'log content');
  fs.writeFileSync(path.join(nestedDir, 'child.txt'), 'child content');
  fs.writeFileSync(path.join(deepDir, 'deep.txt'), 'deep content');

  return tempDir;
}

function cleanupFixture(dir) {
  try {
    fs.rmSync(dir, { recursive: true, force: true });
  } catch {
    // ignore cleanup errors
  }
}

async function runContractTests() {
  const fixtureDir = setupTestFixture();

  try {
    // 1. Export and builder instantiation
    assert.equal(typeof fdir, 'function', 'fdir export must be a constructor function');
    assert.equal(typeof createCrawler, 'function', 'createCrawler helper must be a function');
    assert.equal(typeof crawlSync, 'function', 'crawlSync helper must be a function');
    assert.equal(typeof crawlAsync, 'function', 'crawlAsync helper must be a function');
    assert.equal(typeof countEntriesSync, 'function', 'countEntriesSync helper must be a function');

    const crawler = new fdir();
    assert.equal(typeof crawler.crawl, 'function', 'crawler must have crawl method');
    assert.equal(typeof crawler.filter, 'function', 'crawler must have filter method');
    assert.equal(typeof crawler.exclude, 'function', 'crawler must have exclude method');
    assert.equal(typeof crawler.onlyCounts, 'function', 'crawler must have onlyCounts method');
    assert.equal(typeof crawler.withDirs, 'function', 'crawler must have withDirs method');
    assert.equal(typeof crawler.onlyDirs, 'function', 'crawler must have onlyDirs method');
    assert.equal(typeof crawler.withBasePath, 'function', 'crawler must have withBasePath method');
    assert.equal(typeof crawler.withRelativePaths, 'function', 'crawler must have withRelativePaths method');

    // Chaining returns crawler builder
    assert.equal(crawler.withDirs(), crawler, 'builder methods should return crawler instance');

    // 2. Synchronous crawling
    const syncResults = new fdir().crawl(fixtureDir).sync();
    assert.ok(Array.isArray(syncResults), 'sync() must return an array');
    assert.equal(syncResults.length, 4, 'sync() should find exactly 4 files');
    assert.ok(syncResults.includes('root.txt'), 'sync() results must include root.txt');
    assert.ok(syncResults.includes('file1.log'), 'sync() results must include file1.log');

    const helperSyncResults = crawlSync(fixtureDir);
    assert.equal(helperSyncResults.length, 4, 'crawlSync helper should find 4 files');

    // 3. Asynchronous crawling with Promises and callbacks
    const promiseResults = await new fdir().crawl(fixtureDir).withPromise();
    assert.ok(Array.isArray(promiseResults), 'withPromise() must resolve to an array');
    assert.equal(promiseResults.length, 4, 'withPromise() should find exactly 4 files');

    const helperAsyncResults = await crawlAsync(fixtureDir);
    assert.equal(helperAsyncResults.length, 4, 'crawlAsync helper should resolve to 4 files');

    const callbackResults = await new Promise((resolve, reject) => {
      new fdir().crawl(fixtureDir).withCallback((err, files) => {
        if (err) return reject(err);
        resolve(files);
      });
    });
    assert.ok(Array.isArray(callbackResults), 'withCallback() must provide an array of files');
    assert.equal(callbackResults.length, 4, 'withCallback() should find exactly 4 files');

    // 4. Directory inclusion and directory-only filtering
    const withDirsResults = new fdir().withDirs().crawl(fixtureDir).sync();
    assert.ok(withDirsResults.length > 4, 'withDirs() should include directories and files');
    assert.ok(withDirsResults.some((item) => item.includes('nested')), 'withDirs() should include nested directory');

    const onlyDirsResults = new fdir().onlyDirs().crawl(fixtureDir).sync();
    assert.ok(onlyDirsResults.length >= 2, 'onlyDirs() should return at least 2 directories');
    assert.ok(!onlyDirsResults.includes('root.txt'), 'onlyDirs() must not contain files');

    // 5. Predicate filtering and exclusion
    const txtOnlyResults = new fdir().filter((filePath) => filePath.endsWith('.txt')).crawl(fixtureDir).sync();
    assert.equal(txtOnlyResults.length, 3, 'filter() for .txt should return 3 files');
    assert.ok(txtOnlyResults.every((f) => f.endsWith('.txt')), 'all filtered files must end with .txt');
    assert.ok(!txtOnlyResults.includes('file1.log'), 'filter() must exclude file1.log');

    const excludedResults = new fdir().exclude((dirName) => dirName === 'deep').crawl(fixtureDir).sync();
    assert.equal(excludedResults.length, 3, 'exclude() deep should skip deep.txt');
    assert.ok(!excludedResults.includes('deep.txt'), 'excluded directory content must not be present');

    // 6. Counts mode
    const countResult = new fdir().onlyCounts().crawl(fixtureDir).sync();
    assert.equal(countResult.files, 4, 'onlyCounts() should report 4 files');
    assert.ok(countResult.directories >= 2, 'onlyCounts() should report directories');

    const helperCountResult = countEntriesSync(fixtureDir);
    assert.equal(helperCountResult.files, 4, 'countEntriesSync should report 4 files');

    // 7. Relative and base path formatting
    const relResults = new fdir().withRelativePaths().crawl(fixtureDir).sync();
    assert.ok(relResults.some((p) => p.replace(/\\/g, '/') === 'nested/child.txt'), 'withRelativePaths() should format paths with relative directory prefixes');

    const baseResults = new fdir().withBasePath().crawl(fixtureDir).sync();
    assert.ok(baseResults.every((p) => p.startsWith(fixtureDir)), 'withBasePath() should prepend root base path');

    console.log('All fdir contract tests passed successfully.');
  } finally {
    cleanupFixture(fixtureDir);
  }
}

runContractTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});