monocart-coverage-reports 2.13.2 → 3.0.0

package/skills/monocart-coverage-reports/references/cli.md

@@ -0,0 +1,108 @@
+# CLI and configuration
+
+These recipes support MCR 3.x only (Node.js >= 22.15.0). Verify the installed major version and runtime before using them.
+
+## Executable and argument boundaries
+
+```sh
+npx mcr node ./app.js -r v8,console-summary
+npx mcr -c mcr.config.mjs -- npm run test:unit
+npx mcr -c mcr.config.mjs -- node "./path with spaces/app.js"
+```
+
+The separator keeps child flags distinct from MCR flags. In 3.x the child executes through Execa without explicitly enabling shell mode. Do **not** pass a whole command as one string (`mcr "node app.js"`), expect MCR to expand environment variables/globs, or embed `&&`, pipes, and redirections inside a child command string. Move composite steps into an existing npm script or a dedicated script. The outer terminal shell still has its own expansion/redirection rules.
+
+Useful MCR options include `-c/--config`, `-r/--reports`, `-o/--outputDir`, `-i/--inputDir`, `-b/--baseDir`, `-a/--all`, `--entryFilter`, `--sourceFilter`, `--outputFilter` (3.x), `--filter`, `--inline`, `--lcov`, `--import`, `--require`, and `--env [path]`. Use a JS config for functions/complex options rather than inventing flags. `--env` without a path loads `.env` on the current runtime; avoid logging secrets.
+
+## Configuration
+
+```js
+// mcr.config.mjs
+export default {
+    name: 'Application Coverage',
+    outputDir: './coverage-reports',
+    reports: ['v8', 'console-summary', 'lcovonly'],
+    entryFilter: { '**/node_modules/**': false, '**/src/**': true },
+    sourceFilter: { '**/node_modules/**': false, '**/src/**': true }
+};
+```
+
+Choose the filtering approach using the README's Approach trade-offs: input filtering for early exclusion and better performance, or 3.x `outputFilter` for simpler final-path selection at the cost of processing unwanted inputs first. This config chooses input filtering for directly executed `src/` modules. For bundles, change `entryFilter` to allow the actual bundle URLs, then use `sourceFilter` for their unpacked sources. `sourceFilter` alone does not exclude unmapped collected entries. Do not stack both strategies by default; see [filtering-and-sourcemaps.md](filtering-and-sourcemaps.md) for both alternatives.
+
+A CommonJS config can remain `mcr.config.cjs` with `module.exports = { ... }`, even though MCR's own API is ESM. `.js` follows the host's `package.json` module type. Do not add `"type": "module"` to an entire host project merely for one config file.
+
+Default discovery walks upward from cwd and checks `mcr.config.js`, `.cjs`, `.mjs`, `.json`, then `.ts`. Prefer explicit `-c` when a monorepo could find an unintended parent config. TypeScript configs need an appropriate loader, for example when the host already has `tsx`:
+
+```sh
+npx mcr --import tsx -c mcr.config.ts -- node ./app.js
+```
+
+API loading is explicit:
+
+```js
+import { CoverageReport } from 'monocart-coverage-reports';
+const report = new CoverageReport();
+await report.loadConfig('./mcr.config.mjs');
+await report.addFromDir('./coverage-data');
+const results = await report.generate();
+if (!results) throw new Error('No coverage generated');
+```
+
+Constructor/CLI options override config. In 3.x, an explicit missing config or a discovered but broken config throws/exits nonzero; no `strict` switch is needed. No default config found is allowed. Await and propagate errors rather than generating a misleading default report.
+
+## Built-in Node test runner (3.x)
+
+For simple code-validation tasks, write a test with `node:test` and `node:assert/strict`, install `monocart-coverage-reports`, then run `npx mcr test <test-file> -r v8,console-summary`. It runs the tests and automatically generates an interactive V8 report plus a terminal summary without requiring another test framework or a custom coverage collector. See the [complete quick start](../SKILL.md#quick-start-test-your-code-and-get-coverage-3x) for a module and its test. The two reports are an explicitly selected recommendation, not MCR's implicit report default.
+
+```sh
+npx mcr test "./test/**/*.test.js" -r v8,console-summary
+npx mcr test "./test/unit/**/*.test.js" -c mcr.config.mjs -- --test-reporter=spec
+```
+
+Or put targets in config:
+
+```js
+export default {
+    test: ['./test/unit/**/*.test.js', './test/integration/**/*.test.js'],
+    reports: ['v8', 'console-summary'],
+    outputDir: './coverage-reports'
+};
+```
+
+- `mcr test` invokes Node's `--test`; it is not a replacement entry for Jest/Mocha/Playwright tests.
+- CLI positional targets **replace** config `test`. Arrays supply separate arguments; a string is one target argument, not a shell command.
+- Quote globs for Node to interpret; options after `--` are forwarded to the Node test runner.
+- With neither CLI targets nor config `test`, it **skips tests and generates no report**. Do not treat such a run as validated coverage.
+- `test` is CLI-only and ignored by ordinary commands/API. Existing runners remain supported through `mcr npm run ...`.
+- Test failure still attempts report generation and retains a nonzero exit status. A report-generation failure must fail CI too. Validate both paths.
+
+## Hooks and shutdown
+
+| Hook | Scope / timing |
+| --- | --- |
+| `onStart(report)` | CLI child execution, before spawn |
+| `onReady(report, nodeV8CoverageDir, subprocess)` | CLI, after child exits, before reading inputs |
+| `onEntry(entry)` | V8 input processing; can mutate entry |
+| `onEnd(results)` | After report generation; suitable for thresholds |
+
+Hooks may be async. Use `onReady` for a concrete flush/readiness condition when necessary, not an arbitrary permanent delay. API integrations manage their own process lifecycle; they do not receive CLI-only hooks automatically. Preserve test/child failures even if cleanup or reporting also fails.
+
+## API use in CommonJS hosts
+
+MCR 3.x uses ESM, but a CommonJS host can use dynamic import without converting its entire application:
+
+```js
+// coverage.cjs
+async function main() {
+    const { MCR } = await import('monocart-coverage-reports');
+    const report = MCR({ outputDir: './coverage-reports', cleanCache: true });
+    await report.addFromDir('./coverage-data');
+    if (!await report.generate()) throw new Error('No coverage generated');
+}
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});
+```
+
+Use ESM-aware TypeScript module settings and verify emitted JavaScript. Secondary `/util` and `/converter` entries provide **named exports**, not defaults. These recipes do not cover other major versions; approved upgrades should follow the package's `migrate-to-3.md`.

package/skills/monocart-coverage-reports/references/collection.md

@@ -0,0 +1,152 @@
+# Coverage collection recipes
+
+Examples use ESM (`.mjs`, or `.js` under `"type": "module"`) and the MCR 3.x runtime contract. Reuse installed browser/test tools; do not install every collector. MCR itself is a Node-side library, not a browser import.
+
+## Choose the input
+
+| Runtime / existing data | Collection path | MCR input |
+| --- | --- | --- |
+| Node program or test command | `mcr <executable> <args>` | CLI collects and generates |
+| Node raw V8 directory | `NODE_V8_COVERAGE` before process start | `addFromDir(dir)` or `dataDir` |
+| Playwright Chromium | `page.coverage` | JS + CSS entry array |
+| Puppeteer | Raw script coverage + source text | Converted JS + CSS entry array |
+| Chromium/Node inspector | `CDPClient` | `stopCoverage()` / `stopJSCoverage()` result |
+| Already Istanbul-instrumented program | `window.__coverage__` / `globalThis.__coverage__` | Istanbul map object |
+
+Do not assume Chromium V8 coverage works in Firefox/WebKit or that it automatically covers every browser context, page, worker, or remote backend. Explicitly collect the runtimes/targets the task requires.
+
+## Playwright Chromium: complete standalone script
+
+Assumes the application's test server is already running at `APP_URL` (or the local default). Prefer the host's existing server lifecycle and readiness checks.
+
+```js
+// collect-browser.mjs
+import { chromium } from 'playwright';
+import { MCR } from 'monocart-coverage-reports';
+
+const report = MCR({
+    outputDir: './coverage-reports/browser',
+    reports: ['v8', 'console-summary'],
+    cleanCache: true
+});
+const browser = await chromium.launch();
+try {
+    const page = await browser.newPage();
+    await Promise.all([
+        page.coverage.startJSCoverage({ resetOnNavigation: false }),
+        page.coverage.startCSSCoverage({ resetOnNavigation: false })
+    ]);
+    await page.goto(process.env.APP_URL || 'http://localhost:3000');
+    // Perform real assertions/interactions here before stopping coverage.
+    const [js, css] = await Promise.all([
+        page.coverage.stopJSCoverage(),
+        page.coverage.stopCSSCoverage()
+    ]);
+    await report.add([...js, ...css]);
+    const results = await report.generate();
+    if (!results) throw new Error('No browser coverage generated');
+} finally {
+    await browser.close();
+}
+```
+
+For test suites, start/stop in the host runner's fixtures/hooks, persist each test's data, and generate **once after all workers finish**. Do not create a `cleanCache: true` report per test against a shared directory. Collect before teardown/navigation destroys the execution target. On failure, retain coverage where possible without replacing the original test failure with a successful exit.
+
+Anonymous scripts require deliberate URL/source handling; Playwright CSS coverage does not support anonymous styles without source URLs. Use CDP when that limitation matters.
+
+## Puppeteer: convert the JS data shape
+
+Within an existing Puppeteer `page` lifecycle:
+
+```js
+await Promise.all([
+    page.coverage.startJSCoverage({
+        resetOnNavigation: false,
+        includeRawScriptCoverage: true
+    }),
+    page.coverage.startCSSCoverage({ resetOnNavigation: false })
+]);
+await page.goto(appUrl); // appUrl is the host application's test URL
+// Exercise and assert the application here.
+const [js, css] = await Promise.all([
+    page.coverage.stopJSCoverage(),
+    page.coverage.stopCSSCoverage()
+]);
+const entries = [
+    ...js.map((entry) => ({
+        ...entry.rawScriptCoverage,
+        source: entry.text
+    })),
+    ...css
+];
+await report.add(entries); // report is an MCR instance; generate after collection
+```
+
+Do not pass Puppeteer's simplified JS coverage directly as raw V8 function coverage. Preserve `rawScriptCoverage.functions` and the exact matching source text. Close the browser in `finally` after coverage collection.
+
+## CDPClient
+
+For Playwright use `await page.context().newCDPSession(page)`; for Puppeteer use `await page.target().createCDPSession()`. Pass the resulting session to MCR:
+
+```js
+import { CDPClient } from 'monocart-coverage-reports';
+
+const client = await CDPClient({ session });
+if (!client) throw new Error('Cannot connect coverage client');
+try {
+    await client.startCoverage(); // both JS and CSS on a browser target
+    // Navigate/exercise the target here.
+    const entries = await client.stopCoverage();
+    await report.add(entries);
+} finally {
+    await client.close();
+}
+```
+
+For a Node debugger target, connect with `{ port: 9229 }` (start the program with `--inspect=9229`) and use `startJSCoverage()` / `stopJSCoverage()`, not CSS methods. Ensure the target remains alive during collection; restrict debugger exposure to trusted/local interfaces.
+
+In 3.x, `timeout` controls discovery/connection (default 10000 ms), and `requestTimeout` controls built-in WebSocket commands (default 30000 ms). `0` disables the respective deadline. External Playwright/Puppeteer sessions manage their own command deadlines. Handle disconnects/rejected commands rather than waiting indefinitely.
+
+## Node raw directory
+
+The easiest path is the CLI because it also registers source capture. For manual collection, set the environment **before** starting the program. Use a fresh directory per independent run. POSIX shell example:
+
+```sh
+NODE_V8_COVERAGE=./coverage-data node --import monocart-coverage-reports/register ./app.js
+node ./generate-coverage.mjs
+```
+
+In Windows PowerShell, set `$env:NODE_V8_COVERAGE='./coverage-data'` before `node`; remove it afterward with `Remove-Item Env:NODE_V8_COVERAGE`. Or use the host's existing cross-platform environment tooling. Do not add a dependency solely for this example.
+
+```js
+// generate-coverage.mjs
+import { MCR } from 'monocart-coverage-reports';
+const report = MCR({
+    outputDir: './coverage-reports/node',
+    reports: ['v8', 'lcovonly', 'console-summary'],
+    cleanCache: true
+});
+await report.addFromDir('./coverage-data');
+const results = await report.generate();
+if (!results) throw new Error('No Node coverage generated');
+```
+
+Wait for the target/children to finish flushing. Long-lived servers can use `node:v8`'s `takeCoverage()` with `NODE_V8_COVERAGE`, or MCR's `client.writeCoverage()` through a debugger connection. Flushing still requires coordinated shutdown; do not kill the process before writing inputs.
+
+A Node coverage JSON file contains a `result` array and may have sourcemap metadata. Prefer `addFromDir()` over manually discarding that metadata. Inspector collection requires fetching/attaching the actual script source. Do not create fake source strings for real application scripts.
+
+## Istanbul input
+
+Instrument the tested build with the host's existing Istanbul plugin/tool first. Then collect before the page closes:
+
+```js
+const data = await page.evaluate(() => globalThis.__coverage__);
+if (!data || !Object.keys(data).length) {
+    throw new Error('Missing Istanbul coverage: verify instrumentation');
+}
+await report.add(data);
+```
+
+For Node, read `globalThis.__coverage__` in the instrumented process. Use `reports: ['html', 'lcovonly', 'console-summary']` for Istanbul input; native V8 byte/CSS reports cannot be reconstructed from an Istanbul map. MCR does not apply its V8 input filters to Istanbul maps; configure instrumentation/runner scope appropriately.
+
+Existing Jest/Vitest coverage should use their compatible MCR integration or raw export path. Do not assume a reporter for one framework can be installed as another framework's reporter, or that an arbitrary JSON report is an MCR raw export.

package/skills/monocart-coverage-reports/references/filtering-and-sourcemaps.md

@@ -0,0 +1,170 @@
+# Filtering, sourcemaps, and untested files
+
+## Choose a filtering strategy
+
+For V8 input, choose according to the README's **Approach** comparison, rather than always selecting `outputFilter`. The following comparison is self-contained for package-only/offline use. Both approaches decide which files appear in the report; choose one for the intended scope, not both automatically.
+
+| Approach | When and what it filters | Advantages | Trade-offs |
+| --- | --- | --- | --- |
+| `entryFilter` + `sourceFilter` (or `filter`) | Entry URLs during discovery, then source paths as sourcemaps are unpacked | Early exclusion avoids unnecessary downstream work; prefer when performance matters, especially for large projects/bundles | Requires entry/source knowledge; excluding a bundle also removes desired sources inside it |
+| `outputFilter` (3.x only) | Final `sourcePath` after conversion, merging, and adding untested files (`all`) | One filter against the final file list; simpler configuration | Unwanted inputs are still processed first, increasing generation time and memory usage |
+
+Use input filtering when performance matters. Choose output filtering when simpler final-file selection is more important and the earlier processing cost is acceptable. If switching strategies, remove old input filters for the same scope: output filtering cannot restore previously excluded inputs.
+
+| Option | Receives / matches | Stage |
+| --- | --- | --- |
+| `entryFilter` | Entry object function (`entry.url`), or URL patterns | Before converting bundles |
+| `sourceFilter` | Source path string, or path patterns | Sources unpacked from sourcemaps; also untested files |
+| `filter` | Entry object or source path string | Shorthand for both input filters; not `outputFilter` |
+| `outputFilter` | Final file object function (`entry.sourcePath`), or final path patterns | After sourcemap conversion, merging, and `all` |
+
+Example input filtering for **directly executed source modules**, including entries without sourcemaps:
+
+```js
+// input-filter.config.mjs
+export default {
+    entryFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    },
+    sourceFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    }
+};
+```
+
+For a **bundled build**, allow the actual application bundle URLs instead (adapt `dist/` and vendor rules to the tested build):
+
+```js
+// bundle-filter.config.mjs
+export default {
+    entryFilter: {
+        '**/node_modules/**': false,
+        '**/vendor.js': false,
+        '**/dist/**': true
+    },
+    sourceFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    }
+};
+```
+
+`sourceFilter` does not filter already collected entries without sourcemaps. For directly executed sources, restrict their URLs with `entryFilter`, or use 3.x `outputFilter` to limit the final file list. A permissive `entryFilter` plus `sourceFilter: '**/src/**'` can still include unmapped test/helper scripts.
+
+An entry may be `dist/main.js` but contain the desired `src/*` sources. Filtering entries to `**/src/**` would discard that bundle before its sources can be recovered.
+
+Alternative final-file selection:
+
+```js
+// output-filter.config.mjs
+export default {
+    outputFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    }
+};
+// Or: outputFilter: (entry) => entry.sourcePath.startsWith('src/')
+```
+
+- Ordered pattern objects use **first match wins**; unmatched files are excluded. Put exclusions before a broad inclusion. Quote CLI patterns to avoid shell expansion.
+- Glob wildcards do not necessarily include dot-prefixed path segments (for example `.temp` or framework build directories). Inspect actual URLs/paths and use an explicit pattern for the hidden segment or a function filter when necessary; do not assume `**/*` includes every generated entry.
+- `sourceFilter` functions receive a string; `outputFilter` functions receive an object. Do not interchange signatures.
+- `outputFilter` matches paths **after `sourcePath` rewriting**, cannot recover entries removed by earlier filters, and does not avoid earlier conversion cost.
+- `outputFilter` affects V8 reports and Istanbul reports converted from V8, but not raw exports or Istanbul input maps.
+- When migrating a scope to `outputFilter`, remove old input filters for that same scope unless their intersection is intentional.
+
+## Build the tested code with usable maps
+
+Generate sourcemaps for the exact build that tests execute, preferably with original source content available. Common coverage-build settings:
+
+| Build tool | Settings |
+| --- | --- |
+| Vite | `build: { sourcemap: true, minify: false }` |
+| webpack | `devtool: 'source-map'`, `mode: 'development'` |
+| Rollup | `output.sourcemap: true`, `treeshake: false` |
+| esbuild | `sourcemap: true`, `treeShaking: false`, `minify: false` |
+
+Change only the intended test/coverage build, not production settings without approval. Minification/transformation can make branch mapping approximate; MCR cannot promise perfect mapping of arbitrary transformed code. Ensure external maps are reachable or attach matching `entry.sourceMap` data; do not substitute maps from a different build.
+
+## Normalize paths for merging
+
+Use a shared `baseDir` when collection/generation working directories differ. Use `sourcePath` to remove known build-specific virtual prefixes, preserving unique business paths:
+
+```js
+const options = {
+    sourcePath: (filePath) => {
+        const prefixes = ['unit-dist/', 'e2e-dist/'];
+        const prefix = prefixes.find((value) => filePath.startsWith(value));
+        return prefix ? filePath.slice(prefix.length) : filePath;
+    }
+};
+```
+
+Only rewrite prefixes actually observed in reports. Do not collapse everything to basename: unrelated `index.ts` files would collide. Normalize the same logical source consistently across server/client/shards, and verify that supposedly identical paths refer to the same source version.
+
+## Include untested files
+
+By default, files never loaded are absent, not automatically 0%. Choose the real application directories:
+
+```js
+const options = {
+    all: {
+        dir: ['./src'],
+        filter: {
+            '**/*.test.js': false,
+            '**/*.spec.js': false,
+            '**/*.js': true,
+            '**/*.css': 'css'
+        }
+    },
+    sourceFilter: '**/src/**'
+};
+```
+
+`all.filter` runs before `sourceFilter`. With 3.x final filtering, `outputFilter` also applies after untested files are added. Current checkout behavior can generate an all-untested V8 report with no collected entries; treat this separately from unexpected missing collection data.
+
+For TS/JSX/Vue sources that the JS AST parser cannot directly parse, use an appropriate transformer already present in the host. Example for **TypeScript without JSX**, if `@swc/core` is installed:
+
+```js
+// untested-typescript.config.mjs
+import { fileURLToPath } from 'node:url';
+import { transform } from '@swc/core';
+
+export default {
+    all: {
+        dir: './src',
+        filter: '**/*.ts',
+        transformer: async (entry) => {
+            const { code, map } = await transform(entry.source, {
+                filename: fileURLToPath(entry.url),
+                sourceMaps: true,
+                isModule: true,
+                jsc: { parser: { syntax: 'typescript' } }
+            });
+            entry.source = code;
+            entry.sourceMap = JSON.parse(map);
+        }
+    }
+};
+```
+
+SWC returns its map as a JSON string; parse it before assigning `entry.sourceMap`. Preserve the full filename so different directories' `index.ts` files retain distinct source paths. Use a consistent `baseDir` when generating or merging.
+
+Use the matching JSX/TSX or Vue compiler for those languages; this is not a universal `.vue` transformer. `all.transformer` handles untested sources; `onEntry` is the separate per-collected-V8-entry hook. Preserve sources/maps/offsets consistently when transforming collected data.
+
+## Intentional ignores
+
+MCR supports `/* v8 ignore next */`, `/* v8 ignore next 3 */`, and `/* v8 ignore start */` / `/* v8 ignore stop */`. `v8Ignore` defaults to true. Verify that the comments survive the tested build. Do not add ignore comments or exclude difficult files merely to raise coverage; explain and agree on legitimate exceptions.
+
+## Debugging checklist
+
+1. Verify collection started before module import/navigation, and that entries include expected URLs and real source text.
+2. Temporarily inspect entry URLs and mapped source paths before tightening filters. A wrong stage/pattern is a common cause of empty reports.
+3. Rebuild without minification; verify maps and source content match the executing bundle.
+4. Use `{ logging: 'debug', sourceMap: true }` to retain cache/source/map files for investigation. Debug mode also retains generated dist entries in V8 results, so its file list can differ from normal mode.
+5. Compare generated versus original ranges and inspect a representative covered/uncovered branch. Never fix results by editing coverage counts.
+6. For large inputs, filter early and reduce unnecessary maps/entries before raising memory limits. The `gc` option is a heap threshold in MB; `NODE_OPTIONS=--max-old-space-size=8192` is a separate Node heap setting. Measure rather than promising either will solve OOM.
+
+Debug/raw artifacts and inline HTML can contain source code, URLs, and internal paths. Apply the host's artifact-retention and publication rules; do not upload private sources to public services without permission.

package/skills/monocart-coverage-reports/references/reports-and-ci.md

@@ -0,0 +1,219 @@
+# Reports, merging, and CI
+
+## Select outputs
+
+| Need | Report | Input support / artifact |
+| --- | --- | --- |
+| Native interactive V8/CSS report | `v8` | V8 only; `index.html` + assets |
+| Native machine-readable V8 results | `v8-json` | V8 only; `coverage-report.json` |
+| Istanbul UI | `html` | Istanbul or converted V8 |
+| Interoperable coverage | `lcovonly` | Istanbul or converted V8; `lcov.info` |
+| XML coverage | `cobertura`, `clover` | Istanbul or converted V8 |
+| Istanbul maps / summary | `json`, `json-summary` | Not native V8 JSON and not MCR raw |
+| Console | `console-summary`, `console-details` | V8 or Istanbul |
+| CI summary | `markdown-summary`, `markdown-details` | `coverage-summary.md`, `coverage-details.md` |
+| Upload data | `codecov`, `codacy` | `codecov.json`, `codacy.json` |
+| Later merging | `raw` | Original inputs and sources, not rendered output |
+
+Multiple report syntax is `reports: ['v8', ['html', { subdir: 'istanbul' }], 'lcovonly']`. Keep multiple HTML formats in separate paths. Native V8 report options use `outputFile`; Istanbul JSON/XML options commonly use `file` — check the declaration for the selected reporter rather than assuming one universal option.
+
+For a portable single native HTML file, use a report descriptor **inside** the `reports` array:
+
+```js
+// inline.config.mjs
+export default {
+    outputDir: './coverage-reports',
+    reports: [['v8', { inline: true }]]
+};
+```
+
+Do not use `reports: ['v8', { inline: true }]`: the separate object does not configure the V8 reporter. Otherwise upload the HTML **and its assets**. Do not claim Istanbul-only input can recover V8 bytes or CSS metrics. Custom reporters receive format-specific data; inspect the reporter interface and installed implementation rather than treating `CoverageResults` as a universal custom reporter payload.
+
+## Enforce thresholds explicitly
+
+`watermarks: [50, 80]` changes low/medium/high colors, not exit status. A strict `onEnd` implementation for a 3.x config:
+
+```js
+// mcr.config.mjs
+export default {
+    outputDir: './coverage-reports',
+    reports: ['v8', 'v8-json', 'lcovonly', 'markdown-summary'],
+    onEnd(results) {
+        if (!results) throw new Error('No coverage results');
+        const thresholds = { lines: 80, branches: 70 };
+        const errors = [];
+        for (const [metric, minimum] of Object.entries(thresholds)) {
+            const summary = results.summary?.[metric];
+            const pct = summary?.pct;
+            if (!summary || summary.total === 0 ||
+                typeof pct !== 'number' || !Number.isFinite(pct) || pct < minimum) {
+                errors.push(`${metric}: ${pct ?? 'missing'}%, required ${minimum}% (nonempty)`);
+            }
+        }
+        if (errors.length) throw new Error(errors.join('\n'));
+    }
+};
+```
+
+This deliberately fails absent/zero-total metrics; adapt that policy explicitly if a project legitimately has no branches. Do not coerce `''` into 0 or silently skip missing metrics. For API workflows, also check `generate()`'s return because no usable input can return early without invoking `onEnd`. For ordinary CLI workflows where missing collection must fail, verify a **fresh, nonempty** result as shown below; built-in `mcr test` already treats a missing generated report as an error on 3.x.
+
+Use `process.exitCode = 1` or throw rather than calling `process.exit()` before asynchronous writes/cleanup finish. Preserve the test process's original failing status. Test the threshold-failure path, not just passing coverage.
+
+## Reject stale reports and missing collection in CI
+
+An ordinary CLI run can return success without calling `onEnd` when no usable input was collected. In that case `generate()` returns before its normal output cleanup: **`clean: true` and `cleanCache: true` do not guarantee old reports are removed**. Checking only whether an existing report file exists can therefore pass using a previous run's result.
+
+Prefer a new, isolated output directory per CI run. If reusing a fixed directory, remove it **before** collecting, then require a newly generated machine-readable report with nonempty intended metrics. For the threshold config above, save these two scripts in the host root:
+
+```js
+// clean-coverage.mjs
+import fs from 'node:fs';
+
+// This must be a dedicated report directory, never a source or shared worker directory.
+fs.rmSync('./coverage-reports', { recursive: true, force: true });
+```
+
+```js
+// verify-coverage.mjs
+import fs from 'node:fs';
+
+const results = JSON.parse(fs.readFileSync('./coverage-reports/coverage-report.json', 'utf8'));
+const lines = results.summary?.lines;
+if (!Array.isArray(results.files) || results.files.length === 0 ||
+    !lines || !(lines.total > 0) || typeof lines.pct !== 'number' || !Number.isFinite(lines.pct)) {
+    throw new Error('Missing or empty coverage from this run');
+}
+```
+
+Run all three steps with failure propagation. For example, in a POSIX shell or npm script (replace `./app.js` with the real target):
+
+```sh
+node ./clean-coverage.mjs && npx mcr -c mcr.config.mjs -- node ./app.js && node ./verify-coverage.mjs
+```
+
+Here `&&` belongs to the **outer shell**, not a command string passed to MCR. In other CI environments, use equivalent sequential steps that stop on failure. The cleanup, config, and verifier must use the same dedicated output path. Never clear shared output while workers are collecting; clean once in the coordinator before starting them. The verifier rejects missing/invalid/empty data; `onEnd` separately enforces the configured thresholds, and the original test/CLI failure must still fail CI.
+
+## Multi-process collection on one filesystem
+
+Use shared options with a dedicated `outputDir` and **no `cleanCache: true` on workers**:
+
+```js
+// coverage-options.mjs
+export default {
+    outputDir: './coverage-reports/shared',
+    reports: ['v8', 'console-summary'],
+    cleanCache: false
+};
+```
+
+1. Coordinator before workers start: `MCR(options).cleanCache()` once.
+2. Each worker: `await MCR(options).add(itsCoverageData)`; do not generate a final report.
+3. Coordinator **after every worker completes its writes**: `await MCR(options).generate()`; require a nonempty result.
+
+`add()` persists inputs to the output's `.cache`; generation merges them. `clean` governs old output artifacts, not the worker input collection lifecycle. Default non-debug generation removes cache afterward. Do not let an early worker generate or clear shared cache while other workers are still adding data.
+
+## Merge separate jobs/shards with raw exports
+
+Each independent job has its own output and exports raw data:
+
+```js
+const options = {
+    outputDir: './coverage-reports/shard-1', // unique per job
+    reports: [
+        ['raw', { outputDir: 'raw' }],
+        'v8',
+        'console-summary'
+    ],
+    cleanCache: true
+};
+```
+
+The relative raw directory becomes `coverage-reports/shard-1/raw`. Upload/download the **entire** raw directory, including source files. After every required job finishes, merge in a separate output directory:
+
+```js
+// merge-coverage.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import { MCR } from 'monocart-coverage-reports';
+
+const inputDir = [
+    './downloaded/shard-1/raw',
+    './downloaded/shard-2/raw'
+];
+// Check all expected shards BEFORE generation can clean old output.
+for (const dir of inputDir) {
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        throw new Error(`Missing coverage shard: ${dir}`);
+    }
+    const coverageFiles = fs.readdirSync(dir).filter((name) =>
+        name.startsWith('coverage-') && name.endsWith('.json'));
+    let hasData = false;
+    for (const name of coverageFiles) {
+        const coverage = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+        if (coverage.type === 'v8' && Array.isArray(coverage.data)) {
+            hasData ||= coverage.data.length > 0;
+            for (const entry of coverage.data) {
+                const sourceFile = path.join(dir, `source-${entry.id}.json`);
+                const source = JSON.parse(fs.readFileSync(sourceFile, 'utf8'));
+                if (source.id !== entry.id || typeof source.source !== 'string') {
+                    throw new Error(`Invalid raw source: ${sourceFile}`);
+                }
+            }
+        } else if (coverage.type === 'istanbul' && coverage.data &&
+            typeof coverage.data === 'object' && !Array.isArray(coverage.data)) {
+            hasData ||= Object.keys(coverage.data).length > 0;
+        } else {
+            throw new Error(`Invalid raw coverage: ${dir}/${name}`);
+        }
+    }
+    if (!hasData) throw new Error(`Empty coverage shard: ${dir}`);
+}
+
+const report = MCR({
+    inputDir,
+    outputDir: './coverage-reports/merged',
+    reports: ['v8', 'lcovonly', 'console-summary'],
+    cleanCache: true
+});
+const results = await report.generate();
+if (!results || !results.files.length) throw new Error('No merged coverage generated');
+```
+
+CLI merge syntax (does **not** perform the preflight above; prefer the validated script in CI):
+
+```sh
+npx mcr merge --inputDir "./downloaded/shard-1/raw,./downloaded/shard-2/raw" --outputDir ./coverage-reports/merged -r v8,lcovonly,console-summary
+```
+
+- Derive the expected shard list from the CI matrix, not only the directories that happened to download. The script rejects missing/empty shards, malformed coverage, and missing/invalid V8 source files; a successful merge alone does not prove all shards contributed.
+- For independently built artifacts, record and compare source revision/build identifiers and shard IDs before merging; directory checks alone cannot prove the builds match.
+- Keep output separate from inputs; default cleaning must not remove downloaded artifacts. Apply the same path normalization/source revision across jobs.
+- HTML, `v8-json`, LCOV, and `json-summary` are not substitutes for MCR raw input. Do not average percentages.
+- Do not assume arbitrary V8 and Istanbul datasets can be mixed in one run. Prefer consistent raw formats or verify the installed release's mixed-format handling with a targeted fixture.
+- Keep raw artifacts until merge validation passes, then apply the host's retention/security policy. Raw exports are not affected by final `outputFilter`.
+
+## CI checklist
+
+- Pin a supported Node runtime and install from the existing lockfile.
+- Build the exact coverage target with maps, run tests, then generate/merge only when inputs are flushed.
+- Upload coverage artifacts on failed tests too, using the CI platform's failure-safe artifact step. Do not mask exit codes with unconditional success or `continue-on-error`.
+- Check source scope and nonempty metrics before gating. Supply `all` when coverage must account for files never imported.
+- Publish `coverage-summary.md` to the job summary using the host CI's supported file append mechanism; upload LCOV/Codecov with explicit file paths.
+- Never include tokens in generated HTML/config examples. Do not publicly publish source-containing reports without approval.
+
+## Regression snapshots
+
+The public `getSnapshot(results)` and `diffSnapshot(old, next, options)` helpers compare coverage results, not raw data merges:
+
+```js
+import { getSnapshot, diffSnapshot } from 'monocart-coverage-reports';
+const next = getSnapshot(results);
+const diff = diffSnapshot(previousSnapshot, next, {
+    skipEqual: true,
+    showSummary: true,
+    metrics: ['lines', 'branches']
+});
+if (diff.change) console.log(diff.message);
+```
+
+Here `results` is a validated generation result and `previousSnapshot` is a loaded baseline. Inspect differences; do not overwrite baselines simply to make tests pass. Identical percentages alone do not guarantee identical mapped source ranges.