monocart-coverage-reports 2.12.10 → 2.12.11

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)
@@ -102,9 +102,40 @@ 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)[]` | `"v8"` (V8) / `"html"` (Istanbul) | Reports to generate. 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. |
+| `cleanCache` | `boolean` | `false` | Clean the cache dir on start. |
+| `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
 
-> 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).
 
@@ -198,7 +229,7 @@ const MCR = require('monocart-coverage-reports');
 const coverageOptions = {
     outputDir: './coverage-reports',
     reports: [
-        // build-in reports
+        // built-in reports
         ['console-summary'],
         ['v8'],
         ['html', {
@@ -464,7 +495,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 {
@@ -572,7 +603,7 @@ const coverageOptions = {
     filter: {
         '**/node_modules/**': false,
         '**/vendor.js': false,
-        '**/src/**': true
+        '**/src/**': true,
         '**/**': true
     }
 };
@@ -672,8 +703,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 +736,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 +771,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 +792,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)
@@ -797,6 +854,16 @@ see all options with running `mcr` or `mcr --help`
 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
+```
+
 - Examples
     - [Mocha](#mocha)
     - [TypeScript](#typescript)
@@ -811,7 +878,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 +962,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 +998,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 +1043,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)
@@ -102,6 +102,37 @@ 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` 中的旧报告。 |
+| `cleanCache` | `boolean` | `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
 
 > 内置V8报告(仅V8格式数据支持):
@@ -199,7 +230,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 +499,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 {
@@ -502,7 +533,7 @@ export type V8CoverageData = ScriptCoverage[];
 | Bun | ❌ |  |
 
 ## 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 +607,7 @@ const coverageOptions = {
     filter: {
         '**/node_modules/**': false,
         '**/vendor.js': false,
-        '**/src/**': true
+        '**/src/**': true,
         '**/**': true
     }
 };
@@ -675,8 +706,10 @@ const coverageOptions = {
 };
 ```
 
-## onEnd Hook
-结束回调可以用来自定义业务需求，比如检测覆盖率是否达标，对比每个指标的thresholds，如果低于要求的值则可以抛出一个错误退出
+## Hooks
+
+### `onEnd` — 报告生成后触发
+典型用法：检测覆盖率是否达标，低于 threshold 时抛错退出。
 ```js
 const EC = require('eight-colors');
 const coverageOptions = {
@@ -706,6 +739,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 +774,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 +795,7 @@ function uncovered() {
 }
 /* node:coverage enable */
 ```
+- 可以设置 `v8Ignore: false` 完全禁用基于注释的忽略机制。
 
 ## Multiprocessing Support
 > 多进程支持可以很好的解决异步并行的情况。所有的覆盖率数据会保存到`[outputDir]/.cache`，在报告生成之后，这些缓存数据会被清除。除非开启了[调试模式](#debug-for-coverage-and-sourcemap)，或者使用了`raw`报告
@@ -800,6 +857,16 @@ npx mcr node ./test/specs/node.test.js -r v8,console-details --lcov
 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
+```
+
 - 参见例子
     - [Mocha](#mocha)
     - [TypeScript](#typescript)
@@ -814,7 +881,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 +964,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/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

package/lib/index.d.ts

@@ -36,7 +36,7 @@ declare namespace MCR {
     export type Watermarks = [number, number] | {
         /** V8 only */
         bytes?: [number, number];
-        statements: [number, number];
+        statements?: [number, number];
         branches?: [number, number];
         functions?: [number, number];
         lines?: [number, number];
@@ -134,7 +134,7 @@ declare namespace MCR {
             } | ((file: CoverageFile) => boolean);
         }] |
         ['markdown-summary'] | ['markdown-summary', {
-            color: 'unicode' | 'html' | 'tex' | string;
+            color?: 'unicode' | 'html' | 'tex' | string;
             metrics?: Array<"bytes" | "statements" | "branches" | "functions" | "lines">;
             /**
              * defaults to `coverage-summary.md`
@@ -143,7 +143,7 @@ declare namespace MCR {
         }] |
         ['markdown-details'] | ['markdown-details', {
             baseUrl?: string;
-            color: 'unicode' | 'html' | 'tex' | string;
+            color?: 'unicode' | 'html' | 'tex' | string;
             maxCols?: number;
             skipPercent?: number;
             metrics?: Array<"bytes" | "statements" | "branches" | "functions" | "lines">;
@@ -207,7 +207,7 @@ declare namespace MCR {
          */
         none?: boolean;
         /**  function only, function name */
-        name?: boolean;
+        name?: string;
     }
 
     export interface IgnoredRange {
@@ -422,10 +422,10 @@ declare namespace MCR {
         sourceMapResolver?: (url: string, defaultResolver: Function) => Promise<any>;
 
         /** (V8 only) {function} onEntry hook */
-        onEntry?: (entry: V8CoverageEntry) => Promise<void>;
+        onEntry?: (entry: V8CoverageEntry) => void | Promise<void>;
 
         /** {function} onEnd hook */
-        onEnd?: (coverageResults: CoverageResults | undefined) => Promise<void>;
+        onEnd?: (coverageResults: CoverageResults | undefined) => void | Promise<void>;
 
         [key: string]: any;
     }
@@ -433,13 +433,13 @@ declare namespace MCR {
     export interface McrCliOptions extends CoverageReportOptions {
 
         /** (CLI only) {function} onStart hook */
-        onStart?: (coverageReport: CoverageReport) => Promise<void>;
+        onStart?: (coverageReport: CoverageReport) => void | Promise<void>;
 
         /** (CLI only) {function} onReady hook before adding coverage data.
-         * 
+         *
          * Sometimes, the child process has not yet finished writing the coverage data, and it needs to wait here.
         */
-        onReady?: (coverageReport: CoverageReport, nodeV8CoverageDir: string, subprocess: any) => Promise<void>;
+        onReady?: (coverageReport: CoverageReport, nodeV8CoverageDir: string, subprocess: any) => void | Promise<void>;
 
     }