monocart-coverage-reports 2.13.2 → 3.1.0

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.

package/skills/monocart-coverage-reports/references/repository-map.md

@@ -0,0 +1,59 @@
+# Repository navigation and maintenance
+
+This is a map of project source files, **not** a JavaScript sourcemap specification. For coverage sourcemaps read [filtering-and-sourcemaps.md](filtering-and-sourcemaps.md).
+
+## Installed-package authority
+
+From the host application's root:
+
+```sh
+node -p "require.resolve('monocart-coverage-reports/package.json')"
+node -p "require.resolve('monocart-coverage-reports')"
+```
+
+Resolve the manifest's `types` relative to its package directory (current path: `lib/index.d.ts`). Read the installed declarations and `lib/default/options.js` before inventing an API. `README.md`, `README.zh-Hans.md`, and `migrate-to-3.md` describe integration/version behavior. File inspection inside `lib/` does not make those files public package exports. Do not import arbitrary internals into a host application.
+
+Current exports: main API, `/register` source-capture preload, `/converter` and `/util` named exports, `/package.json`, and `/skills/*` file resolution. Use the high-level API unless a task explicitly requires lower-level conversion.
+
+## Checkout navigation
+
+Paths below are relative to the repository root and are generally **not shipped in npm** except `lib/`. When working in a source checkout, read its root `AGENTS.md` first for shared development rules and command side effects. That file is checkout-only; do not require it when using the installed skill.
+
+| Task | Read first | Related validation / examples |
+| --- | --- | --- |
+| Public factory, config, cache lifecycle | `lib/index.js`, `lib/index.d.ts`, `lib/default/options.js` | `test/unit/config.test.js`, `test/unit/esm.test.js` |
+| CLI execution, test targets, signals | `lib/cli.js` | `test/unit/cli-test.test.js`, `test/unit/cli-signal.test.js`, `test/specs/node.test.js` |
+| Input reading/merge/report dispatch | `lib/generate.js` | `test/test-merge.js`, `test/test-merge-v8.js`, `test/test-merge-istanbul.js` |
+| Source capture/import hooks | `lib/register/register.js`, `lib/register/hooks.js` | `test/unit/register.test.js`, `test/unit/source-map-comments.test.js` |
+| CDP/WebSocket collection | `lib/client/cdp-client.js`, `lib/client/coverage-client.js`, `lib/client/ws-session.js` | `test/test-client.js`, `test/unit/ws-session.test.js` |
+| Node capture workflows | `test/test-node-env.js`, `test/test-node-api.js`, `test/test-node-ins.js` | `test/test-node-cdp.js`, `test/test-node-vm.js` |
+| Browser data shapes | `test/test-v8.js`, `test/test-puppeteer.js`, `test/test-css.js` | `test/test-istanbul.js` |
+| Conversion and sourcemaps | `lib/converter/converter.js`, `lib/converter/collect-source-maps.js`, `lib/converter/find-original-range.js` | `test/test-esbuild.js`, `test/test-rollup.js`, `test/test-swc.js` |
+| AST metrics/ignore/untested sources | `lib/converter/ast.js`, `lib/converter/ast-visitor.js`, `lib/converter/ignore.js`, `lib/converter/untested.js` | `test/test-v8.js`, `test/test-sections.js` |
+| Filters and normalized paths | `lib/utils/util.js`, `lib/utils/source-path.js`, `lib/generate.js` | `test/unit/output-filter.test.js`, `test/unit/source-path.test.js` |
+| Native V8/Istanbul generation | `lib/v8/v8.js`, `lib/istanbul/istanbul.js`, `lib/reports/` | `test/test-v8-and-istanbul.js`, custom reporter examples under `test/` |
+| Snapshots | `lib/utils/snapshot.js` | `test/check-snapshot.js`, `test/snapshot/` |
+| HTML assets and report UI | `lib/assets.js`, `lib/default/template.html`, `src/app/`, `src/vendor/`, `vite.config.mjs` | `npm run dev`, `npm run build`, `npm run test-runtime` |
+| Runtime compatibility / upgrade | `migrate-to-3.md`, `scripts/test-runtime.js` | `test/unit/node-version.test.js` |
+
+## Development validation
+
+Read current `package.json` scripts before running them. Typical commands from a checkout with dependencies installed:
+
+```sh
+npm run test-unit
+npm run test-types
+npm run test-runtime
+```
+
+Unit tests run directly with `node:test`, independently of the MCR CLI and coverage pipeline. For a focused test: `node --test test/unit/config.test.js`. Run `npm run test-unit-coverage` separately to collect coverage through `mcr test`; reports are written to `.temp/coverage-unit/`. For focused coverage: `node ./lib/cli.js test -c test/mcr.config.unit.js test/unit/config.test.js`. Browser/integration scripts may require downloaded browsers, built fixtures, local servers, and more time; inspect the relevant script before running it. `npm run build` invokes `postbuild` and builds test fixtures. `npm test` also runs integration/report generation and documentation generation; it is not a lightweight unit-only check.
+
+A fresh checkout needs `npm run build` to generate `lib/packages/` before tests that import these bundles. Rebuild after changing UI, template, or vendor-entry source.
+
+Avoid unrelated generated changes. `npm run lint` currently includes `--fix`; inspect its scope before invoking it. Use `npx --no-install eslint src/ test/unit/` for the usual scope without fixes, and explicit paths for other changed source. Do not hand-edit generated `lib/packages/*`, `dist/`, `docs/`, or `test/mock/*/dist/`; use the build/generation workflow. `lib/assets.js` is handwritten runtime source, not generated output. Snapshot baseline changes must be intentional and reviewed, never a way to hide a defect.
+
+Do not use `npm run eol` for validation: it removes the index and runs a hard reset. `npm run test:snap` overwrites baselines. `npm run publish` prepares a release through `npm version`, including its build hook and commit/tag creation; obtain explicit approval before release preparation or external writes.
+
+When changing public behavior, align implementation, `lib/index.d.ts`, default options, English/Chinese docs, migration notes where applicable, and focused tests. This skill supports MCR 3.x only. Validate the installed package separately when release compatibility matters; do not infer support for other major versions from these recipes.
+
+For changes to this skill, verify relative Markdown links, public resolution of `SKILL.md`, npm pack inclusion of **all** references, and any executable examples affected by the API change.

package/lib/index.mjs

@@ -1,9 +0,0 @@
-import MCR from './index.js';
-export default MCR;
-export const CoverageReport = MCR.CoverageReport;
-export const getSnapshot = MCR.getSnapshot;
-export const diffSnapshot = MCR.diffSnapshot;
-
-export const WSSession = MCR.WSSession;
-export const CDPClient = MCR.CDPClient;
-export const Util = MCR.Util;

package/lib/register/hooks.mjs

@@ -1,3 +0,0 @@
-import { load } from './hooks.js';
-
-export { load };

package/lib/register/register.mjs

@@ -1,3 +0,0 @@
-import { register } from 'module';
-
-register('./hooks.mjs', import.meta.url);