monocart-coverage-reports 3.0.0 → 3.1.0

package/README.md

@@ -13,6 +13,7 @@
 > A JavaScript code coverage tool to generate native [V8](https://v8.dev/blog/javascript-code-coverage) reports or [Istanbul](https://istanbul.js.org/) reports.
 
 * [Usage](#usage)
+* [Best Practices](#best-practices)
 * [Options](#options)
 * [Available Reports](#available-reports)
 * [Compare Reports](#compare-reports)
@@ -103,8 +104,22 @@ mcr node my-app.js -r v8,console-details
 ```
 For more information, see [Command Line](#command-line)
 
+## Best Practices
+
+For new test setups, prefer native coverage collection without an instrumentation step:
+
+| Target | Recommended setup | Responsibility |
+| --- | --- | --- |
+| Node.js | **Node.js native test runner + `mcr test`** | `node:test` runs assertions; MCR automatically collects native V8 JavaScript coverage and generates reports. |
+| Browser | **Playwright Test + MCR** | Playwright runs assertions; automatic fixtures collect Chromium JS/CSS coverage; MCR merges it and generates reports. |
+| Browser with integrated test reporting | **Playwright Test + [monocart-reporter](https://github.com/cenfun/monocart-reporter#code-coverage-report)** | The reporter already integrates MCR; configure its coverage option and submit coverage from fixtures for unified test and coverage reporting. |
+
+For detailed setup instructions and examples, see the [best-practices guide](skills/monocart-coverage-reports/references/best-practices.md).
+
 ## AI Agent Skill
 
+For AI-assisted development in a source checkout, start with [AGENTS.md](https://github.com/cenfun/monocart-coverage-reports/blob/main/AGENTS.md). It describes the source layout, development commands, validation, and safety boundaries. `.github/copilot-instructions.md` provides a self-contained summary of the core rules for GitHub Copilot. These checkout-only guides are not included in the npm package and are separate from the reusable integration skill below.
+
 The reusable [Monocart Coverage Reports skill](skills/monocart-coverage-reports/SKILL.md) helps AI coding agents collect coverage, configure the CLI, debug sourcemaps and filters, merge raw reports, and enforce CI thresholds. It uses a main `SKILL.md` with task-specific references loaded on demand, targeting MCR 3.x only and checking its runtime requirements.
 
 The npm package includes `skills/monocart-coverage-reports/`. Copy this **entire directory**, including `references/`, into your agent's supported skills location, or ask the agent to read `SKILL.md` directly. Installing MCR does not automatically register the skill or modify agent settings. The instructions are in English; requests and responses can use any language.
@@ -354,11 +369,18 @@ const [jsCoverage, cssCoverage] = await Promise.all([
 const coverageData = [... jsCoverage, ... cssCoverage];
 
 ```
-Collect coverage with `@playwright/test` [`Automatic fixtures`](https://playwright.dev/docs/test-fixtures#automatic-fixtures), see example: [fixtures.ts](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.ts)
+For Playwright Test automatic fixtures, see [fixtures.js](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.js) in the complete [playwright-coverage example](https://github.com/cenfun/playwright-coverage). The [best-practices guide](skills/monocart-coverage-reports/references/best-practices.md#complete-project-example) explains the integration.
 For more examples, see [./test/test-v8.js](./test/test-v8.js), [css](./test/test-css.js)
 
 
 ### Collecting Raw V8 Coverage Data with Puppeteer
+
+> Depending on your package manager, Puppeteer may not download a browser during installation. If no browser is available, install one manually:
+>
+> ```sh
+> npx puppeteer browsers install chrome
+> ```
+
 ```js
 await Promise.all([
     page.coverage.startJSCoverage({
@@ -716,6 +738,8 @@ const coverageOptions = {
     }
 };
 ```
+Built-in report path normalization is best-effort; it cannot fully reconcile every nonstandard, virtual, or foreign-platform path. Use `sourcePath` to correct these special cases rather than relying on automatic inference. The callback receives the normalized `filePath`; for V8 entries and sourcemap sources, `info.url` provides the original URL before report path normalization (including the sourcemap's `sourceRoot`, when present). This rewrites report paths, not the filesystem paths used to load missing source content. When `sourcesContent` is missing, local sources are loaded relative to the external map's URL (or the generated file for inline maps), with `sourceRoot` applied as a directory.
+
 It also supports simple key/value replacement:
 ```js
 const coverageOptions = {
@@ -741,7 +765,7 @@ const coverageOptions = {
 ```
 
 ## Adding Empty Coverage for Untested Files
-By default the untested files will not be included in the coverage report. Use `all` to include them with 0% coverage. This also works when no coverage data has been collected: a V8 report is generated from the matching untested files.
+Untested files are excluded by default. Use `all` to include them with 0% coverage, even when no coverage data was collected. For the same original source, real V8 coverage takes precedence over empty entries.
 ```js
 const coverageOptions = {
     all: './src'
@@ -1243,6 +1267,27 @@ const coverageOptions = {
 process.env.MCR_LOG_TIME = true;
 ```
 
+### CSS coverage issues
+
+CSS coverage from multiple bundles is merged as a union for each original source.
+
+For preprocessor syntax that `all` cannot parse directly, use `all.transformer` to compile to CSS, set `entry.type = 'css'`, and preserve the sourcemap.
+
+#### Sass mixins and `@include`
+
+Sass `@include` can map a generated rule to non-contiguous source locations. When a rule cannot be reliably mapped, MCR reports the **whole bundle as generated CSS** instead of the preprocessor sources. That bundle's coverage is not merged into the original-source coverage.
+
+#### Line coverage of untested preprocessor sources
+
+Untested files included through `all` have `0%` byte coverage, including sourcemap originals. Lines outside parsed or mapped rules (such as variables or unused mixins) may appear covered; use **bytes** coverage for these files.
+
+#### Source map can be inaccurate after minification
+CSS minification can produce imprecise sourcemaps and trigger fallback to generated CSS. If source mapping is inaccurate, try **disabling CSS minification**.
+
+#### V8 covered the whole block
+
+Chromium may mark an entire media query or nested CSS block as covered. Consider [postcss-atomic-selectors](https://www.npmjs.com/package/postcss-atomic-selectors) as a potential workaround.
+
 ## Integration with Any Testing Framework
 - API
     - Collecting coverage data when any stage of the test is completed, and adding the coverage data to the coverage reporter. `await mcr.add(coverageData)`

package/README.zh-Hans.md

@@ -13,6 +13,7 @@
 > JS代码覆盖率工具，用来生成原生的[V8](https://v8.dev/blog/javascript-code-coverage)或者[Istanbul](https://istanbul.js.org/)代码覆盖率报告
 
 * [用法](#usage)
+* [最佳实践](#best-practices)
 * [选项配置](#options)
 * [所有支持的报告类型](#available-reports)
 * [比较两种报告](#compare-reports)
@@ -103,8 +104,22 @@ mcr node my-app.js -r v8,console-details
 ```
 参见 [命令行](#command-line)
 
+## Best Practices
+
+为新项目建立测试方案时，优先使用无需插桩的原生覆盖率采集：
+
+| 测试目标 | 推荐方案 | 职责划分 |
+| --- | --- | --- |
+| Node.js 端 | **Node.js 原生 test runner + `mcr test`** | `node:test` 执行测试断言；MCR 自动采集 JavaScript 原生 V8 覆盖率并生成报告。 |
+| 浏览器端 | **Playwright Test + MCR** | Playwright 执行测试断言；自动 fixture 采集 Chromium JS/CSS 覆盖率；MCR 合并并生成报告。 |
+| 浏览器端，需要统一测试报告 | **Playwright Test + [monocart-reporter](https://github.com/cenfun/monocart-reporter#code-coverage-report)** | reporter 已集成 MCR；配置其 coverage 选项，并由 fixture 提交覆盖率数据，统一管理测试报告和覆盖率报告。 |
+
+详细配置步骤和示例见[最佳实践指南](skills/monocart-coverage-reports/references/best-practices.md)。
+
 ## AI Agent Skill
 
+使用 AI 辅助开发本仓库源码时，请先阅读 [AGENTS.md](https://github.com/cenfun/monocart-coverage-reports/blob/main/AGENTS.md)，了解源码结构、开发命令、验证流程和安全边界。`.github/copilot-instructions.md` 为 GitHub Copilot 提供可独立使用的核心规则摘要。这些指南仅用于源码仓库，不随 npm 包发布，与下面可复用的集成技能相互独立。
+
 项目提供可复用的 [Monocart Coverage Reports 技能](skills/monocart-coverage-reports/SKILL.md)，帮助 AI coding agent 采集覆盖率、配置 CLI、排查 sourcemap 和过滤问题、合并 raw 报告及设置 CI 阈值。结构为主 `SKILL.md` 加按需加载的专题参考文档，仅面向 MCR 3.x，并检查其运行环境要求。
 
 npm 包包含 `skills/monocart-coverage-reports/`。请将**整个目录**（包括 `references/`）复制到 agent 支持的 skills 目录，或直接让 agent 读取 `SKILL.md`。安装 MCR 不会自动注册技能或修改 agent 配置。技能说明使用英文，但提问和回复可以使用中文或其他语言。
@@ -356,11 +371,18 @@ const [jsCoverage, cssCoverage] = await Promise.all([
 const coverageData = [... jsCoverage, ... cssCoverage];
 
 ```
-使用 `@playwright/test` 的 [`Automatic fixtures`](https://playwright.dev/docs/test-fixtures#automatic-fixtures)收集覆盖率数据, 见例子: [fixtures.ts](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.ts)
+Playwright Test 自动 fixture 参见完整 [playwright-coverage 示例](https://github.com/cenfun/playwright-coverage)中的 [fixtures.js](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.js)，接入方式见[最佳实践指南](skills/monocart-coverage-reports/references/best-practices.md#complete-project-example)。
 参见例子 [./test/test-v8.js](./test/test-v8.js), [css](./test/test-css.js)
 
 
 ### Collecting Raw V8 Coverage Data with Puppeteer
+
+> 取决于包管理器配置，Puppeteer 可能不会在安装依赖时下载浏览器。如果没有可用浏览器，请手动安装：
+>
+> ```sh
+> npx puppeteer browsers install chrome
+> ```
+
 使用Puppeteer的覆盖接口收集覆盖率数据，注意Puppeteer默认不会提供原生V8的覆盖率数据，需要设置`includeRawScriptCoverage`
 ```js
 await Promise.all([
@@ -719,6 +741,8 @@ const coverageOptions = {
     }
 };
 ```
+内置报告路径规范化采用尽力而为的原则，无法完全兼容所有非标准、虚拟或来自其他操作系统的路径。此类特殊情况应通过 `sourcePath` 自行修正，而不是依赖自动推断。回调接收规范化后的 `filePath`；对于 V8 入口和 sourcemap 源文件，`info.url` 提供报告路径规范化前的原始 URL（sourcemap 存在 `sourceRoot` 时包含该前缀）。它修改的是报告路径，不是读取缺失源码时使用的文件系统路径。缺少 `sourcesContent` 时，本地源码相对于外部 map 的 URL 加载（内联 map 则相对于生成文件），并将 `sourceRoot` 作为目录应用。
+
 它也支持简单key/value的替换:
 ```js
 const coverageOptions = {
@@ -744,7 +768,7 @@ const coverageOptions = {
 ```
 
 ## Adding Empty Coverage for Untested Files
-默认，未测试的文件不会包含在覆盖率报告中。使用 `all` 选项可将它们以 0% 覆盖率加入报告。即使没有收集到任何覆盖率数据，也会为匹配的未测试文件生成 V8 报告。
+默认不包含未测试文件。使用 `all` 可将它们以 0% 覆盖率加入报告，即使没有采集到任何覆盖率数据也可生成报告。同一原始源码的真实 V8 覆盖率优先于空覆盖率条目。
 ```js
 const coverageOptions = {
     all: './src'
@@ -1246,6 +1270,27 @@ const coverageOptions = {
 process.env.MCR_LOG_TIME = true;
 ```
 
+### CSS 覆盖率与 sourcemap
+
+多个 bundle 映射到同一原始文件时，CSS 覆盖率取并集。
+
+对于 `all` 无法直接解析的预处理器语法，请使用 `all.transformer` 编译为 CSS，设置 `entry.type = 'css'`，并保留 sourcemap。
+
+#### Sass mixin 与 `@include`
+
+Sass `@include` 可能将一条生成规则映射到不连续的源码位置。规则无法可靠映射时，MCR 会将**整个 bundle 按生成的 CSS 展示**，而不是预处理器源文件；该 bundle 的覆盖率也不会合并到原始源码的覆盖率中。
+
+#### 未测试预处理源文件的行覆盖率
+
+通过 `all` 加入的未测试文件，其字节覆盖率为 `0%`，包括 sourcemap 还原的原始文件。解析或映射规则之外的行（如变量、未使用的 mixin）可能显示为已覆盖；请以 **bytes** 覆盖率为准。
+
+#### 压缩后 sourcemap 可能不准确
+CSS 压缩可能产生不准确的 sourcemap，导致报告回退到生成的 CSS。遇到映射不准确时，可尝试**禁用 CSS 压缩**。
+
+#### V8 会将整个 block 视为已覆盖
+
+Chromium 可能将整个 media query 或嵌套 CSS block 标记为已覆盖。可考虑使用 [postcss-atomic-selectors](https://www.npmjs.com/package/postcss-atomic-selectors) 作为临时解决方案。
+
 ## Integration with Any Testing Framework
 通用集成方案
 - 通过API接口在程序集成

package/lib/converter/ast.js

@@ -345,8 +345,29 @@ const getCssAstInfo = (item, coverageList) => {
             endOffset: it.end
         };
     });
-
-    const ast = parseCss(source);
+    let ast;
+    try {
+        ast = parseCss(source);
+    } catch (error) {
+        // Untested files may use preprocessor syntax that postcss cannot parse.
+        // Mirror the JS empty-file fallback: report the whole file as uncovered
+        // instead of aborting report generation.
+        if (empty) {
+            coverageList.push({
+                start: 0,
+                end: source.length,
+                count: 0
+            });
+            return {
+                functions: [],
+                branches: [],
+                statements: []
+            };
+        }
+        throw new Error(`parse css error in ${item.sourcePath}`, {
+            cause: error
+        });
+    }
 
     addCssRules(ast.nodes, coverageList, coveredRanges, empty);
 

package/lib/converter/collect-source-maps.js

@@ -121,27 +121,41 @@ const resolveMapUrl = (filename, url) => {
 
 const resolveSourcesContent = (data, url) => {
 
-    const { sources, sourcesContent } = data;
+    const {
+        sources, sourcesContent, sourceRoot
+    } = data;
+    // sourceRoot is a directory, even when its trailing slash is omitted.
+    let rootUrl;
+    if (typeof sourceRoot === 'string' && sourceRoot) {
+        rootUrl = Util.resolveUrl(sourceRoot.endsWith('/') ? sourceRoot : `${sourceRoot}/`, url);
+    }
 
     // sources [1,2,3]
     // sourcesContent could be [null, null, "content"]
     // some of contents could be missed
 
     let hasSourceContent = false;
+    const missingSources = [];
     sources.forEach((file, i) => {
         if (typeof sourcesContent[i] === 'string') {
             hasSourceContent = true;
             return;
         }
 
-        const sourceUrl = Util.resolveUrl(file, url);
+        const sourceUrl = Util.resolveUrl(file, rootUrl?.href || url);
         if (sourceUrl) {
-            let sourcePath = sourceUrl.toString();
-            // could be no `file:`
-            if (sourcePath.startsWith('file:')) {
-                sourcePath = fileURLToPath(sourcePath);
+            let content;
+            try {
+                let sourcePath = sourceUrl.toString();
+                // Read actual local paths, not normalized virtual report paths.
+                if (sourceUrl.protocol === 'file:') {
+                    sourcePath = fileURLToPath(sourceUrl);
+                }
+                content = Util.readFileSync(path.resolve(sourcePath));
+            } catch {
+                // A foreign or malformed file URL is just an unavailable source.
+                // Keep resolving the other sources instead of discarding the map.
             }
-            const content = Util.readFileSync(path.resolve(sourcePath));
             if (typeof content === 'string') {
                 sourcesContent[i] = content;
                 hasSourceContent = true;
@@ -149,13 +163,18 @@ const resolveSourcesContent = (data, url) => {
             }
         }
 
-        sourcesContent[i] = '';
+        missingSources.push(i);
         Util.logDebug(EC.red(`failed to load source content: ${file}`));
 
     });
 
 
     if (hasSourceContent) {
+        // Only commit placeholders for accepted maps. A rejected map may be
+        // cached by the resolver and must not look like valid empty sources later.
+        missingSources.forEach((i) => {
+            sourcesContent[i] = '';
+        });
         return data;
     }
 };
@@ -233,7 +252,7 @@ const collectSourceMaps = async (v8list, options) => {
     for (const item of v8list) {
 
         const {
-            type, url, id, source, sourceMap
+            url, id, source, sourceMap
         } = item;
 
         // source and sourceMap will be saved as separated file (could be cached)
@@ -258,7 +277,7 @@ const collectSourceMaps = async (v8list, options) => {
 
         // An explicitly supplied, usable map takes precedence over sourceMappingURL.
         // Keep the original source so V8 offsets remain valid.
-        if (type === 'js' && !isUsableSourceMap(sourceData.sourceMap)) {
+        if (!isUsableSourceMap(sourceData.sourceMap)) {
             delete sourceData.sourceMap;
             const candidates = getSourceMapCandidates(source);
             if (candidates.length) {
@@ -279,7 +298,7 @@ const collectSourceMaps = async (v8list, options) => {
         const { url } = sourceData;
         for (const candidate of candidates) {
             let data;
-            let sourceMapUrl;
+            let sourceMapUrl = url;
             try {
                 if (candidate.inline) {
                     data = convertSourceMap.fromComment(candidate.comment).sourcemap;
@@ -293,7 +312,9 @@ const collectSourceMaps = async (v8list, options) => {
                 if (!isUsableSourceMap(data)) {
                     continue;
                 }
-                const sourceMap = resolveSourceMap(data, url);
+                // Inline maps inherit the generated file's URL. External maps
+                // resolve their sources relative to the map, not the bundle.
+                const sourceMap = resolveSourceMap(data, sourceMapUrl);
                 if (!sourceMap) {
                     continue;
                 }

package/lib/converter/converter.js

@@ -11,16 +11,18 @@ import { Util } from '../utils/util.js';
 
 import { findOriginalRange } from './find-original-range.js';
 import { isUncoveredRange } from './source-range-merge.js';
+import { mergeCssBytes } from './css-coverage.js';
 import { handleUncoveredInCovered } from './fake-source-coverage.js';
 import { getJsAstInfo, getCssAstInfo } from './ast.js';
 import { getIgnoredRanges } from './ignore.js';
 
 import { getUntestedList } from './untested.js';
-
 import {
     sortRanges, dedupeCountRanges, mergeRangesWith
 } from '../utils/dedupe.js';
-import { getSourceType, initSourceMapSourcesPath } from '../utils/source-path.js';
+import {
+    getSourceType, initSourceMapSourcesPath, cssTypes
+} from '../utils/source-path.js';
 
 import { decode } from '@jridgewell/sourcemap-codec';
 
@@ -831,16 +833,71 @@ const handleOriginalEmptyBytesCoverage = (state, originalStateMap) => {
     });
 };
 
-
 const handleAllOriginalBytesCoverage = (state, originalStateMap) => {
 
-    const { js, coverageList } = state;
+    const {
+        js, coverageList, type
+    } = state;
+
+    if (cssTypes.has(type)) {
+        // An intentional exclusion is not a broken source map, even when all
+        // sources were excluded and there is nothing left to map.
+        if (state.filteredSourceIndexes.size > 0 && state.filteredSourceIndexes.size === state.sourceMap.sources.length) {
+            return;
+        }
+        const positionMap = new Map();
+        const couldMapAllRanges = coverageList.every((range) => {
+            const {
+                start, end, originalState, error, filtered
+            } = findOriginalRange(range.start, range.end, state, originalStateMap, {
+                fixOriginalRange: true
+            });
+
+            if (filtered) {
+                return true;
+            }
+            if (error) {
+                return false;
+            }
+
+            // Offsets are local to each source, not unique across the bundle.
+            let positions = positionMap.get(originalState);
+            if (!positions) {
+                positions = new Set();
+                positionMap.set(originalState, positions);
+            }
+            const positionKey = `${start}-${end}`;
+            if (positions.has(positionKey)) {
+                return false;
+            }
+            positions.add(positionKey);
+            originalState.bytes.push({
+                start, end, count: range.count
+            });
+            return true;
+        });
+
+        // make sure every range mapped correctly,
+        // otherwise discard changes and fall back to dist file to show at least some meaningful coverage.
+        // Sass `@include` is a common case: one generated rule maps to both the
+        // call site and the mixin body, which cannot be one contiguous original
+        // range. See "Sass mixins and @include" in README.
+        if (!couldMapAllRanges) {
+            Util.logDebug(`Could not map all ranges, fallback to dist file for ${EC.yellow(state.sourcePath)}`);
+            state.v8Data.dedupe = false;
+            // The fallback is now a real report file, not a debug-only copy.
+            delete state.v8Data.debug;
+            state.originalList = [];
+            originalStateMap.clear();
+            generateCoverageForDist(state);
+        }
 
-    // only for js, no sourcemap for css for now
-    if (!js) {
         return;
     }
 
+    if (!js) {
+        return;
+    }
     // v8 coverage
     coverageList.forEach((block) => {
         block.ranges.forEach((range) => {
@@ -1046,7 +1103,6 @@ const getOriginalDecodedMappings = (originalDecodedMap, sourceIndex, locator) =>
 };
 
 // ========================================================================================================
-
 const initOriginalList = (state, originalDecodedMap, options) => {
 
     // source filter
@@ -1054,6 +1110,9 @@ const initOriginalList = (state, originalDecodedMap, options) => {
 
     // create original content mappings
     const originalStateMap = new Map();
+    if (!state.js) {
+        state.filteredSourceIndexes = new Set();
+    }
 
     const { sources, sourcesContent } = state.sourceMap;
 
@@ -1065,7 +1124,7 @@ const initOriginalList = (state, originalDecodedMap, options) => {
         // filter
         // do not change for sourceIndex
         if (!sourceFilter(sourcePath)) {
-            // console.log('-', sourcePath);
+            state.filteredSourceIndexes?.add(sourceIndex);
             return;
         }
         // console.log(sourcePath);
@@ -1082,14 +1141,12 @@ const initOriginalList = (state, originalDecodedMap, options) => {
 
         const decodedMappings = getOriginalDecodedMappings(originalDecodedMap, sourceIndex, locator);
 
-        // unpacked file always is js
-
         const type = getSourceType(sourcePath);
 
         const originalState = {
             original: true,
-            // original file is js
-            js: true,
+            // Only known style types are CSS; preserve JS coverage for all other sources.
+            js: !cssTypes.has(type),
             type,
             source: sourceContent,
             sourcePath,
@@ -1149,6 +1206,12 @@ const collectOriginalList = (state, originalStateMap) => {
             source
         };
 
+        // Sourcemap gaps must not count as covered bytes for untested files.
+        // Keep the marker so real coverage can replace this entry during merge.
+        if (state.v8Data.empty) {
+            sourceItem.empty = true;
+        }
+
         // save v8 data and add to originalList
         originalState.v8Data = sourceItem;
         state.originalList.push(originalState);
@@ -1695,8 +1758,14 @@ const generateV8DataList = (stateList, options, needsIstanbul) => {
         // exists item
         const prevState = stateMap.get(id);
         if (prevState) {
-            // ignore empty item, just override it
-            if (!prevState.v8Data.empty) {
+            // Empty entries and debug copies must not replace real original
+            // coverage, nor contribute a duplicate execution to its merge.
+            if (!prevState.v8Data.empty && !prevState.v8Data.debug) {
+                // An untested build may contain different mapped AST nodes
+                // (for example ES5 helpers). It must not alter real metrics.
+                if (v8Data.empty) {
+                    return;
+                }
                 if (mergeMap.has(id)) {
                     mergeMap.get(id).push(originalState);
                 } else {
@@ -1715,7 +1784,7 @@ const generateV8DataList = (stateList, options, needsIstanbul) => {
         if (state.js) {
             mergeV8Data(state, mergeMap.get(id));
         } else {
-            // should no css here, css can not be in sources
+            state.bytes = mergeCssBytes(mergeMap.get(id).map((it) => it.bytes));
         }
     }
 

package/lib/converter/css-coverage.js

@@ -0,0 +1,76 @@
+const getCssRangePoints = (groups) => {
+    const points = [];
+    groups.forEach((ranges) => {
+        ranges.forEach(({
+            start, end, count
+        }) => {
+            if (start >= end) {
+                return;
+            }
+            const covered = count > 0 ? 1 : 0;
+            const uncovered = count > 0 ? 0 : 1;
+            points.push({
+                offset: start, covered, uncovered
+            }, {
+                offset: end, covered: -covered, uncovered: -uncovered
+            });
+        });
+    });
+    return points.sort((a, b) => a.offset - b.offset);
+};
+
+const appendCssRange = (merged, start, end, count) => {
+    const last = merged[merged.length - 1];
+    if (last && last.end === start && last.count === count) {
+        last.end = end;
+    } else {
+        merged.push({
+            start, end, count
+        });
+    }
+};
+
+const sweepCssBytes = (groups, uncoveredWins) => {
+    const points = getCssRangePoints(groups);
+    const merged = [];
+    let start = 0;
+    let covered = 0;
+    let uncovered = 0;
+    for (const point of points) {
+        const end = point.offset;
+        if (start < end && (covered > 0 || uncovered > 0)) {
+            const count = uncoveredWins ? Number(uncovered === 0) : Number(covered > 0);
+            appendCssRange(merged, start, end, count);
+        }
+        covered += point.covered;
+        uncovered += point.uncovered;
+        start = end;
+    }
+    return merged;
+};
+
+const isSortedDisjoint = (ranges) => {
+    let end = -Infinity;
+    for (const range of ranges) {
+        if (!(range.start >= end && range.start < range.end)) {
+            return false;
+        }
+        end = range.end;
+    }
+    return true;
+};
+
+// Within one bundle an uncovered child overrides its covered wrapper. Only
+// after that interpretation may coverage from separate bundles be unioned.
+// Unmapped gaps stay absent from this union; this function does not turn them
+// into covered ranges. Byte summaries still derive covered bytes from total
+// length minus explicit uncovered ranges, so gaps without an uncovered range
+// are reported as covered. Use the line/code views when gaps matter.
+const mergeCssBytes = (groups) => {
+    // Ordered, disjoint ranges already have unambiguous per-bundle coverage.
+    // Reuse them without allocating intermediate events and normalized ranges.
+    const normalized = groups.map((ranges) => (isSortedDisjoint(ranges) ? ranges : sweepCssBytes([ranges], true)));
+    return sweepCssBytes(normalized, false);
+};
+
+export { mergeCssBytes };