find-up 4.1.0: find files and directories up the directory tree with find-up

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: find files and directories up the directory tree with find-up
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/find-up@4.1.0
Demonstrate these symbols/APIs:
  - findUp
  - findUp.exists
  - findUp.stop
  - findUp.sync
  - findUp.sync.exists

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:757a0dff613cdf97831372957ffc0e27481c2d2d9baf2c0b5dd9e1f64ff89f4b","contract":["assert findUp, findUp.sync, findUp.exists, findUp.sync.exists, and findUp.stop are exported","assert findUp finds a file by name asynchronously starting from a nested directory","assert findUp finds the first matching candidate from an array of filenames","assert findUp.sync finds a directory when type option is set to directory","assert findUp.exists and findUp.sync.exists check path existence asynchronously and synchronously","assert findUp and findUp.sync support custom matcher functions and findUp.stop symbol to halt traversal","assert findUp and findUp.sync return undefined when target file does not exist"],"goal":"find files and directories up the directory tree with find-up","kind":"HOW","packages":["pkg:npm/find-up@4.1.0"],"schemaVersion":1,"symbols":["findUp","findUp.exists","findUp.stop","findUp.sync","findUp.sync.exists"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/find-up@4.1.0"],"schemaVersion":1,"subject":"pkg:npm/find-up@4.1.0","symbols":["findUp","findUp.exists","findUp.stop","findUp.sync","findUp.sync.exists"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-find-up",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-find-up",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "find-up": "4.1.0"
      }
    },
    "node_modules/find-up": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz",
      "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==",
      "license": "MIT",
      "dependencies": {
        "locate-path": "^5.0.0",
        "path-exists": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/locate-path": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz",
      "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==",
      "license": "MIT",
      "dependencies": {
        "p-locate": "^4.1.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/p-limit": {
      "version": "2.3.0",
      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz",
      "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==",
      "license": "MIT",
      "dependencies": {
        "p-try": "^2.0.0"
      },
      "engines": {
        "node": ">=6"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/p-locate": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz",
      "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==",
      "license": "MIT",
      "dependencies": {
        "p-limit": "^2.2.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/p-try": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz",
      "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/path-exists": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    }
  }
}

{
  "name": "csx-sample-find-up",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "find-up": "4.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "find files and directories up the directory tree with find-up",
  "kind": "HOW",
  "packages": [
    "pkg:npm/find-up@4.1.0"
  ],
  "symbols": [
    "findUp",
    "findUp.exists",
    "findUp.stop",
    "findUp.sync",
    "findUp.sync.exists"
  ]
}

import findUp from 'find-up';

export async function findFileUp(name, options) {
  return await findUp(name, options);
}

export function findFileSync(name, options) {
  return findUp.sync(name, options);
}

export async function checkPathExists(path) {
  return await findUp.exists(path);
}

export function checkPathExistsSync(path) {
  return findUp.sync.exists(path);
}

export const stopSymbol = findUp.stop;

export { findUp };

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import {
  findUp,
  findFileUp,
  findFileSync,
  checkPathExists,
  checkPathExistsSync,
  stopSymbol
} from '../src/index.mjs';

// Setup temporary directory structure for testing:
// tmpDir/
//   root/
//     pkg-marker.json
//     config/
//       level1/
//         level2/
//           level3/
const tmpBase = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-find-up-test-'));
const rootDir = path.join(tmpBase, 'root');
const level1 = path.join(rootDir, 'config', 'level1');
const level2 = path.join(level1, 'level2');
const level3 = path.join(level2, 'level3');
const subDir = path.join(rootDir, 'subDir');

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

const markerFile = path.join(rootDir, 'pkg-marker.json');
fs.writeFileSync(markerFile, JSON.stringify({ name: 'test-root' }), 'utf8');

const nestedMarker = path.join(level1, 'nested.cfg');
fs.writeFileSync(nestedMarker, 'nested-config-content', 'utf8');

try {
  // 1. Verify findUp and findUp.sync export types
  assert.equal(typeof findUp, 'function', 'findUp must be a function');
  assert.equal(typeof findUp.sync, 'function', 'findUp.sync must be a function');
  assert.equal(typeof findUp.exists, 'function', 'findUp.exists must be a function');
  assert.equal(typeof findUp.sync.exists, 'function', 'findUp.sync.exists must be a function');
  assert.equal(typeof findUp.stop, 'symbol', 'findUp.stop must be a symbol');
  assert.equal(stopSymbol, findUp.stop, 'exported stopSymbol must match findUp.stop');

  // 2. findUp finds a file by name asynchronously starting from a nested directory
  const foundAsync = await findFileUp('pkg-marker.json', { cwd: level3 });
  assert.equal(foundAsync, markerFile, 'findUp should find pkg-marker.json in parent directory');

  // 3. findUp finds the first matching candidate from an array of filenames
  const foundArray = await findFileUp(['nonexistent-file.json', 'nested.cfg'], { cwd: level3 });
  assert.equal(foundArray, nestedMarker, 'findUp should find the first existing candidate from array');

  // 4. findUp.sync finds a directory when type option is set to directory
  const foundDirSync = findFileSync('subDir', { cwd: level3, type: 'directory' });
  assert.equal(foundDirSync, subDir, 'findUp.sync should find subDir directory');

  // 5. findUp.exists and findUp.sync.exists check path existence asynchronously and synchronously
  const existsAsyncTrue = await checkPathExists(markerFile);
  const existsAsyncFalse = await checkPathExists(path.join(rootDir, 'missing.txt'));
  const existsSyncTrue = checkPathExistsSync(markerFile);
  const existsSyncFalse = checkPathExistsSync(path.join(rootDir, 'missing.txt'));

  assert.equal(existsAsyncTrue, true, 'findUp.exists should return true for existing file');
  assert.equal(existsAsyncFalse, false, 'findUp.exists should return false for missing file');
  assert.equal(existsSyncTrue, true, 'findUp.sync.exists should return true for existing file');
  assert.equal(existsSyncFalse, false, 'findUp.sync.exists should return false for missing file');

  // 6. findUp and findUp.sync support custom matcher functions and findUp.stop symbol to halt traversal
  const stoppedAsync = await findUp(async (dir) => {
    if (dir === level2) {
      return findUp.stop;
    }
    const p = path.join(dir, 'pkg-marker.json');
    return (await findUp.exists(p)) ? p : undefined;
  }, { cwd: level3 });
  assert.equal(stoppedAsync, undefined, 'findUp should return undefined when stopped early by findUp.stop');

  const stoppedSync = findUp.sync((dir) => {
    if (dir === level2) {
      return findUp.stop;
    }
    const p = path.join(dir, 'pkg-marker.json');
    return findUp.sync.exists(p) ? p : undefined;
  }, { cwd: level3 });
  assert.equal(stoppedSync, undefined, 'findUp.sync should return undefined when stopped early by findUp.stop');

  // 7. findUp and findUp.sync return undefined when target file does not exist
  const missingAsync = await findFileUp('completely-nonexistent-file-404.tmp', { cwd: level3 });
  const missingSync = findFileSync('completely-nonexistent-file-404.tmp', { cwd: level3 });
  assert.equal(missingAsync, undefined, 'findUp returns undefined when not found');
  assert.equal(missingSync, undefined, 'findUp.sync returns undefined when not found');

  console.log('CONTRACT PASS: find-up 4.1.0 verified successfully');
} finally {
  fs.rmSync(tmpBase, { recursive: true, force: true });
}