monocart-coverage-reports 2.12.11 → 2.13.0

package/README.md

@@ -66,7 +66,7 @@
 * [Thanks](#thanks)
 
 ## Usage
-> It's recommended to use [Node.js 20+](https://nodejs.org/).
+> [Node.js 22+](https://nodejs.org/) is recommended and is the actively maintained target.
 - Install
 ```sh
 npm install monocart-coverage-reports
@@ -89,6 +89,8 @@ import { CoverageReport } from 'monocart-coverage-reports';
 const mcr = new CoverageReport();
 await mcr.loadConfig();
 ```
+> Both `MCR({...})` and `new CoverageReport()` create the same instance. `MCR()` is a shorthand factory function; use `new CoverageReport()` when you prefer class instantiation or need to call `loadConfig()` separately.
+
 For more information, see [Multiprocessing Support](#multiprocessing-support)
 
 - CLI
@@ -106,7 +108,7 @@ For more information, see [Command Line](#command-line)
 | :-- | :-- | :-- | :-- |
 | `logging` | `"off" \| "error" \| "info" \| "debug"` | `"info"` | Logging level. Use `"debug"` to keep raw cache and dump sourcemaps for troubleshooting. See [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap). |
 | `name` | `string` | `"Coverage Report"` | Report title shown in the UI and summary reports. |
-| `reports` | `string \| (string \| ReportDescription)[]` | `"v8"` (V8) / `"html"` (Istanbul) | Reports to generate. See [Available Reports](#available-reports). |
+| `reports` | `string \| (string \| ReportDescription)[]` | `""` (auto) | Reports to generate. Defaults to `"v8"` for V8 data and `"html"` for Istanbul data. See [Available Reports](#available-reports). |
 | `outputDir` | `string` | `"./coverage-reports"` | Output directory for all reports and the `.cache` folder. |
 | `inputDir` | `string \| string[]` | `null` | Input directories of raw coverage data for [merging](#merge-coverage-reports). |
 | `baseDir` | `string` | `process.cwd()` | Base dir used to normalize relative source paths. Set when the report is generated from a different working directory than the sources. |
@@ -123,15 +125,13 @@ For more information, see [Command Line](#command-line)
 | `v8Ignore` | `boolean` | `true` | (V8 only) Enable/disable comment-based ignoring (`v8 ignore …`). See [Ignoring Uncovered Codes](#ignoring-uncovered-codes). |
 | `reportPath` | `string \| () => string` | `null` | Override the report entry path (defaults to `outputDir/index.html`). Useful when multiple reports share an `outputDir`. |
 | `watermarks` | `[number, number] \| object` | `[50, 80]` | Low/high thresholds (percent). Accepts per-metric object like `{ bytes:[50,80], lines:[50,80] }`. |
-| `clean` | `boolean` | `true` | Clean previous reports in `outputDir` before generating. |
-| `cleanCache` | `boolean` | `false` | Clean the cache dir on start. |
+| `clean` | `boolean` | `true` | Clean previous reports in `outputDir` before generating (the `.cache` dir is preserved unless `cleanCache` is also `true`). |
+| `cleanCache` | `boolean` | `false` | Clean the cache dir on start. When both `clean` and `cleanCache` are `false`, cached coverage data from previous runs is preserved and can be reused across processes. |
 | `gc` | `number` | `null` | Memory threshold in MB; force GC at critical stages when RSS exceeds it. Useful for very large data sets, see [JavaScript heap out of memory](#javascript-heap-out-of-memory). |
 | `sourceMap` | `boolean` | `false` | Save source/sourcemap files to cache for debugging (requires `logging: "debug"`). |
 | `sourceMapResolver` | `(url, defaultResolver) => Promise<string \| object>` | `null` | Custom sourcemap loader (e.g. from a build cache). Call `defaultResolver(url)` to fall back. |
 | `onEntry` | `(entry) => void \| Promise<void>` | `null` | (V8 only) Per-entry hook; see [Hooks](#hooks). |
 | `onEnd` | `(coverageResults) => void \| Promise<void>` | `null` | Hook invoked after report generation; see [Hooks](#hooks). |
-| `onStart` | `(coverageReport) => void \| Promise<void>` | `null` | (CLI only) Before the child process starts; see [Hooks](#hooks). |
-| `onReady` | `(coverageReport, nodeV8CoverageDir, subprocess) => void \| Promise<void>` | `null` | (CLI only) After the child exits, before MCR reads coverage data; see [Hooks](#hooks). |
 
 ## Available Reports
 
@@ -223,6 +223,11 @@ cat path-to/coverage-summary.md >> $GITHUB_STEP_SUMMARY
     - V8 custom reporter
     > example: [./test/custom-v8-reporter.js](./test/custom-v8-reporter.js)
 
+    The `type` option determines which coverage format the reporter receives:
+    - `'istanbul'` — the reporter receives Istanbul-format coverage data (`coverageResults.istanbulData`).
+    - `'v8'` — the reporter receives native V8-format coverage data (`coverageResults.v8Data`).
+    - `'both'` — the reporter receives both formats, accessible via `coverageResults.v8Data` and `coverageResults.istanbulData`.
+
 ### Multiple Reports:
 ```js
 const MCR = require('monocart-coverage-reports');
@@ -526,7 +531,22 @@ export type V8CoverageData = ScriptCoverage[];
 | Firefox (2%) | ❌ |  |
 | Node.js | ✅ |  |
 | Deno | ❌ | [issue](https://github.com/denoland/deno/issues/23359) |
-| Bun | ❌ |  |
+| Bun | ❌ | [issue](https://github.com/oven-sh/bun/issues/30968) |
+
+> MCR extends each V8 coverage entry with additional fields:
+
+| Field | Type | Description |
+| :-- | :-- | :-- |
+| `url` | `string` | Script URL or file path |
+| `type` | `"js" \| "css"` | Entry type |
+| `source` | `string` | (JS) Source code text |
+| `sourceMap` | `object` | (JS) Parsed sourcemap object |
+| `scriptOffset` | `number` | (JS) Byte offset for the script wrapper (e.g. in `vm` modules). This offset is automatically added to all range start/end values |
+| `distFile` | `string` | (JS) The dist bundle file this source was unpacked from |
+| `empty` | `boolean` | Marked as `true` when this entry was added via the `all` option (no real coverage data), showing 0% coverage |
+| `fake` | `boolean` | Marked as `true` when the source code is not original (e.g. compiled from `.ts`/`.jsx`). The AST parser skips coverage extraction for fake sources |
+
+These fields can be read/mutated in [`onEntry`](#hooks) hooks.
 
 ## Filtering Results
 ### Using `entryFilter` and `sourceFilter` to filter the results for V8 report
@@ -847,7 +867,19 @@ npx mcr node ./test/specs/node.test.js -r v8,console-details --lcov
 ```
 
 - CLI Options
-see all options with running `mcr` or `mcr --help`
+
+The options below are only available when using the CLI (`mcr <command>`):
+
+| Option | Type | Default | Description |
+| :-- | :-- | :-- | :-- |
+| `-c, --config` | `string` | — | Custom config file path |
+| `--import` | `string` | `null` | Preload ESM module via `NODE_OPTIONS`, e.g. `tsx` for TypeScript. Requires Node.js `>= 18.19` |
+| `--require` | `string` | `null` | Preload CJS module via `NODE_OPTIONS` |
+| `--env` | `string` | `null` | Load environment variables from a dotenv file (defaults to `.env`). Requires Node.js `>= 20.6` |
+| `onStart` | `(coverageReport) => Promise<void>` | `null` | Runs before the child process is spawned; see [Hooks](#hooks) |
+| `onReady` | `(coverageReport, nodeV8CoverageDir, subprocess) => Promise<void>` | `null` | Runs after the child exits, before MCR reads coverage; see [Hooks](#hooks) |
+
+For other options (e.g. `--name`, `--reports`, `--outputDir`, `--lcov`, etc.), see the [Options](#options) table — they work the same way in CLI.
 
 - Use `--` to separate sub CLI args
 ```sh
@@ -864,6 +896,12 @@ mcr --import tsx node ./test.ts
 mcr --env .env.test node ./test.js
 ```
 
+- `merge`: merge raw coverage data from `inputDir`(s) and generate merged reports directly, without running a child process.
+```sh
+mcr merge -r v8,console-details --inputDir ./coverage-reports/unit/raw,./coverage-reports/e2e/raw --outputDir ./coverage-reports/merged
+```
+See [Merge Coverage Reports](#merge-coverage-reports).
+
 - Examples
     - [Mocha](#mocha)
     - [TypeScript](#typescript)
@@ -1234,7 +1272,7 @@ const coverageOptions = {
 ```
 
 ## Contributing
-- Node.js 20+
+- Node.js 22+ (recommended development version)
 - VSCode (extensions: eslint/stylelint/vue)
 ```sh
 npm install

package/README.zh-Hans.md

@@ -66,7 +66,7 @@
 * [感谢](#thanks)
 
 ## Usage
-> 推荐使用 [Node.js 20+](https://nodejs.org/).
+> 推荐使用 [Node.js 22+](https://nodejs.org/)，项目将其作为持续维护的目标版本。
 - 安装
 ```sh
 npm install monocart-coverage-reports
@@ -89,6 +89,8 @@ import { CoverageReport } from 'monocart-coverage-reports';
 const mcr = new CoverageReport();
 await mcr.loadConfig();
 ```
+> `MCR({...})` 和 `new CoverageReport()` 创建的是同一个实例。`MCR()` 是简写工厂函数；`new CoverageReport()` 更适合需要单独调用 `loadConfig()` 的场景。
+
 参见 [多进程支持](#multiprocessing-support)
 
 - CLI
@@ -106,7 +108,7 @@ mcr node my-app.js -r v8,console-details
 | :-- | :-- | :-- | :-- |
 | `logging` | `"off" \| "error" \| "info" \| "debug"` | `"info"` | 日志级别。设为 `"debug"` 会保留原始缓存并输出 sourcemap，便于排查问题。参见 [调试覆盖率和sourcemap](#debug-for-coverage-and-sourcemap)。 |
 | `name` | `string` | `"Coverage Report"` | 报告标题，显示在 UI 以及 summary 报告中。 |
-| `reports` | `string \| (string \| ReportDescription)[]` | V8 默认 `"v8"` / Istanbul 默认 `"html"` | 生成哪些报告，参见 [所有支持的报告类型](#available-reports)。 |
+| `reports` | `string \| (string \| ReportDescription)[]` | `""` (自动) | 生成哪些报告。V8 数据默认 `"v8"`，Istanbul 数据默认 `"html"`。参见 [所有支持的报告类型](#available-reports)。 |
 | `outputDir` | `string` | `"./coverage-reports"` | 所有报告以及 `.cache` 的输出目录。 |
 | `inputDir` | `string \| string[]` | `null` | 导入的原始覆盖率数据目录（用于 [合并](#merge-coverage-reports)）。 |
 | `baseDir` | `string` | `process.cwd()` | 规范化相对源路径的基准目录。当生成报告的工作目录和源码目录不一致时需要设置。 |
@@ -123,15 +125,13 @@ mcr node my-app.js -r v8,console-details
 | `v8Ignore` | `boolean` | `true` | （仅 V8）启用/禁用基于注释的忽略（`v8 ignore …`），参见 [忽略未覆盖代码](#ignoring-uncovered-codes)。 |
 | `reportPath` | `string \| () => string` | `null` | 覆盖默认的报告入口路径（默认 `outputDir/index.html`）。多个报告共用同一 `outputDir` 时很有用。 |
 | `watermarks` | `[number, number] \| object` | `[50, 80]` | 覆盖率高/低阈值百分比。也支持按指标配置：`{ bytes:[50,80], lines:[50,80] }`。 |
-| `clean` | `boolean` | `true` | 生成报告前清理 `outputDir` 中的旧报告。 |
-| `cleanCache` | `boolean` | `false` | 启动时清理缓存目录。 |
+| `clean` | `boolean` | `true` | 生成报告前清理 `outputDir` 中的旧报告（`.cache` 目录在 `cleanCache` 也为 `true` 时才会被清理）。 |
+| `cleanCache` | `boolean` | `false` | 启动时清理缓存目录。当 `clean` 和 `cleanCache` 都为 `false` 时，之前运行的缓存数据会保留，可在多进程间复用。 |
 | `gc` | `number` | `null` | 内存阈值（MB），在关键阶段若 RSS 超过阈值则强制触发 GC，适用于超大数据集，参见 [JavaScript heap out of memory](#javascript-heap-out-of-memory)。 |
 | `sourceMap` | `boolean` | `false` | 将源文件和 sourcemap 也保存到 cache 便于调试（需要 `logging: "debug"`）。 |
 | `sourceMapResolver` | `(url, defaultResolver) => Promise<string \| object>` | `null` | 自定义 sourcemap 加载逻辑（例如从构建缓存中读取），可调用 `defaultResolver(url)` 回退到默认解析。 |
 | `onEntry` | `(entry) => void \| Promise<void>` | `null` | （仅 V8）每个入口文件处理前触发，参见 [Hooks](#hooks)。 |
 | `onEnd` | `(coverageResults) => void \| Promise<void>` | `null` | 报告生成完成后触发，参见 [Hooks](#hooks)。 |
-| `onStart` | `(coverageReport) => void \| Promise<void>` | `null` | （仅 CLI）子进程启动前触发，参见 [Hooks](#hooks)。 |
-| `onReady` | `(coverageReport, nodeV8CoverageDir, subprocess) => void \| Promise<void>` | `null` | （仅 CLI）子进程退出后、MCR 读取覆盖率数据前触发，参见 [Hooks](#hooks)。 |
 
 ## Available Reports
 
@@ -223,6 +223,11 @@ cat path-to/coverage-summary.md >> $GITHUB_STEP_SUMMARY
     - V8自定义报告
     > 例子: [./test/custom-v8-reporter.js](./test/custom-v8-reporter.js)
 
+    `type` 选项决定报告接收的覆盖率数据格式：
+    - `'istanbul'` — 报告接收 Istanbul 格式的覆盖率数据（`coverageResults.istanbulData`）。
+    - `'v8'` — 报告接收原生 V8 格式的覆盖率数据（`coverageResults.v8Data`）。
+    - `'both'` — 报告同时接收两种格式，可通过 `coverageResults.v8Data` 和 `coverageResults.istanbulData` 访问。
+
 ### Multiple Reports:
 如何配置多个报告
 ```js
@@ -530,7 +535,22 @@ export type V8CoverageData = ScriptCoverage[];
 | Firefox (2%) | ❌ |  |
 | Node.js | ✅ |  |
 | Deno | ❌ | [issue](https://github.com/denoland/deno/issues/23359) |
-| Bun | ❌ |  |
+| Bun | ❌ | [issue](https://github.com/oven-sh/bun/issues/30968) |
+
+> MCR 为每个 V8 覆盖率条目扩展了以下字段：
+
+| 字段 | 类型 | 说明 |
+| :-- | :-- | :-- |
+| `url` | `string` | 脚本 URL 或文件路径 |
+| `type` | `"js" \| "css"` | 条目类型 |
+| `source` | `string` | （JS）源代码文本 |
+| `sourceMap` | `object` | （JS）已解析的 sourcemap 对象 |
+| `scriptOffset` | `number` | （JS）脚本包裹层的字节偏移（例如 `vm` 模块中）。此偏移会自动加到所有 range 的 start/end 值上 |
+| `distFile` | `string` | （JS）该 source 解包自的 dist 打包文件 |
+| `empty` | `boolean` | 当条目通过 `all` 选项添加（无真实覆盖率数据）时标记为 `true`，显示为 0% 覆盖 |
+| `fake` | `boolean` | 当源代码非原始代码（例如从 `.ts`/`.jsx` 编译而来）时标记为 `true`。AST 解析器会跳过 fake 源的覆盖率提取 |
+
+这些字段可以在 [`onEntry`](#hooks) 钩子中读取或修改。
 
 ## Filtering Results
 ### Using `entryFilter` and `sourceFilter` to filter the results for V8 report
@@ -849,8 +869,20 @@ npm i monocart-coverage-reports
 npx mcr node ./test/specs/node.test.js -r v8,console-details --lcov
 ```
 
-- 命令行参数
-直接运行 `mcr` 或 `mcr --help` 查看所有CLI的参数
+- CLI 选项
+
+以下选项仅在 CLI 模式（`mcr <command>`）下可用：
+
+| 选项 | 类型 | 默认值 | 说明 |
+| :-- | :-- | :-- | :-- |
+| `-c, --config` | `string` | — | 自定义配置文件路径 |
+| `--import` | `string` | `null` | 通过 `NODE_OPTIONS` 预加载 ESM 模块，如 `tsx`。需要 Node.js `>= 18.19` |
+| `--require` | `string` | `null` | 通过 `NODE_OPTIONS` 预加载 CJS 模块 |
+| `--env` | `string` | `null` | 从 dotenv 文件加载环境变量（默认 `.env`）。需要 Node.js `>= 20.6` |
+| `onStart` | `(coverageReport) => Promise<void>` | `null` | 子进程启动前触发；参见 [Hooks](#hooks) |
+| `onReady` | `(coverageReport, nodeV8CoverageDir, subprocess) => Promise<void>` | `null` | 子进程退出后、MCR 读取覆盖率前触发；参见 [Hooks](#hooks) |
+
+其他选项（如 `--name`、`--reports`、`--outputDir`、`--lcov` 等）参见 [选项配置](#options) 表格，它们在 CLI 中的用法相同。
 
 - 使用 `--` 可以隔离子程序参数，以免两种参数混淆
 ```sh
@@ -867,6 +899,12 @@ mcr --import tsx node ./test.ts
 mcr --env .env.test node ./test.js
 ```
 
+- `merge`: 直接合并 `inputDir` 中的原始覆盖率数据并生成合并报告，无需启动子进程。
+```sh
+mcr merge -r v8,console-details --inputDir ./coverage-reports/unit/raw,./coverage-reports/e2e/raw --outputDir ./coverage-reports/merged
+```
+参见 [合并覆盖率报告](#merge-coverage-reports)。
+
 - 参见例子
     - [Mocha](#mocha)
     - [TypeScript](#typescript)
@@ -1239,7 +1277,7 @@ const coverageOptions = {
 ```
 
 ## Contributing
-- Node.js 20+
+- Node.js 22+（推荐的开发版本）
 - VSCode (extensions: eslint/stylelint/vue)
 ```sh
 npm install

package/lib/assets.js

@@ -53,7 +53,7 @@ const Assets = {
         });
 
         // html content
-        let htmlStr = '';
+        let htmlStr;
         const EOL = Util.getEOL();
         if (inline) {
             htmlStr = [

package/lib/converter/converter.js

@@ -89,7 +89,7 @@ const applyBytesToLines = (bytes, locator, lineMap) => {
         } = lineItem;
 
         // default count to 1, both js and css
-        let count = 1;
+        let count;
         // full covered true/false for entire line
         let covered = true;
 
@@ -288,9 +288,9 @@ const collectFileCoverage = (v8Data, state, options) => {
     sortRanges(data.functions);
 
     // branch group with locations to flat branches
-    data.branches = branches.map((info) => {
+    data.branches = branches.flatMap((info) => {
         return info.getRanges();
-    }).flat();
+    });
     sortRanges(data.branches);
 
     data.statements = statements.map((info) => {
@@ -326,21 +326,36 @@ const collectFileCoverage = (v8Data, state, options) => {
         b: {}
     };
 
-    statements.filter((it) => !it.ignored).forEach((statement, index) => {
+    let index = 0;
+    for (const statement of statements) {
+        if (statement.ignored) {
+            continue;
+        }
         istanbulData.statementMap[`${index}`] = statement.generate(locator);
         istanbulData.s[`${index}`] = statement.count;
-    });
+        index += 1;
+    }
 
-    functions.filter((it) => !it.ignored).forEach((fn, index) => {
+    index = 0;
+    for (const fn of functions) {
+        if (fn.ignored) {
+            continue;
+        }
         istanbulData.fnMap[`${index}`] = fn.generate(locator, index);
         istanbulData.f[`${index}`] = fn.count;
-    });
+        index += 1;
+    }
 
-    branches.filter((it) => !it.ignored).forEach((branch, index) => {
+    index = 0;
+    for (const branch of branches) {
+        if (branch.ignored) {
+            continue;
+        }
         const { map, counts } = branch.generate(locator);
         istanbulData.branchMap[`${index}`] = map;
         istanbulData.b[`${index}`] = counts;
-    });
+        index += 1;
+    }
 
     return istanbulData;
 
@@ -1610,7 +1625,7 @@ const mergeV8Data = (state, stateList) => {
 
     // ===========================================================
     // functions
-    const allFunctions = stateList.map((it) => it.functions).flat();
+    const allFunctions = stateList.flatMap((it) => it.functions);
     const functionComparer = (lastRange, range) => {
         // if (lastRange.start === range.start && lastRange.end === range.end) {
         //     return true;
@@ -1649,7 +1664,7 @@ const mergeV8Data = (state, stateList) => {
 
     // ===========================================================
     // statements
-    const allStatements = stateList.map((it) => it.statements).flat();
+    const allStatements = stateList.flatMap((it) => it.statements);
     const statementComparer = (lastRange, range) => {
         // exact matched because the statement range is generated from ast
         return lastRange.start === range.start && lastRange.end === range.end;
@@ -1663,7 +1678,7 @@ const mergeV8Data = (state, stateList) => {
 
     // ===========================================================
     // branches
-    const allBranches = stateList.map((it) => it.branches).flat();
+    const allBranches = stateList.flatMap((it) => it.branches);
     const branchComparer = (lastRange, range) => {
         // exact matched because the branch range is generated from ast
         return lastRange.start === range.start && lastRange.end === range.end;
@@ -1743,7 +1758,7 @@ const generateV8DataList = (stateList, options) => {
 
     // merge istanbul and v8(converted)
     const mergeMap = new Map();
-    allOriginalList.flat().forEach((originalState) => {
+    allOriginalList.flatMap((arr) => arr).forEach((originalState) => {
         const { v8Data } = originalState;
         const id = v8Data.id;
         // exists item