locate-path 6.0.0: locatePath

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 locatePath in pkg:npm/locate-path@6.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/locate-path@6.0.0
Demonstrate these symbols/APIs:
  - locatePath
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:dc146bd6638dca50130ece541c18f1b446e318141ed6faced9057c133e4c06a8","constraints":{"executionContext":"node"},"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 resolves to directory when type option is set to directory","locatePath supports custom cwd option","locatePath supports allowSymlinks option set to false","locatePath.sync returns the first existing file synchronously","findFirstExistingPath helper locates the first existing path asynchronously"],"goal":"verify locatePath in pkg:npm/locate-path@6.0.0","kind":"HOW","packages":["pkg:npm/locate-path@6.0.0"],"schemaVersion":1,"symbols":["locatePath"]},"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","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/locate-path@6.0.0"],"schemaVersion":1,"subject":"pkg:npm/locate-path@6.0.0","symbols":["locatePath"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

async function findFirstExistingPath(paths, options) {
  return await locatePath(paths, options);
}

function findFirstExistingPathSync(paths, options) {
  return locatePath.sync(paths, options);
}

module.exports = {
  findFirstExistingPath,
  findFirstExistingPathSync
};

{
  "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": "6.0.0"
      }
    },
    "node_modules/locate-path": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
      "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==",
      "license": "MIT",
      "dependencies": {
        "p-locate": "^5.0.0"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/p-limit": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
      "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
      "license": "MIT",
      "dependencies": {
        "yocto-queue": "^0.1.0"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/p-locate": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz",
      "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==",
      "license": "MIT",
      "dependencies": {
        "p-limit": "^3.0.2"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "node_modules/yocto-queue": {
      "version": "0.1.0",
      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
      "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
      "license": "MIT",
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify locatePath in pkg:npm/locate-path@6.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/locate-path@6.0.0"
  ],
  "symbols": [
    "locatePath"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

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

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

async function runContract() {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'locate-path-contract-'));

  try {
    const fileA = path.join(tmpDir, 'file-a.txt');
    const fileB = path.join(tmpDir, 'file-b.txt');
    const subDir = path.join(tmpDir, 'sub-dir');
    const symlinkFile = path.join(tmpDir, 'symlink-file.txt');

    fs.writeFileSync(fileB, 'beta content');
    fs.mkdirSync(subDir);
    fs.symlinkSync(fileB, symlinkFile);

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

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

    // 3. locatePath resolves to directory when type option is set to directory
    const res3 = await locatePath(['nonexistent.txt', 'sub-dir'], { cwd: tmpDir, type: 'directory' });
    assert.strictEqual(res3, 'sub-dir', 'locatePath should resolve to directory when type is directory');

    // 4. locatePath supports custom cwd option
    const res4 = await locatePath(['file-b.txt'], { cwd: tmpDir });
    assert.strictEqual(res4, 'file-b.txt', 'locatePath should respect custom cwd');

    // 5. locatePath supports allowSymlinks option set to false
    const res5 = await locatePath(['symlink-file.txt'], { cwd: tmpDir, allowSymlinks: false });
    assert.strictEqual(res5, undefined, 'locatePath should not resolve symlink when allowSymlinks is false');

    // 6. locatePath.sync returns the first existing file synchronously
    const res6 = locatePath.sync(['nonexistent1.txt', 'file-b.txt'], { cwd: tmpDir });
    assert.strictEqual(res6, 'file-b.txt', 'locatePath.sync should return first existing file');

    // 7. findFirstExistingPath helper locates the first existing path asynchronously
    const res7 = await findFirstExistingPath(['missing.txt', 'file-b.txt'], { cwd: tmpDir });
    assert.strictEqual(res7, 'file-b.txt', 'findFirstExistingPath helper should return first existing file');

    console.log('All locatePath contract checks passed.');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

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