browserslist 4.28.9: Locate configuration files and enforce mutual exclusivity with browserslist.findConfigFile

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: Locate configuration files and enforce mutual exclusivity with browserslist.findConfigFile
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/browserslist@4.28.9
Demonstrate these symbols/APIs:
  - browserslist.findConfigFile

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:0a3c2c05f1867d4412906cd48e2c2520bd707fa3aeb01e037390b7d6f622807c","contract":["browserslist.findConfigFile(dir) discovers .browserslistrc files and returns their absolute path","browserslist.findConfigFile(dir) discovers browserslist files without extension and returns their absolute path","browserslist.findConfigFile(dir) discovers package.json with browserslist field and returns its absolute path","browserslist.findConfigFile(childDir) traverses parent directories to discover configuration files","browserslist.findConfigFile(dir) ignores package.json lacking a browserslist configuration section","browserslist.findConfigFile(dir) returns undefined when no configuration file exists in the directory tree","browserslist.findConfigFile(dir) throws BrowserslistError when both .browserslistrc and package.json with browsers exist","browserslist.findConfigFile(dir) throws BrowserslistError when both browserslist and package.json with browsers exist","browserslist.findConfigFile(dir) throws BrowserslistError when both .browserslistrc and browserslist exist"],"goal":"Locate configuration files and enforce mutual exclusivity with browserslist.findConfigFile","kind":"HOW","packages":["pkg:npm/browserslist@4.28.9"],"schemaVersion":1,"symbols":["browserslist.findConfigFile"]},"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/browserslist@4.28.9"],"schemaVersion":1,"subject":"pkg:npm/browserslist@4.28.9","symbols":["browserslist.findConfigFile"],"verifierAdapter":"node-typescript@1"}

const browserslist = require('browserslist');

/**
 * Discovers configuration files for browserslist from the given directory.
 *
 * @param {string} from - Starting directory or file path.
 * @returns {string | undefined} Absolute path to the config file, or undefined.
 */
function findConfigFile(from) {
  return browserslist.findConfigFile(from);
}

module.exports = {
  browserslist,
  findConfigFile,
};

{
  "name": "sample-browserslist-find-config-file",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-browserslist-find-config-file",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "browserslist": "4.28.9"
      }
    },
    "node_modules/baseline-browser-mapping": {
      "version": "2.11.21",
      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.21.tgz",
      "integrity": "sha512-uh8vpY/1/YyFkunIDFH/12p7/7VdPKA1hejMVEbdkEaWnUz0Hesvx5EbiU6XxjyHZIOju+ZMbQJkRh+es3/spQ==",
      "license": "Apache-2.0",
      "bin": {
        "baseline-browser-mapping": "dist/cli.cjs"
      },
      "engines": {
        "node": ">=6.0.0"
      }
    },
    "node_modules/browserslist": {
      "version": "4.28.9",
      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.9.tgz",
      "integrity": "sha512-EWazOblFYUvlGZcfGhPUPmYh3nikUxBVb+y9MJun5f3hBi812X+8MSQTujLBtgK3cf51fJWbWfOjyeO954d+Eg==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/browserslist"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/browserslist"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "baseline-browser-mapping": "^2.11.20",
        "caniuse-lite": "^1.0.30001810",
        "electron-to-chromium": "^1.5.420",
        "node-releases": "^2.0.54",
        "update-browserslist-db": "^1.3.2"
      },
      "bin": {
        "browserslist": "cli.js"
      },
      "engines": {
        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
      }
    },
    "node_modules/caniuse-lite": {
      "version": "1.0.30001810",
      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001810.tgz",
      "integrity": "sha512-TITQPUkaz+aVk5GL6NhOdwk1aEaNTSDPsGFWrTuhKGtjTF70jL/Oht2W4c6rXUe5fu7Ie19VIahAXHIIiWWNeg==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/browserslist"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/caniuse-lite"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "CC-BY-4.0"
    },
    "node_modules/electron-to-chromium": {
      "version": "1.5.422",
      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.422.tgz",
      "integrity": "sha512-UvA/32XqrLDdZSn7Jllo1AYNcWji/G0d5M0GTViE7KoGBiMunw3a34Sb2KO4ZZyrSEhqsxFoVhWWJshdyfKqJA==",
      "license": "ISC"
    },
    "node_modules/escalade": {
      "version": "3.2.0",
      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/node-releases": {
      "version": "2.0.54",
      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.54.tgz",
      "integrity": "sha512-YHs7BmmcsdAI5Ozuf8JZo6PT0mv2GIWC9vMfvUC3dp65M8hn7Ux8CPL+2oBI7juNuj9d0ndhTcznq2ODBps9cQ==",
      "license": "MIT",
      "engines": {
        "node": ">=18"
      }
    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
      "license": "ISC"
    },
    "node_modules/update-browserslist-db": {
      "version": "1.3.2",
      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.2.tgz",
      "integrity": "sha512-UQ+MSxlhRm1bzjhU+DcuXfjFO1FzNtqhK5+9Yvlp90ItDLk5vT932A0rFu619nf7RVS+Y/VeaUW1jaRDqZ8VJw==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/browserslist"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/browserslist"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "escalade": "^3.2.0",
        "picocolors": "^1.1.1"
      },
      "bin": {
        "update-browserslist-db": "cli.js"
      },
      "peerDependencies": {
        "browserslist": ">= 4.21.0"
      }
    }
  }
}

{
  "name": "sample-browserslist-find-config-file",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room sample verifying browserslist.findConfigFile discovery and mutual exclusivity",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "browserslist": "4.28.9"
  }
}

{
  "schemaVersion": 1,
  "goal": "Locate configuration files and enforce mutual exclusivity with browserslist.findConfigFile",
  "kind": "HOW",
  "packages": [
    "pkg:npm/browserslist@4.28.9"
  ],
  "symbols": [
    "browserslist.findConfigFile"
  ]
}

import assert from 'node:assert/strict';
import fs from 'node:fs';
import path from 'node:path';
import os from 'node:os';
import browserslist from 'browserslist';
import { findConfigFile } from '../index.js';

const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'csx-bll-contract-'));

try {
  // 1. browserslist.findConfigFile(dir) discovers .browserslistrc files and returns their absolute path
  const dir1 = path.join(tmpDir, 'case1');
  fs.mkdirSync(dir1, { recursive: true });
  const rc1 = path.join(dir1, '.browserslistrc');
  fs.writeFileSync(rc1, '> 1%\n');
  assert.strictEqual(browserslist.findConfigFile(dir1), rc1);
  assert.strictEqual(findConfigFile(dir1), rc1);

  // 2. browserslist.findConfigFile(dir) discovers browserslist files without extension and returns their absolute path
  const dir2 = path.join(tmpDir, 'case2');
  fs.mkdirSync(dir2, { recursive: true });
  const bfile2 = path.join(dir2, 'browserslist');
  fs.writeFileSync(bfile2, 'last 2 versions\n');
  assert.strictEqual(browserslist.findConfigFile(dir2), bfile2);
  assert.strictEqual(findConfigFile(dir2), bfile2);

  // 3. browserslist.findConfigFile(dir) discovers package.json with browserslist field and returns its absolute path
  const dir3 = path.join(tmpDir, 'case3');
  fs.mkdirSync(dir3, { recursive: true });
  const pkg3 = path.join(dir3, 'package.json');
  fs.writeFileSync(pkg3, JSON.stringify({ browserslist: ['defaults'] }));
  assert.strictEqual(browserslist.findConfigFile(dir3), pkg3);
  assert.strictEqual(findConfigFile(dir3), pkg3);

  // 4. browserslist.findConfigFile(childDir) traverses parent directories to discover configuration files
  const dir4Parent = path.join(tmpDir, 'case4');
  const dir4Child = path.join(dir4Parent, 'nested', 'child');
  fs.mkdirSync(dir4Child, { recursive: true });
  const rc4 = path.join(dir4Parent, '.browserslistrc');
  fs.writeFileSync(rc4, 'defaults\n');
  assert.strictEqual(browserslist.findConfigFile(dir4Child), rc4);
  assert.strictEqual(findConfigFile(dir4Child), rc4);

  // 5. browserslist.findConfigFile(dir) ignores package.json lacking a browserslist configuration section
  const dir5Parent = path.join(tmpDir, 'case5');
  const dir5Child = path.join(dir5Parent, 'child');
  fs.mkdirSync(dir5Child, { recursive: true });
  const rc5 = path.join(dir5Parent, '.browserslistrc');
  fs.writeFileSync(rc5, 'defaults\n');
  const pkg5 = path.join(dir5Child, 'package.json');
  fs.writeFileSync(pkg5, JSON.stringify({ name: 'unrelated-subpackage' }));
  assert.strictEqual(browserslist.findConfigFile(dir5Child), rc5);
  assert.strictEqual(findConfigFile(dir5Child), rc5);

  // 6. browserslist.findConfigFile(dir) returns undefined when no configuration file exists in the directory tree
  const dir6 = path.join(tmpDir, 'case6');
  fs.mkdirSync(dir6, { recursive: true });
  assert.strictEqual(browserslist.findConfigFile(dir6), undefined);
  assert.strictEqual(findConfigFile(dir6), undefined);

  // 7. browserslist.findConfigFile(dir) throws BrowserslistError when both .browserslistrc and package.json with browsers exist
  const dir7 = path.join(tmpDir, 'case7');
  fs.mkdirSync(dir7, { recursive: true });
  fs.writeFileSync(path.join(dir7, '.browserslistrc'), 'defaults\n');
  fs.writeFileSync(path.join(dir7, 'package.json'), JSON.stringify({ browserslist: ['defaults'] }));
  assert.throws(
    () => browserslist.findConfigFile(dir7),
    (err) => err.name === 'BrowserslistError' && err.message.includes('contains both .browserslistrc and package.json with browsers')
  );

  // 8. browserslist.findConfigFile(dir) throws BrowserslistError when both browserslist and package.json with browsers exist
  const dir8 = path.join(tmpDir, 'case8');
  fs.mkdirSync(dir8, { recursive: true });
  fs.writeFileSync(path.join(dir8, 'browserslist'), 'defaults\n');
  fs.writeFileSync(path.join(dir8, 'package.json'), JSON.stringify({ browserslist: ['defaults'] }));
  assert.throws(
    () => browserslist.findConfigFile(dir8),
    (err) => err.name === 'BrowserslistError' && err.message.includes('contains both browserslist and package.json with browsers')
  );

  // 9. browserslist.findConfigFile(dir) throws BrowserslistError when both .browserslistrc and browserslist exist
  const dir9 = path.join(tmpDir, 'case9');
  fs.mkdirSync(dir9, { recursive: true });
  fs.writeFileSync(path.join(dir9, '.browserslistrc'), 'defaults\n');
  fs.writeFileSync(path.join(dir9, 'browserslist'), 'defaults\n');
  assert.throws(
    () => browserslist.findConfigFile(dir9),
    (err) => err.name === 'BrowserslistError' && err.message.includes('contains both .browserslistrc and browserslist')
  );

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