browserslist 4.28.7: coverage

# browserslist Public API Behavior: browserslist.coverage

## Overview
This sample verifies the behavior and contract of `browserslist.coverage` in `browserslist@4.28.7`.

## Pinned Release
- `browserslist`: `4.28.7`
- Ecosystem: npm
- Runtime: Node.js (ESM)

## Observed Behaviors & Traps

### 1. Custom Statistics Handling
- `browserslist.coverage(browsers, stats)` directly accepts a custom statistics object (e.g. `{ chrome: { '100': 15 } }`) and computes total coverage without requiring the `in my stats` query clause.
- Browsers or versions not present in the custom statistics object contribute 0 to the calculated coverage.

### 2. Duplicate Browser Entries
- `browserslist.coverage` does not internally deduplicate input browser lists. Providing duplicate entries (e.g. `['chrome 100', 'chrome 100']`) linearly sums their coverage percentages.

### 3. Country / Regional Statistics
- Passing a two-letter uppercase region string (e.g. `'US'`) computes coverage using the regional usage data from `caniuse-lite`.
- Passing an unrecognized region name throws `BrowserslistError: Unknown region name \`<region>\``.

### 4. Default / Global Statistics
- Omitting the second argument calculates coverage against global usage data in `caniuse-lite`.

### 5. Input Validation
- Passing an empty browser array `[]` returns `0`.
- Passing a non-array value (or null/undefined) for the browsers argument throws `TypeError` because `browsers.reduce` is invoked directly.

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 browserslist.coverage in pkg:npm/browserslist@4.28.7
Kind: HOW

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

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:ce73fc4a5060c6d267fb9af9c4cb0a6c0bce2aa6c9f376fc4832d08fdf8a90be","contract":["browserslist.coverage(browsers, stats) calculates total market share directly from custom stats","browserslist.coverage sums duplicate entries in the browser list without internal deduplication","browserslist.coverage([]) returns 0 for an empty browser list","browserslist.coverage(browsers) evaluates against global caniuse-lite data by default","browserslist.coverage(browsers, country) evaluates against regional caniuse-lite data","browserslist.coverage returns 0 for browsers or versions not present in custom stats","browserslist.coverage throws BrowserslistError when given an unknown region code","browserslist.coverage throws TypeError when first argument is not an array"],"goal":"verify browserslist.coverage in pkg:npm/browserslist@4.28.7","kind":"HOW","packages":["pkg:npm/browserslist@4.28.7"],"schemaVersion":1,"symbols":["browserslist.coverage"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","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.7"],"schemaVersion":1,"subject":"pkg:npm/browserslist@4.28.7","symbols":["browserslist.coverage"],"verifierAdapter":"node-typescript@1"}

import browserslist from 'browserslist';

/**
 * Calculates total coverage for a given set of browser queries or browser targets.
 *
 * @param {string[]|string} browsers - Array of browser version targets or query.
 * @param {Object|string} [statsOrCountry] - Custom statistics map or country code.
 * @returns {number} Sum of coverage percentages.
 */
export function getCoverage(browsers, statsOrCountry) {
  const browserList = Array.isArray(browsers) ? browsers : browserslist(browsers);
  return browserslist.coverage(browserList, statsOrCountry);
}

export default browserslist;

{
  "name": "sample-browserslist-coverage",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-browserslist-coverage",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "browserslist": "4.28.7"
      }
    },
    "node_modules/baseline-browser-mapping": {
      "version": "2.11.24",
      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.24.tgz",
      "integrity": "sha512-hYrgxie335U08WqICoGqKRzV1HFXv6zdxwJE4ekCb80CM9a0SVVsN4QPwT67RraRo+9h8IATk6uxHJw7QSkdOg==",
      "license": "Apache-2.0",
      "bin": {
        "baseline-browser-mapping": "dist/cli.cjs"
      },
      "engines": {
        "node": ">=6.0.0"
      }
    },
    "node_modules/browserslist": {
      "version": "4.28.7",
      "resolved": "https://registry.npmjs.org/browserslist/-/browserslist-4.28.7.tgz",
      "integrity": "sha512-JxV13hNrFxqjOc8alRbq9dK1MM79NEXYpma2B2J4wAtpWS5zIEIKqWPGCl7N4o7Uc7B7itylh7SuDujATRyyTw==",
      "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.10.44",
        "caniuse-lite": "^1.0.30001806",
        "electron-to-chromium": "^1.5.393",
        "node-releases": "^2.0.51",
        "update-browserslist-db": "^1.2.3"
      },
      "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.430",
      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.430.tgz",
      "integrity": "sha512-e1QEj72Y4zd8RlNZVmoTg+iCOSVwpk05IOiiQwdrkwCSVlZfPthevErhE+nckGd2YbsXfp1SkisznhGVIXP2NQ==",
      "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.55",
      "resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.55.tgz",
      "integrity": "sha512-mIrE/Cw9y+9Au6dS5vDKDhQza9YvG6w+ZrS6X+ZzA7yFW/soAeaups4Qzn1bL6g5FVy8WtP79+0j82oPIbqRjQ==",
      "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.3",
      "resolved": "https://registry.npmjs.org/update-browserslist-db/-/update-browserslist-db-1.3.3.tgz",
      "integrity": "sha512-pJ2sYawQS0R/WI928Gj5GlPhTGzbMelq0+4INtSYNDV9ErKJcX6xjGWkoG/VnB3dpUm00zALaqkrUD77pO5TDQ==",
      "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-coverage",
  "version": "1.0.0",
  "description": "Clean-room sample verifying pkg:npm/browserslist@4.28.7 browserslist.coverage",
  "type": "module",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "browserslist": "4.28.7"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify browserslist.coverage in pkg:npm/browserslist@4.28.7",
  "kind": "HOW",
  "packages": [
    "pkg:npm/browserslist@4.28.7"
  ],
  "symbols": [
    "browserslist.coverage"
  ]
}

import assert from 'node:assert/strict';
import browserslist from 'browserslist';
import { getCoverage } from '../index.js';

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

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

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

// 3. browserslist.coverage([]) returns 0 for an empty browser list
assert.strictEqual(browserslist.coverage([]), 0);
assert.strictEqual(browserslist.coverage([], customStats), 0);
assert.strictEqual(getCoverage([], customStats), 0);

// 4. browserslist.coverage(browsers) evaluates against global caniuse-lite data by default
const defaultBrowsers = browserslist('last 2 versions');
const globalCov = browserslist.coverage(defaultBrowsers);
assert.ok(typeof globalCov === 'number');
assert.ok(globalCov > 50 && globalCov <= 100);

// 5. browserslist.coverage(browsers, country) evaluates against regional caniuse-lite data
const usBrowsers = browserslist('> 1% in US');
const usCov = browserslist.coverage(usBrowsers, 'US');
assert.ok(typeof usCov === 'number');
assert.ok(usCov > 50 && usCov <= 100);

// 6. browserslist.coverage returns 0 for browsers or versions not present in custom stats
const unknownCov = browserslist.coverage(['safari 14', 'chrome 999'], customStats);
assert.strictEqual(unknownCov, 0);

// 7. browserslist.coverage throws BrowserslistError when given an unknown region code
assert.throws(
  () => browserslist.coverage(['chrome 100'], 'INVALID_REGION'),
  (err) => {
    return err.name === 'BrowserslistError' && err.message.includes('Unknown region name');
  }
);

// 8. browserslist.coverage throws TypeError when first argument is not an array with reduce method
assert.throws(
  () => browserslist.coverage(null),
  (err) => err instanceof TypeError
);
assert.throws(
  () => browserslist.coverage('chrome 100'),
  (err) => err instanceof TypeError
);

console.log('All contract assertions passed successfully.');