locate-path 6.0.0: sync

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 locate-path.sync 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:
  - locate-path.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:c41f5d6e05279a3f9690d1ecafcba7c6bb2183ee58db397aeda9c3444fdcca58","contract":["locatePath.sync returns the first existing file in candidate paths","locatePath.sync returns undefined when none of the candidate files exist","locatePath.sync resolves directory when type option is set to directory","locatePath.sync supports custom cwd option","locatePath.sync ignores symlinks when allowSymlinks option is false","locatePath.sync throws an error when an invalid type option is passed","findFirstSync returns the first matching path synchronously","findFirstFileSync returns only existing file paths synchronously","findFirstDirectorySync returns only existing directory paths synchronously","locatePathSync exported alias matches locatePath.sync"],"goal":"verify locate-path.sync in pkg:npm/locate-path@6.0.0","kind":"HOW","packages":["pkg:npm/locate-path@6.0.0"],"schemaVersion":1,"symbols":["locate-path.sync"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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":["locate-path.sync"],"verifierAdapter":"node-typescript@1"}

'use strict';

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

/**
 * Locate the first existing file or directory synchronously from candidate paths.
 * @param {Iterable<string>} paths
 * @param {object} [options]
 * @returns {string|undefined}
 */
function findFirstSync(paths, options) {
  return locatePath.sync(paths, options);
}

/**
 * Locate the first existing regular file synchronously.
 * @param {Iterable<string>} paths
 * @param {object} [options]
 * @returns {string|undefined}
 */
function findFirstFileSync(paths, options) {
  return locatePath.sync(paths, { ...options, type: 'file' });
}

/**
 * Locate the first existing directory synchronously.
 * @param {Iterable<string>} paths
 * @param {object} [options]
 * @returns {string|undefined}
 */
function findFirstDirectorySync(paths, options) {
  return locatePath.sync(paths, { ...options, type: 'directory' });
}

module.exports = {
  findFirstSync,
  findFirstFileSync,
  findFirstDirectorySync,
  locatePathSync: locatePath.sync
};

{
  "name": "sample-locate-path-sync",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-locate-path-sync",
      "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-sync",
  "version": "1.0.0",
  "description": "Minimal sample verifying locate-path.sync in 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 locate-path.sync in pkg:npm/locate-path@6.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/locate-path@6.0.0"
  ],
  "symbols": [
    "locate-path.sync"
  ]
}

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 {
  findFirstSync,
  findFirstFileSync,
  findFirstDirectorySync,
  locatePathSync
} = require('../index.js');

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

  try {
    const fileAlpha = path.join(tmpDir, 'alpha.txt');
    const fileBeta = path.join(tmpDir, 'beta.txt');
    const targetDir = path.join(tmpDir, 'subfolder');
    const symlinkTarget = path.join(tmpDir, 'symlink.txt');

    fs.writeFileSync(fileAlpha, 'alpha-data');
    fs.writeFileSync(fileBeta, 'beta-data');
    fs.mkdirSync(targetDir);
    fs.symlinkSync(fileBeta, symlinkTarget);

    // 1. locatePath.sync returns the first existing file in candidate paths
    const res1 = locatePath.sync(['missing.txt', 'beta.txt', 'alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(res1, 'beta.txt', 'locatePath.sync should return first existing file');

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

    // 3. locatePath.sync resolves directory when type option is set to directory
    const res3 = locatePath.sync(['missing.txt', 'subfolder'], { cwd: tmpDir, type: 'directory' });
    assert.strictEqual(res3, 'subfolder', 'locatePath.sync should resolve existing directory');

    // 4. locatePath.sync supports custom cwd option
    const res4 = locatePath.sync(['alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(res4, 'alpha.txt', 'locatePath.sync should resolve path relative to custom cwd');

    // 5. locatePath.sync ignores symlinks when allowSymlinks option is false
    const res5 = locatePath.sync(['symlink.txt'], { cwd: tmpDir, allowSymlinks: false });
    assert.strictEqual(res5, undefined, 'locatePath.sync should not resolve symlink when allowSymlinks is false');

    // 6. locatePath.sync throws an error when an invalid type option is passed
    assert.throws(
      () => locatePath.sync(['alpha.txt'], { cwd: tmpDir, type: 'unsupported-type' }),
      /Invalid type specified: unsupported-type/,
      'locatePath.sync should throw on invalid type'
    );

    // 7. findFirstSync returns the first matching path synchronously
    const res7 = findFirstSync(['missing.txt', 'alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(res7, 'alpha.txt', 'findFirstSync helper should return first matching path');

    // 8. findFirstFileSync returns only existing file paths synchronously
    const res8 = findFirstFileSync(['missing.txt', 'subfolder', 'alpha.txt'], { cwd: tmpDir });
    assert.strictEqual(res8, 'alpha.txt', 'findFirstFileSync should return file and ignore directory');

    // 9. findFirstDirectorySync returns only existing directory paths synchronously
    const res9 = findFirstDirectorySync(['missing.txt', 'alpha.txt', 'subfolder'], { cwd: tmpDir });
    assert.strictEqual(res9, 'subfolder', 'findFirstDirectorySync should return directory and ignore file');

    // 10. locatePathSync exported alias matches locatePath.sync
    assert.strictEqual(locatePathSync, locatePath.sync, 'locatePathSync should alias locatePath.sync');

    console.log('All locate-path.sync contract assertions passed.');
  } finally {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  }
}

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