monocart-coverage-reports 2.13.2 → 3.1.0

package/skills/monocart-coverage-reports/references/best-practices.md

@@ -0,0 +1,218 @@
+# MCR best practices: test code and get useful coverage
+
+Use this module to choose a test setup and implement coverage collection. These recipes target **MCR 3.x and Node.js >= 22.15.0**. Reuse the host package manager, module format, test server, and installed tools. Do not upgrade dependencies or migrate an existing runner without approval.
+
+## 1. Choose the simplest collection path
+
+| Target | Default recommendation | Why |
+| --- | --- | --- |
+| New Node.js tests | **Node.js native test runner + `mcr test`** | Built-in assertions/tests, automatic native V8 JS coverage, no instrumentation or custom collector. |
+| Browser tests | **Playwright Test + MCR** | Runner-managed lifecycle and assertions; direct control over JS/CSS coverage reports. |
+| Browser tests with integrated reporting | **Playwright Test + monocart-reporter** | Already integrates MCR; combines test results and coverage reporting. |
+| Existing Jest/Vitest/Mocha/etc. | Keep the existing runner and its compatible collection integration | Adding coverage should not require rewriting working tests. |
+
+MCR collects/processes coverage and generates reports; the test runner executes assertions. Prefer native V8 collection where supported. Choose **one owner** for collection and final generation, rather than collecting the same execution through multiple integrations.
+
+## 2. Node.js: prefer `mcr test <targets>`
+
+Write tests with `node:test` and `node:assert/strict`. Cover meaningful outputs, errors, boundaries, and asynchronous behavior; use the real module rather than duplicating its implementation in a test. See the [complete module and test example](../SKILL.md#quick-start-test-your-code-and-get-coverage-3x).
+
+Install only if needed, using the host package manager:
+
+```sh
+npm install --save-dev monocart-coverage-reports@^3
+npx mcr test "./test/**/*.test.mjs" -r v8,console-summary
+```
+
+Replace the glob with actual test targets. For a repeatable project command, put `mcr test -c mcr.config.mjs` in an npm script such as `test:coverage`, with this config:
+
+```js
+// mcr.config.mjs
+export default {
+    test: ['./test/**/*.test.mjs'],
+    outputDir: './coverage-reports/node',
+    reports: ['v8', 'console-summary'],
+    outputFilter: {
+        '**/node_modules/**': false,
+        '**/src/**': true
+    }
+};
+```
+
+This example selects final `src/` paths. Adapt it to the host's real source layout and verify the resulting file list; do not copy a filter that excludes the code under test. See [filtering and sourcemaps](filtering-and-sourcemaps.md) for early input filtering, transpiled sources, and `all` for files never loaded by tests.
+
+- `mcr test` invokes Node's native `--test`, automatically collects V8 JS coverage, and generates the selected reports. No manual `NODE_V8_COVERAGE`, coverage instrumentation, or API collector is needed.
+- Quote target globs. Forward Node runner flags after `--`, for example `npx mcr test "./test/**/*.test.mjs" -- --test-reporter=spec`.
+- Supply actual targets or config `test`; an empty target list skips testing and reporting.
+- Open `coverage-reports/index.html` for the first command, or `coverage-reports/node/index.html` for the config above. Verify expected sources and use uncovered branches to choose the next tests.
+- Failed tests still attempt report generation and remain failures. Do not suppress the exit status because an HTML file exists.
+- Existing runners may use `mcr -c mcr.config.mjs -- npm run test:unit` for Node V8 collection where compatible; avoid duplicate coverage providers. TypeScript needs the host's supported loader/build and matching sourcemaps, not an assumption that every TS syntax runs directly.
+
+See [CLI details](cli.md) for target overrides, configuration discovery, and argument boundaries.
+
+## 3. Browser: Playwright Test + MCR
+
+Run tests with **`playwright test`**, not `mcr test`. Wrapping Playwright's Node runner with the MCR CLI does **not** collect JavaScript executing inside browser pages.
+
+Use an automatic test-scoped fixture: start coverage before navigation, run real assertions, then stop and persist coverage before Playwright closes the page. This includes normal assertion failures. Generate once in the coordinator after every worker has finished writing.
+
+### Complete project example
+
+[playwright-coverage](https://github.com/cenfun/playwright-coverage) is a minimal **Playwright Test + MCR 3.x** example using plain JavaScript ESM. It tests browser-side application code, not the Playwright test scripts or a Node.js backend. Its [quick start](https://github.com/cenfun/playwright-coverage#quick-start-for-your-own-project) explains how to adapt these five files to your application:
+
+| File | Purpose |
+| --- | --- |
+| [fixtures.js](https://github.com/cenfun/playwright-coverage/blob/main/fixtures.js) | Automatically start/stop page JS/CSS coverage and persist it with `add()`, including ordinary assertion failures. |
+| [mcr.config.js](https://github.com/cenfun/playwright-coverage/blob/main/mcr.config.js) | Share output/report options and keep `cleanCache: false` for workers. |
+| [global.setup.js](https://github.com/cenfun/playwright-coverage/blob/main/global.setup.js) | Clear the dedicated output directory before workers start. |
+| [global-teardown.js](https://github.com/cenfun/playwright-coverage/blob/main/global-teardown.js) | Generate once after all workers finish; reject missing/empty results. |
+| [playwright.config.js](https://github.com/cenfun/playwright-coverage/blob/main/playwright.config.js) | Select Chromium, register hooks, and configure the test runner. |
+
+For an existing application, merge these settings, configure its actual `baseURL` and server lifecycle, and import the extended `test` from the fixture. Do not change the application's module system just for coverage; use `.mjs` as below when appropriate. Browser dependencies and binaries must already be installed or their installation approved.
+
+The example's [Todo tests](https://github.com/cenfun/playwright-coverage/blob/main/tests/demo-todo-app.spec.js) serve real local HTML/JS/CSS through Playwright routes so the tests need no server or external website. They assert item creation, input clearing, whitespace handling, and text rendering. The routes and Todo assets are only an offline demo, not extra infrastructure to copy into your application.
+
+Run `npm test` in the example project. Inspect `coverage-reports/index.html` for code coverage, `coverage-reports/lcov.info` for CI, and `playwright-report/index.html` for test results. These are different artifacts: a passing test report alone does not validate coverage. For JS-only coverage, omit CSS collection; retain sourcemaps and select your real application source scope for bundled code.
+
+### Minimal parallel-safe integration
+
+This example assumes `@playwright/test` and MCR 3.x are installed, an approved Chromium binary is available, and the application server is already running. Reuse the host's server lifecycle/readiness checks (such as Playwright `webServer`); do not silently download browsers. Save these files at the host project root except the spec under `e2e/`. Merge the settings into an existing Playwright config rather than replacing its projects or hooks.
+
+```js
+// coverage-options.mjs
+export default {
+    outputDir: './coverage-reports/browser',
+    reports: ['v8', 'console-summary'],
+    // Workers share this cache. Only the coordinator may clean it.
+    cleanCache: false
+};
+```
+
+```js
+// coverage-setup.mjs
+import fs from 'node:fs';
+import options from './coverage-options.mjs';
+
+export default function globalSetup() {
+    // Dedicated to this run: never share with another active Playwright invocation.
+    // Remove old reports as well as cache, so missing collection cannot leave stale artifacts.
+    fs.rmSync(options.outputDir, { recursive: true, force: true });
+}
+```
+
+```js
+// coverage-fixtures.mjs
+import { test as base, expect } from '@playwright/test';
+import { MCR } from 'monocart-coverage-reports';
+import options from './coverage-options.mjs';
+
+export const test = base.extend({
+    coverage: [async ({ page, browserName }, use) => {
+        if (browserName !== 'chromium') {
+            // Other browser projects still run tests, but do not provide native coverage.
+            await use();
+            return;
+        }
+        await Promise.all([
+            page.coverage.startJSCoverage({ resetOnNavigation: false }),
+            page.coverage.startCSSCoverage({ resetOnNavigation: false })
+        ]);
+        try {
+            await use();
+        } finally {
+            const [js, css] = await Promise.all([
+                page.coverage.stopJSCoverage(),
+                page.coverage.stopCSSCoverage()
+            ]);
+            await MCR(options).add([...js, ...css]);
+        }
+    }, { auto: true }]
+});
+export { expect };
+```
+
+```js
+// coverage-teardown.mjs
+import { MCR } from 'monocart-coverage-reports';
+import options from './coverage-options.mjs';
+
+export default async function globalTeardown() {
+    const results = await MCR(options).generate();
+    if (!results || !results.files.length) {
+        throw new Error('No browser coverage generated: check fixtures and source scope');
+    }
+}
+```
+
+```js
+// playwright.config.mjs
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './e2e',
+    globalSetup: './coverage-setup.mjs',
+    globalTeardown: './coverage-teardown.mjs',
+    use: {
+        browserName: 'chromium',
+        baseURL: process.env.APP_URL || 'http://localhost:3000'
+    }
+});
+```
+
+```js
+// e2e/counter.spec.mjs
+import { test, expect } from '../coverage-fixtures.mjs';
+
+// Assumes a counter starting at 0; replace with your application's actual behavior.
+test('increments the counter when clicked', async ({ page }) => {
+    await page.goto('/');
+    const counter = page.getByTestId('counter');
+    await expect(counter).toHaveText('0');
+    await page.getByRole('button', { name: 'Increment', exact: true }).click();
+    await expect(counter).toHaveText('1');
+});
+```
+
+```sh
+npx playwright test
+```
+
+All covered specs must import the extended `test` from the fixture, not directly from `@playwright/test`. Inspect `coverage-reports/browser/index.html`. The example deliberately starts without a source filter: inspect actual bundle URLs and mapped paths, then select application sources using [filtering and sourcemaps](filtering-and-sourcemaps.md). Leaving vendor/runtime code in the report is not an accurate application coverage scope.
+
+### Lifecycle and scope limitations
+
+- Native `page.coverage` JS/CSS collection is **Chromium-only**. Firefox/WebKit require a separate instrumentation-based approach, such as collecting an Istanbul map; changing the reporter does not remove this limitation.
+- `resetOnNavigation: false` preserves coverage across navigations in the same page. The fixture covers only its `page`; extra pages/popups, workers, and the Node.js backend require explicit collection strategies. Tests must not close the covered page before fixture teardown.
+- Assertion failures normally run fixture teardown; crashes, forced termination, or timeouts may prevent collection. Retain the original failure and report collection failures rather than claiming coverage is complete.
+- Only the coordinator removes the dedicated output directory before workers start. Clearing only `.cache` would leave old HTML reports available for upload if collection fails. Never point `outputDir` at source code, merge inputs, or another run's output.
+- Do not call `generate()` or `cleanCache()` in each test/worker. `add()` persists data; the coordinator merges it during final generation. `cleanCache: true` in a shared worker would erase other tests' inputs.
+- Give independent CI runs/shards separate output directories. Export `raw` per shard and merge only after validating every expected shard; do not let independent global teardowns race on shared cache. See [reports and CI](reports-and-ci.md).
+
+## 4. Browser alternative: Playwright Test + monocart-reporter
+
+Choose this when you also want Monocart's Playwright test report, rather than maintaining a separate MCR reporting lifecycle. **monocart-reporter already integrates MCR**; do not add another MCR generator for the same data.
+
+1. Check the installed reporter's version, runtime requirements, bundled MCR version, and [official code coverage integration](https://github.com/cenfun/monocart-reporter#code-coverage-report). Do not assume its bundled MCR major matches a separate top-level installation or pass unsupported MCR 3.x options.
+2. Add `monocart-reporter` to the host's Playwright `reporter` configuration and configure its `coverage` options according to that release's documentation.
+3. Use an automatic Playwright fixture to start/stop page coverage around each test, as above, but submit the data through the reporter's documented coverage API with the current `testInfo`, instead of `MCR(options).add()`.
+4. Let the reporter own aggregation, cleanup, and final report generation. Do **not** also install the direct-MCR global setup/teardown above. Follow the reporter's own merge workflow for parallel jobs/shards.
+5. Run `npx playwright test` and verify both the test report and its coverage report contain current, intended data. Enabling a reporter alone does not start browser coverage collection.
+
+Use the version-matched official fixture rather than guessing reporter API signatures. Direct MCR is preferable when you need independent coverage lifecycle/options; the reporter is preferable when you want unified test and coverage reporting. Both use the same browser coverage limitations.
+
+## 5. Make coverage trustworthy
+
+- **Test behavior, not a percentage.** Add assertions for normal, boundary, error, and async paths. Use uncovered branches to find missing cases; do not weaken assertions or add unjustified ignores to satisfy a threshold.
+- **Match the exact build.** Keep tested source, bundle, and sourcemaps together. For TS/bundlers, verify mapped source and line positions; do not rebuild different artifacts before generating/merging coverage.
+- **Define the denominator.** Exclude only justified out-of-scope dependencies/generated assets, and use `all` when untouched application files must count as uncovered. A high percentage of loaded files alone does not prove the whole application is tested.
+- **Choose useful artifacts.** Start with `v8` and `console-summary`; add `lcovonly` for compatible CI services, `v8-json` for machine validation, or `raw` for later merging. Do not merge HTML, summaries, or percentages.
+- **Fail honestly.** Test, collection, report, and threshold failures must remain nonzero. `watermarks` only colors results; enforce thresholds explicitly. API callers must reject missing/empty results; CI must reject stale artifacts, not just check whether an old HTML file exists. See [strict CI and threshold recipes](reports-and-ci.md).
+- **Keep artifacts safe.** Use dedicated per-run output directories and retain useful reports on failures without masking status. Reports and raw/debug data may contain source code, private paths, and URLs; publish only with approval.
+
+### Delivery checklist
+
+- [ ] The chosen runner executes real assertions; collection starts before application execution/navigation.
+- [ ] The report contains the intended current sources, accurate mappings, and any required untested files.
+- [ ] Parallel tests do not clear one another's data; every required shard contributes to the merge.
+- [ ] Reports are fresh and nonempty, and test/report/threshold failure paths fail CI.
+- [ ] The user receives the run command, report location, source scope, and any collection limitations.

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,154 @@
+# 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.
+
+For test suites, prefer the [Playwright Test fixture and lifecycle in MCR best practices](best-practices.md#3-browser-playwright-test--mcr), or its `monocart-reporter` alternative. The standalone script below is for custom collection outside a runner.
+
+## 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.