find-up 5.0.0: findUpStop

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 findUpStop in pkg:npm/find-up@5.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/find-up@5.0.0
Demonstrate these symbols/APIs:
  - findUpStop

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:cb3c5a3f438e0925c51ae43b1acbe59af3a52522ab44cce074fccdeef4ff6e1d","contract":["assert findUpStop is exported and equals findUp.stop symbol","assert findUp halts asynchronous directory traversal and resolves to undefined when matcher returns findUpStop","assert findUp.sync halts synchronous directory traversal and returns undefined when matcher returns findUpStop","assert returning findUpStop at initial search directory halts traversal immediately without checking parents","assert createStopAtDirectoryMatcher stops synchronous traversal at boundary marker","assert createAsyncStopMatcher stops asynchronous traversal at boundary marker","assert directory traversal continues upward to find target when findUpStop is not returned"],"goal":"verify findUpStop in pkg:npm/find-up@5.0.0","kind":"HOW","packages":["pkg:npm/find-up@5.0.0"],"schemaVersion":1,"symbols":["findUpStop"]},"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/find-up@5.0.0"],"schemaVersion":1,"subject":"pkg:npm/find-up@5.0.0","symbols":["findUpStop"],"verifierAdapter":"node-typescript@1"}

const path = require('node:path');
const fs = require('node:fs');
const findUp = require('find-up');

/**
 * findUpStop symbol used to halt directory traversal in findUp / findUp.sync.
 * In find-up@5.0.0, this is the unique sentinel symbol exported at findUp.stop.
 */
const findUpStop = findUp.stop;

/**
 * Searches asynchronously for a file or directory with a custom matcher function,
 * allowing findUpStop to immediately halt upward directory traversal.
 *
 * @param {Function} matcher - Function called with each directory that returns a file path, findUpStop, or undefined.
 * @param {object} [options] - Options passed to findUp.
 * @param {string} [options.cwd] - Directory to start looking from.
 * @returns {Promise<string|undefined>} First path found or undefined if stopped / not found.
 */
async function findWithEarlyStop(matcher, options = {}) {
  return findUp(matcher, options);
}

/**
 * Searches synchronously for a file or directory with a custom matcher function,
 * allowing findUpStop to immediately halt upward directory traversal.
 *
 * @param {Function} matcher - Function called with each directory that returns a file path, findUpStop, or undefined.
 * @param {object} [options] - Options passed to findUp.sync.
 * @param {string} [options.cwd] - Directory to start looking from.
 * @returns {string|undefined} First path found or undefined if stopped / not found.
 */
function findWithEarlyStopSync(matcher, options = {}) {
  return findUp.sync(matcher, options);
}

/**
 * Creates a synchronous matcher that stops searching when reaching a boundary file/marker.
 *
 * @param {string} targetFileName - Target file to look for.
 * @param {string} stopMarkerName - Boundary file or folder name that halts traversal if present.
 * @returns {Function} Synchronous matcher function compatible with findUp.sync.
 */
function createStopAtDirectoryMatcher(targetFileName, stopMarkerName) {
  return directory => {
    const targetPath = path.join(directory, targetFileName);
    if (fs.existsSync(targetPath)) {
      return targetPath;
    }

    const stopPath = path.join(directory, stopMarkerName);
    if (fs.existsSync(stopPath)) {
      return findUpStop;
    }

    return undefined;
  };
}

/**
 * Creates an asynchronous matcher that stops searching when reaching a boundary file/marker.
 *
 * @param {string} targetFileName - Target file to look for.
 * @param {string} stopMarkerName - Boundary file or folder name that halts traversal if present.
 * @returns {Function} Asynchronous matcher function compatible with findUp.
 */
function createAsyncStopMatcher(targetFileName, stopMarkerName) {
  return async directory => {
    const targetPath = path.join(directory, targetFileName);
    if (fs.existsSync(targetPath)) {
      return targetPath;
    }

    const stopPath = path.join(directory, stopMarkerName);
    if (fs.existsSync(stopPath)) {
      return findUpStop;
    }

    return undefined;
  };
}

module.exports = {
  findUp,
  findUpStop,
  findWithEarlyStop,
  findWithEarlyStopSync,
  createStopAtDirectoryMatcher,
  createAsyncStopMatcher,
};

{
  "name": "sample-find-up-find-up-stop",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-find-up-find-up-stop",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "find-up": "5.0.0"
      }
    },
    "node_modules/find-up": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz",
      "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==",
      "license": "MIT",
      "dependencies": {
        "locate-path": "^6.0.0",
        "path-exists": "^4.0.0"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
    "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/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"
      }
    },
    "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-find-up-find-up-stop",
  "version": "1.0.0",
  "description": "Clean-room sample verifying findUpStop symbol and early-termination behavior in find-up",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "find-up": "5.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify findUpStop in pkg:npm/find-up@5.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/find-up@5.0.0"
  ],
  "symbols": [
    "findUpStop"
  ]
}

import assert from 'node:assert';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import findUp from 'find-up';
import {
  findUpStop,
  findWithEarlyStop,
  findWithEarlyStopSync,
  createStopAtDirectoryMatcher,
  createAsyncStopMatcher,
} from '../index.js';

// Setup isolated temporary directory structure for offline verification:
// tmpDir (root)
// ├── root-target.txt
// └── boundary/
//     ├── .stop-boundary
//     └── nested/
//         └── deep/
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-findupstop-contract-'));
const boundaryDir = path.join(tmpDir, 'boundary');
const nestedDir = path.join(boundaryDir, 'nested');
const deepDir = path.join(nestedDir, 'deep');

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

const rootTarget = path.join(tmpDir, 'root-target.txt');
const stopMarker = path.join(boundaryDir, '.stop-boundary');

fs.writeFileSync(rootTarget, 'root target content', 'utf8');
fs.writeFileSync(stopMarker, 'boundary stop marker', 'utf8');

try {
  // 1. assert findUpStop is exported and equals findUp.stop symbol
  assert.strictEqual(typeof findUpStop, 'symbol', 'findUpStop must be a symbol');
  assert.strictEqual(findUpStop, findUp.stop, 'findUpStop must match findUp.stop sentinel');

  // 2. assert findUp halts asynchronous directory traversal and resolves to undefined when matcher returns findUpStop
  const asyncVisited = [];
  const asyncResult = await findWithEarlyStop(async dir => {
    asyncVisited.push(dir);
    if (fs.existsSync(path.join(dir, '.stop-boundary'))) {
      return findUpStop;
    }
    const candidate = path.join(dir, 'root-target.txt');
    return fs.existsSync(candidate) ? candidate : undefined;
  }, { cwd: deepDir });

  assert.strictEqual(asyncResult, undefined, 'findUp must resolve to undefined when findUpStop is returned');
  assert.strictEqual(asyncVisited.includes(tmpDir), false, 'findUp must not traverse past the stop boundary');
  assert.strictEqual(asyncVisited.length, 3, 'findUp must check deep, nested, and boundary, then stop');

  // 3. assert findUp.sync halts synchronous directory traversal and returns undefined when matcher returns findUpStop
  const syncVisited = [];
  const syncResult = findWithEarlyStopSync(dir => {
    syncVisited.push(dir);
    if (fs.existsSync(path.join(dir, '.stop-boundary'))) {
      return findUpStop;
    }
    const candidate = path.join(dir, 'root-target.txt');
    return fs.existsSync(candidate) ? candidate : undefined;
  }, { cwd: deepDir });

  assert.strictEqual(syncResult, undefined, 'findUp.sync must return undefined when findUpStop is returned');
  assert.strictEqual(syncVisited.includes(tmpDir), false, 'findUp.sync must not traverse past the stop boundary');
  assert.strictEqual(syncVisited.length, 3, 'findUp.sync must check deep, nested, and boundary, then stop');

  // 4. assert returning findUpStop at initial search directory halts traversal immediately without checking parents
  let initialCallCount = 0;
  const immediateStopResult = findUp.sync(() => {
    initialCallCount += 1;
    return findUpStop;
  }, { cwd: deepDir });

  assert.strictEqual(immediateStopResult, undefined, 'findUp.sync must return undefined on immediate stop');
  assert.strictEqual(initialCallCount, 1, 'findUp.sync must halt on first call when findUpStop is returned');

  // 5. assert createStopAtDirectoryMatcher stops synchronous traversal at boundary marker
  const syncBoundedMatcher = createStopAtDirectoryMatcher('root-target.txt', '.stop-boundary');
  const boundedSyncResult = findUp.sync(syncBoundedMatcher, { cwd: deepDir });
  assert.strictEqual(boundedSyncResult, undefined, 'Bounded sync matcher must return undefined at stop marker');

  // 6. assert createAsyncStopMatcher stops asynchronous traversal at boundary marker
  const asyncBoundedMatcher = createAsyncStopMatcher('root-target.txt', '.stop-boundary');
  const boundedAsyncResult = await findUp(asyncBoundedMatcher, { cwd: deepDir });
  assert.strictEqual(boundedAsyncResult, undefined, 'Bounded async matcher must resolve to undefined at stop marker');

  // 7. assert directory traversal continues upward to find target when findUpStop is not returned
  const normalFound = findUp.sync('root-target.txt', { cwd: deepDir });
  assert.strictEqual(normalFound, rootTarget, 'Normal findUp without stop returns path in root directory');

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