browserslist 4.28.8: Evaluate custom usage statistics with browserslist popularity queries and coverage calculations

# browserslist Public API Behavior

## Prior Findings
A network search found sample `sha256:5230d1d8374292e6b338e3af9d42b2f705868895b5c720d33aec72599fd6f335`, which focuses on configuration cache retention across Babel transforms. This project instead investigates `browserslist` query evaluation semantics with custom usage statistics, coverage calculation, empty query defaults, and query composition rules.

## Pinned Release
- `browserslist`: `4.28.8` (resolved via `npm`)
- Runtime: Node.js (tested on Node 24 ESM)

## Observed Behavior & Traps

### 1. Custom Statistics Evaluation in Popularity Queries
- **Trap**: When custom usage statistics are passed via `opts.stats`, standard popularity queries like `> 10%` or `cover 50%` do NOT evaluate against `opts.stats`. Instead, they silently query the global `caniuse-lite` usage database.
- **Failure Mode**: Silent semantic divergence. The build succeeds and produces browser targets, but targets match global market share rather than the custom telemetry dataset.
- **Correct Usage**: Custom stats are only evaluated when the query explicitly includes the clause `in my stats` (for example, `> 10% in my stats` or `cover 50% in my stats`).
- **Missing Stats**: Querying `> 10% in my stats` without supplying `opts.stats` throws a loud `BrowserslistError: Custom usage statistics was not provided`.

### 2. Coverage Calculation
- `browserslist.coverage(browsers, stats)` accepts the custom statistics map directly as its second argument without requiring the `in my stats` query keyword.
- `browserslist.coverage` does not deduplicate input arrays; passing duplicate entries like `['chrome 100', 'chrome 100']` sums their coverage percentages linearly.

### 3. Empty Queries vs. Default Queries
- `browserslist()` (with no arguments, `undefined`, or `null`) resolves to `browserslist.defaults` (`['> 0.5%', 'last 2 versions', 'Firefox ESR', 'not dead']`).
- Passing an explicit empty array `browserslist([])` or empty string `browserslist('')` evaluates directly to `[]` (empty list), rather than falling back to defaults.

### 4. Subtraction Query Ordering
- Queries containing `not <browser>` (such as `browserslist(['not ie 11'])`) act as set subtraction filters and require a preceding positive browser query to subtract from.
- Passing `['not ie 11']` at the start of a query array fails loudly with `BrowserslistError: Write any browsers query (for instance, defaults) before not ie 11`.

### 5. Version Validation
- An unrecognized browser version like `chrome 999` throws `BrowserslistError: Unknown version 999 of chrome` unless `ignoreUnknownVersions: true` is passed, in which case it evaluates to `[]`.

{"case":{"believed":"passing custom usage statistics via opts.stats causes standard popularity queries like '\u003e 10%' to automatically evaluate against the provided custom statistics","caseId":"case:sha256:d4e224a81d30c00eed4c1e15499b9502f021bc08484c472a829d1652bae31076","contract":["browserslist('\u003e 10%', { stats }) evaluates against global caniuse-lite usage data and ignores opts.stats unless the query explicitly contains 'in my stats'","browserslist('\u003e 10% in my stats', { stats }) evaluates against the custom usage data provided in opts.stats","browserslist('\u003e 10% in my stats') throws a BrowserslistError when opts.stats is omitted","browserslist.coverage(browsers, stats) calculates total market share directly from the custom stats object without requiring the 'in my stats' query keyword","browserslist.coverage sums duplicate entries in the browser list without internal deduplication","browserslist([]) returns an empty array rather than falling back to default queries","browserslist(['not ie 11']) throws a BrowserslistError because a 'not' query requires a preceding positive query set to subtract from","browserslist('chrome 999') throws an unknown version error unless ignoreUnknownVersions: true is passed"],"goal":"Evaluate custom usage statistics with browserslist popularity queries and coverage calculations","kind":"HOW","packages":["pkg:npm/browserslist@4.28.8"],"schemaVersion":1,"symbols":["browserslist","browserslist.coverage"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/browserslist@4.28.8"],"schemaVersion":1,"symbols":["browserslist","browserslist.coverage"],"verifierAdapter":"node-typescript@1"}

{
  "name": "npm-browserslist-api",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "npm-browserslist-api",
      "version": "1.0.0",
      "dependencies": {
        "browserslist": "4.28.8"
      }
    },
    "node_modules/baseline-browser-mapping": {
      "version": "2.11.14",
      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.14.tgz",
      "integrity": "sha512-JyJ954WzuIR8/FFzX0o5krdSTrBAkcCSRfWSleRsIHSWV+cZe2FI1PKggVkFke1hBldRs+LRxUczzE9iPmgZww==",
      "license": "Apache-2.0",
      "bin": {
        "baseline-browser-mapping": "dist/cli.cjs"
      },
      "engines": {
        "node": ">=6.0.0"
      }
    },
    "node_modules/browserslist": {
      "version": "4.28.8",
      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.8.tgz",
      "integrity": "sha512-V2NpofLblG64mfOtSgDhOJESZEGogzDMBv/q+W6oc4LXWP/q75eOXoOaaOu1EOadB9U4Bwx/e0yzbvwKH8zalA==",
      "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.12",
        "caniuse-lite": "^1.0.30001809",
        "electron-to-chromium": "^1.5.402",
        "node-releases": "^2.0.53",
        "update-browserslist-db": "^1.3.0"
      },
      "bin": {
        "browserslist": "cli.js"
      },
      "engines": {
        "node": "^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7"
      }
    },
    "node_modules/caniuse-lite": {
      "version": "1.0.30001809",
      "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001809.tgz",
      "integrity": "sha512-xxWVywk6a6Arlk+hymeycyn/VgqEfLDxupvhH/xiY5SJ/18kmi9o6MiO320DCUzypORHLtvh0I4i04tUhCNHNQ==",
      "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.408",
      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.408.tgz",
      "integrity": "sha512-SLoprcYpJ/OH2v2ps0+N5biv9H4/KBT3+YmmDew64TwK5y9j2wv7pMOFY7IorVkyMtEyLSCRlXKLsNlakeAlPw==",
      "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.53",
      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.53.tgz",
      "integrity": "sha512-D9UOmYG3UH1V+ENW56t5QXBwJw1YEY18ruVeus89Rw+SyIgjPkCO84bRzO3uNIYosJbNwiabWVn48o3uJLjxFQ==",
      "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.1",
      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.1.tgz",
      "integrity": "sha512-ZZ61DsRsOnakl74HAmp3oSN4aXUmEWXf+i/yv0h7tIBfICc3VdrFErQKUUKPgu3AMsTUMbcongALEN4l6GSUrQ==",
      "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": "npm-browserslist-api",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "browserslist": "4.28.8"
  }
}

import assert from 'node:assert/strict';
import browserslist from 'browserslist';

const customStats = {
  chrome: { '100': 15, '101': 25, '102': 35 },
  firefox: { '100': 10 }
};

// 1. browserslist('> 10%', { stats }) evaluates against global caniuse data, ignoring opts.stats
const globalRes = browserslist('> 10%', { stats: customStats });
assert.ok(!globalRes.includes('chrome 101'), 'Generic popularity query must not evaluate against opts.stats');
assert.ok(!globalRes.includes('chrome 102'), 'Generic popularity query must not evaluate against opts.stats');

// 2. browserslist('> 10% in my stats', { stats }) evaluates against opts.stats
const customRes = browserslist('> 10% in my stats', { stats: customStats });
assert.deepStrictEqual(customRes, ['chrome 102', 'chrome 101', 'chrome 100']);

// 3. browserslist('> 10% in my stats') throws when opts.stats is missing
assert.throws(
  () => browserslist('> 10% in my stats'),
  (err) => {
    return err.name === 'BrowserslistError' && err.message.includes('Custom usage statistics was not provided');
  }
);

// 4. browserslist.coverage(browsers, stats) calculates total market share directly from custom stats
const cov = browserslist.coverage(['chrome 100', 'firefox 100'], customStats);
assert.strictEqual(cov, 25);

// 5. browserslist.coverage sums duplicate entries without deduplicating
const singleCov = browserslist.coverage(['chrome 100'], customStats);
const dupCov = browserslist.coverage(['chrome 100', 'chrome 100'], customStats);
assert.strictEqual(singleCov, 15);
assert.strictEqual(dupCov, 30);

// 6. browserslist([]) returns [] rather than default queries
assert.deepStrictEqual(browserslist([]), []);
assert.deepStrictEqual(browserslist(''), []);
assert.ok(browserslist().length > 0);
assert.deepStrictEqual(browserslist(), browserslist(undefined));
assert.deepStrictEqual(browserslist(), browserslist(null));

// 7. browserslist(['not ie 11']) throws because 'not' query requires a preceding positive query
assert.throws(
  () => browserslist(['not ie 11']),
  (err) => {
    return err.name === 'BrowserslistError' && err.message.includes('Write any browsers query');
  }
);
const subtracted = browserslist(['chrome 100', 'chrome 101', 'not chrome 100']);
assert.deepStrictEqual(subtracted, ['chrome 101']);

// 8. browserslist('chrome 999') throws unless ignoreUnknownVersions: true is passed
assert.throws(
  () => browserslist('chrome 999'),
  (err) => {
    return err.name === 'BrowserslistError' && err.message.includes('Unknown version 999 of chrome');
  }
);
assert.deepStrictEqual(browserslist('chrome 999', { ignoreUnknownVersions: true }), []);

console.log('Contract passed successfully.');