locate-path 5.0.0: find first existing path from array of paths asynchronously and synchronously

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 first existing path from array of paths asynchronously and synchronously
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/locate-path@5.0.0
Demonstrate these symbols/APIs:
  - locatePath
  - locatePath.sync

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:6cb4977c07bef1278eeeaa47f64d445ffb7a0d1087a209a12c525f8a7ad9b780","contract":["locatePath resolves to the first existing file in an array of candidate paths","locatePath resolves to undefined when none of the candidate files exist","locatePath.sync returns the first existing file synchronously","locatePath.sync returns undefined when none of the candidate files exist","locatePath resolves to directory when type option is set to directory","locatePath.sync returns directory when type option is set to directory","findFirstExistingFile and findFirstExistingFileSync helper functions locate existing files"],"goal":"find first existing path from array of paths asynchronously and synchronously","kind":"HOW","packages":["pkg:npm/locate-path@5.0.0"],"schemaVersion":1,"symbols":["locatePath","locatePath.sync"]},"contractCommand":["node","test/contract.mjs"],"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/locate-path@5.0.0"],"schemaVersion":1,"subject":"pkg:npm/locate-path@5.0.0","symbols":["locatePath","locatePath.sync"],"verifierAdapter":"node-typescript@1"}

const locatePath = require('locate-path');

async function findFirstExistingFile(files, options) {
  return await locatePath(files, options);
}

function findFirstExistingFileSync(files, options) {
  return locatePath.sync(files, options);
}

module.exports = {
  findFirstExistingFile,
  findFirstExistingFileSync
};

{
  "name": "sample-locate-path",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-locate-path",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "locate-path": "5.0.0"
      }
    },
    "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"
      }
    }
  }
}

{
  "name": "sample-locate-path",
  "version": "1.0.0",
  "description": "Minimal sample verifying pkg:npm/locate-path@5.0.0",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "license": "MIT-0",
  "dependencies": {
    "locate-path": "5.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "find first existing path from array of paths asynchronously and synchronously",
  "kind": "HOW",
  "packages": [
    "pkg:npm/locate-path@5.0.0"
  ],
  "symbols": [
    "locatePath",
    "locatePath.sync"
  ]
}

import assert from 'assert';
import path from 'path';
import os from 'os';
import fs from 'fs';
import locatePath from 'locate-path';
import { createRequire } from 'module';

const require = createRequire(import.meta.url);
const { findFirstExistingFile, findFirstExistingFileSync } = require('../index.js');

async function testLocatePath() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locate-path-contract-'));
  try {
    const fileA = path.join(tmpDir, 'alpha.txt');
    const fileB = path.join(tmpDir, 'beta.txt');
    const subDir = path.join(tmpDir, 'subdir');
    fs.writeFileSync(fileB, 'content of beta');
    fs.mkdirSync(subDir);

    // 1. locatePath resolves to the first existing file in an array of candidate paths
    const result1 = await locatePath(['nonexistent1.txt', 'beta.txt', 'alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(result1, 'beta.txt', 'locatePath should return the first existing file');

    // 2. locatePath resolves to undefined when none of the candidate files exist
    const result2 = await locatePath(['missing1.txt', 'missing2.txt'], { cwd: tmpDir });
    assert.strictEqual(result2, undefined, 'locatePath should return undefined if no candidates exist');

    // 3. locatePath.sync returns the first existing file synchronously
    const result3 = locatePath.sync(['nonexistent1.txt', 'beta.txt', 'alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(result3, 'beta.txt', 'locatePath.sync should return the first existing file');

    // 4. locatePath.sync returns undefined when none of the candidate files exist
    const result4 = locatePath.sync(['missing1.txt', 'missing2.txt'], { cwd: tmpDir });
    assert.strictEqual(result4, undefined, 'locatePath.sync should return undefined if no candidates exist');

    // 5. locatePath resolves to directory when type option is set to directory
    const result5 = await locatePath(['missing.txt', 'subdir'], { cwd: tmpDir, type: 'directory' });
    assert.strictEqual(result5, 'subdir', 'locatePath should find directory when type is directory');

    // 6. locatePath.sync returns directory when type option is set to directory
    const result6 = locatePath.sync(['missing.txt', 'subdir'], { cwd: tmpDir, type: 'directory' });
    assert.strictEqual(result6, 'subdir', 'locatePath.sync should find directory when type is directory');

    // 7. findFirstExistingFile and findFirstExistingFileSync helper functions locate existing files
    const helperAsync = await findFirstExistingFile(['missing.txt', 'beta.txt'], { cwd: tmpDir });
    assert.strictEqual(helperAsync, 'beta.txt', 'findFirstExistingFile helper should find beta.txt');

    const helperSync = findFirstExistingFileSync(['missing.txt', 'beta.txt'], { cwd: tmpDir });
    assert.strictEqual(helperSync, 'beta.txt', 'findFirstExistingFileSync helper should find beta.txt');

    console.log('Contract passed');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

testLocatePath().catch((err) => {
  console.error(err);
  process.exit(1);
});