monocart-coverage-reports 2.12.10 → 2.12.12

package/README.md

@@ -26,7 +26,7 @@
 * [Filtering Results](#filtering-results)
 * [Resolve `sourcePath` for the Source Files](#resolve-sourcepath-for-the-source-files)
 * [Adding Empty Coverage for Untested Files](#adding-empty-coverage-for-untested-files)
-* [onEnd Hook](#onend-hook)
+* [Hooks](#hooks)
 * [Ignoring Uncovered Codes](#ignoring-uncovered-codes)
 * [Multiprocessing Support](#multiprocessing-support)
 * [Command Line](#command-line)
@@ -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
@@ -102,9 +104,38 @@ For more information, see [Command Line](#command-line)
 - Options declaration see `CoverageReportOptions` [lib/index.d.ts](./lib/index.d.ts)
 - [Config file](#config-file)
 
+| Option | Type | Default | Description |
+| :-- | :-- | :-- | :-- |
+| `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)[]` | `""` (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. |
+| `dataDir` | `string` | `null` | Coverage data directory loaded automatically in `generate()` — alternative to `addFromDir()`. |
+| `entryFilter` | `string \| object \| function` | `null` | (V8 only) Filter V8 entries by url. See [Filtering Results](#filtering-results). |
+| `sourceFilter` | `string \| object \| function` | `null` | (V8 only) Filter sources unpacked from sourcemaps. |
+| `filter` | `string \| object \| function` | `null` | Combined filter replacing both `entryFilter` and `sourceFilter`. |
+| `sourcePath` | `object \| function` | `null` | Rewrite source paths; see [Resolve `sourcePath`](#resolve-sourcepath-for-the-source-files). |
+| `all` | `string \| string[] \| object` | `null` | Include untested files as empty coverage. See [Adding Empty Coverage](#adding-empty-coverage-for-untested-files). |
+| `outputFile` | `string` | `"index.html"` | (V8 only) Output `[sub dir/]filename` for the V8 report. |
+| `inline` | `boolean` | `false` | (V8 only) Inline all assets into a single HTML file. |
+| `assetsPath` | `string` | `"./assets"` | (V8 only) Assets directory when `inline` is false. |
+| `lcov` | `boolean` | `false` | Also generate `lcov.info` (equivalent to adding the `lcovonly` report). |
+| `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 (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). |
+
 ## Available Reports
 
-> V8 build-in reports (V8 data only):
+> V8 built-in reports (V8 data only):
 
 - `v8`
     - Features: 
@@ -124,7 +155,7 @@ For more information, see [Command Line](#command-line)
 
 ![](./assets/mcv.gif)
 
-> Istanbul build-in reports (both V8 and Istanbul data):
+> Istanbul built-in reports (both V8 and Istanbul data):
 
 - `clover`
 - `cobertura`
@@ -144,7 +175,7 @@ For more information, see [Command Line](#command-line)
 - `text-lcov`
 - `text-summary`
 
-> Other build-in reports (both V8 and Istanbul data):
+> Other built-in reports (both V8 and Istanbul data):
 
 - `codecov` Save coverage data to a json file with [Codecov](https://docs.codecov.com/docs/codecov-custom-coverage-format) format (defaults to `codecov.json`), see [example](https://app.codecov.io/github/cenfun/monocart-coverage-reports).
 
@@ -192,13 +223,18 @@ 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');
 const coverageOptions = {
     outputDir: './coverage-reports',
     reports: [
-        // build-in reports
+        // built-in reports
         ['console-summary'],
         ['v8'],
         ['html', {
@@ -464,7 +500,7 @@ export interface CoverageRange {
  * @functionName can be an empty string.
  * @ranges is always non-empty. The first range is called the "root range".
  * @isBlockCoverage indicates if the function has block coverage information.
-    If this is false, it usually means that the functions was never called.
+    If this is false, it usually means that the function was never called.
     It seems to be equivalent to ranges.length === 1 && ranges[0].count === 0.
 */
 export interface FunctionCoverage {
@@ -495,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
@@ -572,7 +623,7 @@ const coverageOptions = {
     filter: {
         '**/node_modules/**': false,
         '**/vendor.js': false,
-        '**/src/**': true
+        '**/src/**': true,
         '**/**': true
     }
 };
@@ -672,8 +723,10 @@ const coverageOptions = {
 };
 ```
 
-## onEnd Hook
-For example, checking thresholds:
+## Hooks
+
+### `onEnd` — after the report is generated
+Typical use case: enforce coverage thresholds.
 ```js
 const EC = require('eight-colors');
 const coverageOptions = {
@@ -703,6 +756,29 @@ const coverageOptions = {
 }
 ```
 
+### `onEntry` — before each V8 entry is processed (V8 only)
+Use this to mutate the entry (for example, transform non-standard sources into valid ECMAScript before the AST parser runs). See [Unparsable source](#unparsable-source).
+```js
+const coverageOptions = {
+    onEntry: async (entry) => {
+        // entry.source, entry.sourceMap, entry.fake, ...
+    }
+};
+```
+
+### `onStart` / `onReady` — CLI-only
+Only available when using `mcr <command>`:
+- `onStart(coverageReport)` — runs before the child process is spawned.
+- `onReady(coverageReport, nodeV8CoverageDir, subprocess)` — runs after the child exits, before MCR reads coverage from `nodeV8CoverageDir`. Useful when the child hasn't finished flushing coverage data and needs to be waited on.
+```js
+// mcr.config.js
+module.exports = {
+    onReady: async (coverageReport, nodeV8CoverageDir, subprocess) => {
+        // wait for something, or pre-process the raw files
+    }
+};
+```
+
 ## Ignoring Uncovered Codes
 To ignore codes, use the special comment which starts with `v8 ignore `:
 - Ignoring all until stop
@@ -715,9 +791,9 @@ function uncovered() {
 - Ignoring the next line or next N lines
 ```js
 /* v8 ignore next */
-const os = platform === 'wind32' ? 'Windows' : 'Other';
+const os = platform === 'win32' ? 'Windows' : 'Other';
 
-const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
+const os = platform === 'win32' ? 'Windows' /* v8 ignore next */ : 'Other';
 
 // v8 ignore next 3
 if (platform === 'linux') {
@@ -736,6 +812,7 @@ function uncovered() {
 }
 /* node:coverage enable */
 ```
+- To disable comment-based ignoring entirely, set `v8Ignore: false`.
 
 ## Multiprocessing Support
 > The data will be added to `[outputDir]/.cache`, After the generation of the report, this data will be removed unless debugging has been enabled or a raw report has been used, see [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
@@ -790,13 +867,41 @@ 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
 mcr -c mcr.config.js -- sub-cli -c sub-cli.config.js
 ```
 
+- `--import <module>` / `--require <module>`: forward a preload module to the child process via `NODE_OPTIONS`. Use this for TypeScript/JSX runtimes (`tsx`, `ts-node`, etc.) and also when loading a `mcr.config.ts`. Requires Node.js `>= 18.19`.
+```sh
+mcr --import tsx node ./test.ts
+```
+
+- `--env [path]`: load environment variables from a dotenv file before the child starts (defaults to `.env`). Requires `process.loadEnvFile`, added in Node.js `20.6`.
+```sh
+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)
@@ -811,7 +916,12 @@ Loading config file by priority:
 - `mcr.config.cjs`
 - `mcr.config.mjs`
 - `mcr.config.json` - json format
-- `mcr.config.ts` (requires preloading the ts execution module)
+- `mcr.config.ts` (requires preloading the TypeScript execution module, for example with `tsx`):
+```sh
+mcr --import tsx -c mcr.config.ts node ./test.js
+```
+
+> If no custom path is given, MCR walks up from the current working directory to find the default config file (via [`find-up`](https://github.com/sindresorhus/find-up)). Files outside the search path will be ignored.
 
 ## Merge Coverage Reports
 The following usage scenarios may require merging coverage reports:
@@ -890,7 +1000,7 @@ const coverageOptions = {
     ],
     
     onEnd: () => {
-        // remove the raw files if it useless
+        // remove the raw files if no longer needed
         // inputDir.forEach((p) => {
         //     fs.rmSync(p, {
         //         recursive: true,
@@ -926,8 +1036,8 @@ In the generated code, there is a position `p`, and we need to find out its corr
 - Further understanding of sourcemap, try [Debug for Coverage and Sourcemap](#debug-for-coverage-and-sourcemap)
 
 How `MCR` Works:
-- 1, Trying to fix the original position with string comparison and [`diff-sequences`](https://github.com/jestjs/jest/tree/main/packages/diff-sequences). However, for non-JS code, such as Vue template, JSX, etc., it might be hard to find a perfect solution.
-- 2, Finding all functions, statements and branches by parsing the source code [AST](https://github.com/acornjs/acorn). (There is a small issue is the V8 cannot provide effective branch coverage information for `AssignmentPattern`)
+1. Tries to fix the original position with string comparison and [`diff-sequences`](https://github.com/jestjs/jest/tree/main/packages/diff-sequences). However, for non-JS code such as Vue templates or JSX, a perfect solution may not always be possible.
+2. Finds all functions, statements and branches by parsing the source code [AST](https://github.com/acornjs/acorn). (One small caveat: V8 cannot provide effective branch coverage information for `AssignmentPattern`.)
 
 
 ### Unparsable source
@@ -971,7 +1081,7 @@ const coverageOptions = {
     ]
 };
 ```
-When `logging` is `debug`, the raw report data will be preserved in `[outputDir]/.cache` or `[outputDir]/raw` if `raw` report is used. And the dist file will be preserved in the V8 list, and by opening the browser's devtool, it makes data verification visualization effortless.
+When `logging` is `debug`, the raw report data is preserved in `[outputDir]/.cache` (or `[outputDir]/raw` if the `raw` report is used). The dist file is also kept in the V8 list, so you can open the browser's devtools and visually verify the coverage data.
 ![](./assets/debug-coverage.png)
 
 - Check sourcemap with [Source Map Visualization](https://evanw.github.io/source-map-visualization/)

package/README.zh-Hans.md

@@ -26,7 +26,7 @@
 * [过滤V8覆盖率数据](#filtering-results)
 * [使用 `sourcePath` 修改源文件路径](#resolve-sourcepath-for-the-source-files)
 * [为未测试的文件添加空的覆盖率报告](#adding-empty-coverage-for-untested-files)
-* [onEnd回调函数](#onend-hook)
+* [回调钩子 Hooks](#hooks)
 * [如何忽略未覆盖的代码](#ignoring-uncovered-codes)
 * [多进程支持](#multiprocessing-support)
 * [如何使用CLI命令行](#command-line)
@@ -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
@@ -102,6 +104,35 @@ mcr node my-app.js -r v8,console-details
 - 选项的类型描述，见 `CoverageReportOptions` [lib/index.d.ts](./lib/index.d.ts)
 - [配置文件](#config-file)
 
+| 选项 | 类型 | 默认值 | 说明 |
+| :-- | :-- | :-- | :-- |
+| `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)。 |
+| `outputDir` | `string` | `"./coverage-reports"` | 所有报告以及 `.cache` 的输出目录。 |
+| `inputDir` | `string \| string[]` | `null` | 导入的原始覆盖率数据目录（用于 [合并](#merge-coverage-reports)）。 |
+| `baseDir` | `string` | `process.cwd()` | 规范化相对源路径的基准目录。当生成报告的工作目录和源码目录不一致时需要设置。 |
+| `dataDir` | `string` | `null` | `generate()` 阶段自动加载的覆盖率数据目录，作为 `addFromDir()` 的替代。 |
+| `entryFilter` | `string \| object \| function` | `null` | （仅 V8）按 URL 过滤入口文件，参见 [过滤V8覆盖率数据](#filtering-results)。 |
+| `sourceFilter` | `string \| object \| function` | `null` | （仅 V8）过滤从 sourcemap 解包出的源文件。 |
+| `filter` | `string \| object \| function` | `null` | 合并 `entryFilter` 和 `sourceFilter` 的统一过滤器。 |
+| `sourcePath` | `object \| function` | `null` | 修改源文件路径，参见 [使用 `sourcePath`](#resolve-sourcepath-for-the-source-files)。 |
+| `all` | `string \| string[] \| object` | `null` | 为未测试文件添加空覆盖率，参见 [为未测试的文件添加空的覆盖率报告](#adding-empty-coverage-for-untested-files)。 |
+| `outputFile` | `string` | `"index.html"` | （仅 V8）V8 报告的 `[子目录/]文件名`。 |
+| `inline` | `boolean` | `false` | （仅 V8）将所有资源内联到单一 HTML 文件。 |
+| `assetsPath` | `string` | `"./assets"` | （仅 V8）非内联模式下的资源目录。 |
+| `lcov` | `boolean` | `false` | 额外生成 `lcov.info`，等同于添加 `lcovonly` 报告。 |
+| `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` 中的旧报告（`.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)。 |
+
 ## Available Reports
 
 > 内置V8报告(仅V8格式数据支持):
@@ -192,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
@@ -199,7 +235,7 @@ const MCR = require('monocart-coverage-reports');
 const coverageOptions = {
     outputDir: './coverage-reports',
     reports: [
-        // build-in reports
+        // built-in reports
         ['console-summary'],
         ['v8'],
         ['html', {
@@ -468,7 +504,7 @@ export interface CoverageRange {
  * @functionName can be an empty string.
  * @ranges is always non-empty. The first range is called the "root range".
  * @isBlockCoverage indicates if the function has block coverage information.
-    If this is false, it usually means that the functions was never called.
+    If this is false, it usually means that the function was never called.
     It seems to be equivalent to ranges.length === 1 && ranges[0].count === 0.
 */
 export interface FunctionCoverage {
@@ -499,10 +535,25 @@ 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
+### Using `entryFilter` and `sourceFilter` to filter the results for V8 report
 当收集到V8的覆盖数据时，它实际上包含了所有的入口文件的覆盖率数据, 比如有以下3个文件:
 
 - *dist/main.js*
@@ -576,7 +627,7 @@ const coverageOptions = {
     filter: {
         '**/node_modules/**': false,
         '**/vendor.js': false,
-        '**/src/**': true
+        '**/src/**': true,
         '**/**': true
     }
 };
@@ -675,8 +726,10 @@ const coverageOptions = {
 };
 ```
 
-## onEnd Hook
-结束回调可以用来自定义业务需求，比如检测覆盖率是否达标，对比每个指标的thresholds，如果低于要求的值则可以抛出一个错误退出
+## Hooks
+
+### `onEnd` — 报告生成后触发
+典型用法：检测覆盖率是否达标，低于 threshold 时抛错退出。
 ```js
 const EC = require('eight-colors');
 const coverageOptions = {
@@ -706,6 +759,29 @@ const coverageOptions = {
 }
 ```
 
+### `onEntry` — 每个V8入口在处理前触发（仅V8）
+可以在进入AST解析前改写 entry（例如对非标准语法的源码做预编译），参见 [Unparsable source](#unparsable-source)
+```js
+const coverageOptions = {
+    onEntry: async (entry) => {
+        // entry.source, entry.sourceMap, entry.fake, ...
+    }
+};
+```
+
+### `onStart` / `onReady` — 仅CLI可用
+只在使用 `mcr <command>` 时有效:
+- `onStart(coverageReport)` — 子进程启动前触发
+- `onReady(coverageReport, nodeV8CoverageDir, subprocess)` — 子进程退出后、MCR 读取 `nodeV8CoverageDir` 之前触发。用于子进程尚未写完覆盖数据需要等待的场景
+```js
+// mcr.config.js
+module.exports = {
+    onReady: async (coverageReport, nodeV8CoverageDir, subprocess) => {
+        // 等待某个信号，或先对 raw 文件做一些预处理
+    }
+};
+```
+
 ## Ignoring Uncovered Codes
 使用特定的注释，以`v8 ignore `开头可以忽略未覆盖的代码:
 - 忽略开始到结束
@@ -718,9 +794,9 @@ function uncovered() {
 - 忽略接下来一行或者多行
 ```js
 /* v8 ignore next */
-const os = platform === 'wind32' ? 'Windows' : 'Other';
+const os = platform === 'win32' ? 'Windows' : 'Other';
 
-const os = platform === 'wind32' ? 'Windows' /* v8 ignore next */ : 'Other';
+const os = platform === 'win32' ? 'Windows' /* v8 ignore next */ : 'Other';
 
 // v8 ignore next 3
 if (platform === 'linux') {
@@ -739,6 +815,7 @@ function uncovered() {
 }
 /* node:coverage enable */
 ```
+- 可以设置 `v8Ignore: false` 完全禁用基于注释的忽略机制。
 
 ## Multiprocessing Support
 > 多进程支持可以很好的解决异步并行的情况。所有的覆盖率数据会保存到`[outputDir]/.cache`，在报告生成之后，这些缓存数据会被清除。除非开启了[调试模式](#debug-for-coverage-and-sourcemap)，或者使用了`raw`报告
@@ -792,14 +869,42 @@ 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
 mcr -c mcr.config.js -- sub-cli -c sub-cli.config.js
 ```
 
+- `--import <module>` / `--require <module>`: 通过 `NODE_OPTIONS` 把一个预加载模块传给子进程。常用于 TypeScript/JSX 运行时（`tsx`、`ts-node` 等），也可用于加载 `mcr.config.ts`。要求 Node.js `>= 18.19`
+```sh
+mcr --import tsx node ./test.ts
+```
+
+- `--env [path]`: 子进程启动前从 dotenv 文件加载环境变量（默认 `.env`）。依赖 `process.loadEnvFile`，Node.js `20.6` 起支持
+```sh
+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)
@@ -814,7 +919,12 @@ mcr -c mcr.config.js -- sub-cli -c sub-cli.config.js
 - `mcr.config.cjs`
 - `mcr.config.mjs`
 - `mcr.config.json` - json format
-- `mcr.config.ts` (requires preloading the ts execution module)
+- `mcr.config.ts` （需要预加载 TypeScript 执行模块，比如 `tsx`）:
+```sh
+mcr --import tsx -c mcr.config.ts node ./test.js
+```
+
+> 未指定自定义路径时，MCR 会从当前工作目录向上查找默认配置文件（通过 [`find-up`](https://github.com/sindresorhus/find-up)）。不在搜索路径内的文件会被忽略
 
 ## Merge Coverage Reports
 以下这些使用场景可能需要使用合并覆盖率报告：
@@ -892,7 +1002,7 @@ const coverageOptions = {
     ],
     
     onEnd: () => {
-        // remove the raw files if it useless
+        // remove the raw files if no longer needed
         // inputDir.forEach((p) => {
         //     fs.rmSync(p, {
         //         recursive: true,

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/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const path = require('path');
+const { pathToFileURL } = require('url');
 const EC = require('eight-colors');
 
 const { program } = require('commander');
@@ -11,12 +12,18 @@ const Util = require('./utils/util.js');
 
 const version = require('../package.json').version;
 
-const getRegisterPath = (filename) => {
-    const rel = Util.relativePath(path.resolve(__dirname, 'register', filename));
-    if (rel.startsWith('.')) {
-        return rel;
-    }
-    return `./${rel}`;
+// quote NODE_OPTIONS argument if it contains whitespace so child processes
+// inheriting the env var can parse it correctly
+const quoteNodeOption = (v) => ((/\s/).test(v) ? `"${v}"` : v);
+
+// absolute path so NODE_OPTIONS keeps resolving when child processes are
+// spawned with a different cwd than the mcr parent process
+const getRequirePath = () => {
+    return quoteNodeOption(path.resolve(__dirname, 'register', 'register.js'));
+};
+
+const getImportPath = () => {
+    return quoteNodeOption(pathToFileURL(path.resolve(__dirname, 'register', 'register.mjs')).href);
 };
 
 const getInitNodeOptions = async (cliOptions) => {
@@ -92,10 +99,10 @@ const initNodeOptions = async (cliOptions) => {
 
     // export source after
     if (preloadType === '--import') {
-        const importPath = getRegisterPath('register.mjs');
+        const importPath = getImportPath();
         nodeOptions.unshift(`--import ${importPath}`);
     } else {
-        const requirePath = getRegisterPath('register.js');
+        const requirePath = getRequirePath();
         nodeOptions.unshift(`--require ${requirePath}`);
     }
 
@@ -183,6 +190,7 @@ const executeCommand = async (command, cliOptions) => {
 process.on('uncaughtException', function(err) {
     Util.logError(`Process uncaughtException: ${err.message}`);
     console.log(err.stack);
+    process.exit(1);
 });
 
 // the -- separator