@mifort-solutions/qmetrix 1.0.0

package/src/check-images.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * Image budget check — fails the build when committed images are too heavy for the web.
+ *
+ * Scans public/, src/ and content/ for raster + SVG assets and reports every file that
+ * exceeds the byte budget or (rasters only) the pixel budget. Wired into `npm run verify`.
+ *
+ * Budgets (override per run with flags, per file via EXCEPTIONS below):
+ *   • size:       ≤ 300 KB per file
+ *   • dimensions: ≤ 3840 px on the longest side (raster formats, needs sharp)
+ *
+ * Usage:
+ *   node dev/scripts/check-images.mjs [--max-kb 300] [--max-px 3840]
+ *   npm run images:check
+ *
+ * Fix offenders with:  npm run images:optimize -- <file|dir> [--format webp]
+ */
+
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import path from 'node:path';
+
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const ROOT = process.cwd();
+
+const SCAN_ROOTS = ['public', 'src', 'content'];
+const SKIP_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'coverage']);
+const RASTER_EXT = new Set(['.png', '.jpg', '.jpeg', '.webp', '.avif', '.gif']);
+const VECTOR_EXT = new Set(['.svg']);
+
+// Per-file budget overrides, keyed by posix path relative to the repo root.
+// Use sparingly — prefer optimizing the asset over raising its budget.
+//   ['public/images/huge-hero.png', { maxKB: 800 }],
+const EXCEPTIONS = new Map([]);
+
+/* ── CLI flags ── */
+const argv = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] ? Number(argv[i + 1]) : fallback;
+};
+const MAX_KB = flag('--max-kb', 300);
+const MAX_PX = flag('--max-px', 3840);
+
+/* ── helpers ── */
+const rel = (p) => path.relative(ROOT, p).split(path.sep).join('/');
+const fmtKB = (bytes) =>
+  bytes >= 1024 * 1024
+    ? `${(bytes / 1024 / 1024).toFixed(1)} MB`
+    : `${Math.round(bytes / 1024)} KB`;
+
+function* walk(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name)) {
+        yield* walk(path.join(dir, entry.name));
+      }
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (RASTER_EXT.has(ext) || VECTOR_EXT.has(ext)) {
+        yield path.join(dir, entry.name);
+      }
+    }
+  }
+}
+
+// sharp ships with Next 16; degrade to size-only checks if it ever goes missing.
+let sharp = null;
+try {
+  sharp = (await import('sharp')).default;
+} catch {
+  console.log('⚠  sharp not found — checking file sizes only (no dimension checks).');
+}
+
+/* ── scan ── */
+const violations = [];
+let checked = 0;
+
+for (const root of SCAN_ROOTS) {
+  const abs = path.join(ROOT, root);
+  if (!existsSync(abs)) {
+    continue;
+  }
+  for (const file of walk(abs)) {
+    checked++;
+    const relPath = rel(file);
+    const maxKB = EXCEPTIONS.get(relPath)?.maxKB ?? MAX_KB;
+    const bytes = statSync(file).size;
+    const problems = [];
+
+    if (bytes > maxKB * 1024) {
+      problems.push(`${fmtKB(bytes)} (budget ${maxKB} KB)`);
+    }
+
+    if (sharp && RASTER_EXT.has(path.extname(file).toLowerCase())) {
+      try {
+        const { width = 0, height = 0 } = await sharp(file).metadata();
+        if (Math.max(width, height) > MAX_PX) {
+          problems.push(`${width}×${height} px (budget ${MAX_PX} px)`);
+        }
+      } catch {
+        problems.push('unreadable by sharp (corrupt image?)');
+      }
+    }
+
+    if (problems.length) {
+      violations.push({ relPath, problems });
+    }
+  }
+}
+
+/* ── report ── */
+console.log(`\n==  Image budget check  ==  (${checked} files, ≤${MAX_KB} KB, ≤${MAX_PX} px)\n`);
+
+if (violations.length === 0) {
+  console.log('✓ All images within budget.\n');
+  process.exit(0);
+}
+
+for (const v of violations) {
+  console.log(`  ✗ ${v.relPath}\n      ${v.problems.join(' · ')}`);
+}
+console.log(`\n${violations.length} image(s) over budget. Fix with:`);
+console.log('  npm run images:optimize -- <file|dir> [--format webp]');
+console.log('or add a justified exception in dev/scripts/check-images.mjs (EXCEPTIONS).\n');
+process.exit(1);

package/src/coverage/clean.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Remove a coverage suite's outputs before a fresh run.
+ *
+ * MCR's own coverage cache lives under <report-dir>/.cache and is cleared by MCR
+ * on generate, so removing the report dir covers it. NODE_V8_COVERAGE server
+ * dumps live separately under .raw/<suite>-server/ and must be cleared here so a
+ * rerun doesn't fold in last run's dumps.
+ *
+ *   node dev/scripts/coverage/clean.mjs <e2e|storybook|global>
+ */
+import { rmSync } from 'node:fs';
+import path from 'node:path';
+
+const suite = process.argv[2];
+if (!suite) {
+  console.error('usage: node dev/scripts/coverage/clean.mjs <e2e|storybook|global>');
+  process.exit(1);
+}
+
+const ROOT = process.cwd();
+const COV = path.join(ROOT, 'dist', 'reports', 'coverage');
+
+const targets = [path.join(COV, suite)];
+if (suite !== 'global') {
+  targets.push(path.join(COV, '.raw', `${suite}-server`));
+}
+
+for (const dir of targets) {
+  rmSync(dir, { recursive: true, force: true });
+  console.log(`[coverage:clean] removed ${path.relative(ROOT, dir) || dir}`);
+}

package/src/coverage/merge-istanbul.mjs

@@ -0,0 +1,161 @@
+/**
+ * Collapse N per-suite Istanbul coverage maps into ONE, unioning coverage at the
+ * LINE level onto each file's richest structure.
+ *
+ * Why this is custom — and can't be a native istanbul/monocart merge: the three
+ * suites are instrumented by DIFFERENT tools (unit by jest's own istanbul
+ * instrumentation; e2e + storybook by monocart V8→istanbul). For the same source
+ * file their statementMap / fnMap / branchMap geometry differs, so istanbul's structural
+ * merge unions hit counts only when the maps are byte-identical; when they aren't
+ * it stacks them side by side and the per-file totals DOUBLE — a file covered by
+ * e2e but not unit then reads ~50% (one covered copy + one empty copy) instead of
+ * 100%, most visibly on tiny files like src/app/loading.tsx (1 fn → 1/2).
+ *
+ * This cross-instrumenter mismatch is IRREDUCIBLE while the browser/server suites
+ * use V8 coverage — verified empirically (2026-06-13): unit vs V8(e2e) maps
+ * matched on 5/129 shared files; jest's own `coverageProvider: v8` matched 0/129
+ * (a different v8-to-istanbul converter, degenerate fn/branch geometry); and the
+ * only route to identical geometry — istanbul-instrumenting the build — is closed
+ * because Turbopack ignores `experimental.swcPlugins` and would need the
+ * deprecated `--webpack` builder. So we union by line ourselves rather than hand
+ * two structures to a merger that can't reconcile them. See
+ * dev/docs/coverage-by-suite-plan.md § "Why the global merge is a custom union".
+ *
+ * The union: per file, pick the suite map with the most statements as the
+ * canonical structure, collect the set of source lines covered by ANY suite, and
+ * mark covered anything the canonical map left at 0 whose line is in that set. All
+ * suites instrument the SAME source, so 1-based line numbers are a shared
+ * coordinate system. Statements/branches union on their START line (istanbul's own
+ * line-coverage model); functions union on their full body RANGE, so a callback
+ * whose declaration line rendered but whose body never ran is NOT credited. The
+ * result is exactly one FileCoverage per file — nothing doubles — and the headline
+ * is the intended "covered by ANY suite" at line granularity.
+ *
+ * Single-suite files pass through untouched (the union of one map is itself), so
+ * this only changes files that appeared in more than one suite — the doubled ones.
+ *
+ * Limitation: across coarse (V8) vs fine (babel/SWC) maps the function/branch
+ * union is approximate — line coverage is the reliable headline.
+ */
+
+const lineOf = (loc) => loc?.start?.line ?? null;
+const stmtCount = (fc) => Object.keys(fc.statementMap || {}).length;
+
+/** The line range to test a function against: full body if known, else its decl line. */
+const fnLoc = (fn) =>
+  fn?.loc ??
+  fn?.decl ??
+  (fn?.line != null ? { start: { line: fn.line }, end: { line: fn.line } } : null);
+
+/** Does the union cover any source line inside [loc.start.line, loc.end.line]? */
+function rangeCovered(loc, union) {
+  const from = lineOf(loc);
+  if (from == null) {
+    return false;
+  }
+  const to = loc.end?.line ?? from;
+  for (let l = from; l <= to; l++) {
+    if (union.has(l)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Per-map collectors of executed source lines (split out so coveredLines stays
+// under the complexity gate). Each adds to the shared set in place.
+function addStatementLines(fc, lines) {
+  for (const [i, loc] of Object.entries(fc.statementMap || {})) {
+    if ((fc.s?.[i] || 0) > 0) {
+      lines.add(lineOf(loc));
+    }
+  }
+}
+function addFnLines(fc, lines) {
+  for (const [i, fn] of Object.entries(fc.fnMap || {})) {
+    if ((fc.f?.[i] || 0) > 0) {
+      lines.add(lineOf(fn.decl ?? { start: { line: fn.line } }));
+    }
+  }
+}
+function addBranchLines(fc, lines) {
+  for (const [i, br] of Object.entries(fc.branchMap || {})) {
+    const counts = fc.b?.[i] || [];
+    (br.locations || []).forEach((loc, j) => {
+      if ((counts[j] || 0) > 0) {
+        lines.add(lineOf(loc));
+      }
+    });
+  }
+}
+
+/** Lines a single FileCoverage marks executed: covered statements + fn decls + branch arms. */
+function coveredLines(fc) {
+  const lines = new Set();
+  addStatementLines(fc, lines);
+  addFnLines(fc, lines);
+  addBranchLines(fc, lines);
+  lines.delete(null);
+  return lines;
+}
+
+/** Bump anything the canonical map left at 0 whose source line ANY suite covered. */
+function applyUnion(out, union) {
+  for (const [i, loc] of Object.entries(out.statementMap || {})) {
+    if (!out.s[i] && union.has(lineOf(loc))) {
+      out.s[i] = 1;
+    }
+  }
+  for (const [i, fn] of Object.entries(out.fnMap || {})) {
+    if (!out.f[i] && rangeCovered(fnLoc(fn), union)) {
+      out.f[i] = 1;
+    }
+  }
+  for (const [i, br] of Object.entries(out.branchMap || {})) {
+    const counts = out.b[i] || [];
+    (br.locations || []).forEach((loc, j) => {
+      if (!counts[j] && union.has(lineOf(loc))) {
+        counts[j] = 1;
+      }
+    });
+    out.b[i] = counts;
+  }
+}
+
+/** Merge several FileCoverage maps of the SAME file into one (line-level union). */
+function mergeFile(path, maps) {
+  const union = new Set();
+  for (const fc of maps) {
+    for (const l of coveredLines(fc)) {
+      union.add(l);
+    }
+  }
+  // Canonical structure = richest map (most statements); first-wins → deterministic.
+  const base = maps.reduce((a, b) => (stmtCount(b) > stmtCount(a) ? b : a), maps[0]);
+  const out = JSON.parse(JSON.stringify(base));
+  out.path = path;
+  applyUnion(out, union);
+  return out;
+}
+
+/**
+ * @param {Array<Record<string, object>>} suites - canonicalized istanbul maps,
+ *   one object per suite, keyed by the SAME canonical path (e.g. 'src/app/x.tsx').
+ * @returns {Record<string, object>} one merged FileCoverage per path.
+ */
+export function mergeIstanbulSuites(suites) {
+  const byPath = new Map();
+  for (const data of suites) {
+    for (const [p, fc] of Object.entries(data)) {
+      if (!byPath.has(p)) {
+        byPath.set(p, []);
+      }
+      byPath.get(p).push(fc);
+    }
+  }
+  const out = {};
+  for (const [p, maps] of byPath) {
+    out[p] = maps.length === 1 ? maps[0] : mergeFile(p, maps);
+  }
+  return out;
+}

package/src/coverage/next-start-cov.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/**
+ * Launch `next start` in-process and flush V8 coverage on shutdown signals.
+ *
+ * NODE_V8_COVERAGE is only written on a CLEAN process exit. Playwright stops the
+ * web server with SIGTERM — and on Windows that terminates the process WITHOUT
+ * delivering a catchable signal, so a shutdown-only flush never runs and the
+ * server-side coverage is lost. So we flush on a short interval: `v8.takeCoverage()`
+ * writes the cumulative coverage to the NODE_V8_COVERAGE dir on demand, so the
+ * latest snapshot survives even an abrupt kill. Signal/exit handlers add a final
+ * flush where the platform allows it. Used only by the coverage:e2e web server
+ * (see playwright.config.ts).
+ */
+import v8 from 'node:v8';
+
+const flush = () => {
+  try {
+    v8.takeCoverage();
+  } catch {
+    // takeCoverage throws if NODE_V8_COVERAGE isn't set — nothing to flush then.
+  }
+};
+
+// Periodic flush is the load-bearing one (survives Windows' non-graceful kill).
+const timer = setInterval(flush, 1500);
+timer.unref?.();
+
+const shutdown = () => {
+  flush();
+  process.exit(0);
+};
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+process.on('exit', flush);
+
+// The Next CLI reads process.argv.slice(2); make it `start`.
+process.argv.splice(2, process.argv.length, 'start');
+await import('next/dist/bin/next');

package/src/coverage/report-global.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Merge all three suites into one global coverage report over the full src/ tree.
+ *
+ *   unit       → dist/reports/coverage/unit/coverage-final.json       (jest istanbul)
+ *   e2e        → dist/reports/coverage/e2e/coverage-final.json        (browser + server V8 → istanbul)
+ *   storybook  → dist/reports/coverage/storybook/coverage-final.json  (browser V8 → istanbul)
+ *
+ * All three are Istanbul coverage maps already scoped to src/. They are
+ * instrumented by DIFFERENT tools (unit: jest/babel; e2e + storybook: monocart
+ * V8 → istanbul), so the same file has different statementMap/fnMap structures
+ * across suites. Handing those straight to monocart/istanbul does NOT union them —
+ * mismatched structures are stacked side by side and per-file totals double, so a
+ * file covered by e2e but not unit reads ~50% instead of 100%. We therefore
+ * pre-merge into ONE structure per file (mergeIstanbulSuites, line-level union)
+ * before add(). Run the per-suite steps first (coverage:unit / :e2e / :storybook).
+ *
+ * The merged global figure is "covered by ANY suite" at line granularity — the
+ * right headline number. (See dev/docs/coverage-by-suite-plan.md.)
+ *
+ *   node dev/scripts/coverage/report-global.mjs
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { CoverageReport } from 'monocart-coverage-reports';
+
+import { mergeIstanbulSuites } from './merge-istanbul.mjs';
+import { inSrc } from './src-filter.mjs';
+
+const ROOT = process.cwd();
+const COV = path.join(ROOT, 'dist', 'reports', 'coverage');
+
+const mcr = new CoverageReport({
+  name: 'Global coverage (unit + e2e + storybook)',
+  outputDir: path.join(COV, 'global'),
+  sourceFilter: inSrc,
+  // istanbul reporters only (text-summary, not v8 'console-summary') so no Bytes /
+  // V8-Lines column appears anywhere — the merged input is istanbul maps with no
+  // byte data, so every metric here is statement/fn/branch-derived.
+  reports: ['text-summary', 'html', 'json', 'json-summary', 'lcovonly'],
+});
+
+/**
+ * Canonicalize istanbul file keys to `src/<path>` (posix) so the same file is
+ * unified across suites. jest emits absolute Windows paths
+ * (C:\…\src\foo.tsx); MCR emits project-relative ones (name/src/foo.tsx) — left
+ * as-is they'd be treated as two different files and inflate the denominator.
+ */
+function canonicalize(data) {
+  const out = {};
+  for (const [k, v] of Object.entries(data)) {
+    const p = k.replace(/\\/g, '/');
+    const i = p.lastIndexOf('/src/');
+    const key = i >= 0 ? p.slice(i + 1) : p; // 'src/…'
+    // Safety net: only merge real project src/ files. A stale suite-final could
+    // still carry unmapped `.next/server/**` dist bundles (Turbopack route stubs /
+    // runtime chunks); inSrc drops anything that doesn't resolve under <root>/src.
+    if (!inSrc(key)) {
+      continue;
+    }
+    out[key] = { ...v, path: key };
+  }
+  return out;
+}
+
+const suites = [];
+for (const suite of ['unit', 'e2e', 'storybook']) {
+  const f = path.join(COV, suite, 'coverage-final.json');
+  if (!existsSync(f)) {
+    console.warn(`[coverage:global] ${suite}/coverage-final.json missing — run coverage:${suite}.`);
+    continue;
+  }
+  suites.push(canonicalize(JSON.parse(readFileSync(f, 'utf8'))));
+}
+const parts = suites.length;
+
+if (!parts) {
+  console.warn('[coverage:global] no suite reports found — run coverage:unit / :e2e / :storybook.');
+} else {
+  // Union the suites into one structure per file BEFORE handing to monocart, so
+  // cross-instrumenter structure mismatches can't double the per-file totals.
+  await mcr.add(mergeIstanbulSuites(suites));
+}
+
+const res = await mcr.generate();
+const pct = res?.summary?.lines?.pct;
+console.log(
+  `[coverage:global] merged ${parts} suite(s) → dist/reports/coverage/global/coverage-final.json (lines ${pct ?? '?'}%)`,
+);

package/src/coverage/report-suite.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Generate a Playwright suite's Istanbul coverage report.
+ *
+ * The browser-side V8 coverage was already resolved against source maps and
+ * cached by the in-test fixture (.config/coverage-fixture.ts) — see the
+ * comment there for why that has to happen while the server is live. This step
+ * just adds the server-side V8 dumps (e2e only; their maps are on disk so they
+ * resolve offline) and renders the report from the shared cache.
+ *
+ * Cache (browser, written by the fixture across workers):
+ *   dist/reports/coverage/.cache/<suite>/
+ * Server V8 (NODE_V8_COVERAGE, inspector format; e2e only):
+ *   dist/reports/coverage/.raw/<suite>-server/*.json
+ * Output:
+ *   dist/reports/coverage/<suite>/coverage-final.json   (Istanbul, src/-mapped)
+ *   dist/reports/coverage/<suite>/coverage-summary.json
+ *   dist/reports/coverage/<suite>/lcov.info
+ *   dist/reports/coverage/<suite>/index.html            (istanbul HTML report)
+ *
+ *   node dev/scripts/coverage/report-suite.mjs <e2e|storybook>
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { CoverageReport } from 'monocart-coverage-reports';
+
+import { inSrc } from './src-filter.mjs';
+
+// Picking the value out of the constant list (rather than trusting argv) keeps
+// the argument from ever being used as a path fragment.
+const suite = ['e2e', 'storybook'].find((s) => s === process.argv[2]);
+if (!suite) {
+  console.error('usage: node dev/scripts/coverage/report-suite.mjs <e2e|storybook>');
+  process.exit(1);
+}
+
+const ROOT = process.cwd();
+const COV = path.join(ROOT, 'dist', 'reports', 'coverage');
+const baseDir = path.join(COV, suite);
+// MCR forces cacheDir to <outputDir>/.cache; the fixture (same outputDir) wrote
+// the resolved browser coverage there, and generate() reads it back.
+const cacheDir = path.join(baseDir, '.cache');
+
+const mcr = new CoverageReport({
+  name: `${suite} coverage`,
+  outputDir: baseDir,
+  // Keep server bundles (file: URLs, source attached below) and browser bundles
+  // that carry a source map; drop node_modules and map-less runtime bundles.
+  entryFilter: (entry) => {
+    const url = String(entry.url || '');
+    if (!url || url.includes('node_modules')) {
+      return false;
+    }
+    if (url.startsWith('file:') || /[\\/]\.next[\\/]/.test(url)) {
+      return true;
+    }
+    return /sourceMappingURL=/.test(String(entry.source || ''));
+  },
+  sourceFilter: inSrc,
+  // Turbopack labels server-bundle sources `[project]/src/…`; the browser half of
+  // the same suite labels the identical file `src/…`. Strip the `[project]/`
+  // prefix so both halves collapse onto one `src/…` key — otherwise a file
+  // exercised on both server and client is listed (and counted) twice.
+  sourcePath: (filePath) => {
+    const s = String(filePath).replace(/\\/g, '/');
+    return s.startsWith('[project]/') ? s.slice('[project]/'.length) : s;
+  },
+  // istanbul reporters only — deliberately NOT monocart's 'v8' reporter. The v8
+  // report's headline (Bytes / V8-Lines) is byte-RANGE coverage: a module that was
+  // imported but never invoked reads ~100% there (its top-level eval covers the
+  // file's byte span) while no function actually ran — false confidence. istanbul
+  // 'html' + 'text-summary' derive every metric from statement/fn/branch hits, so a
+  // loaded-but-not-run file honestly reads ~0%. coverage-final.json is unaffected
+  // either way — it never carried byte data — so the global merge is unchanged.
+  reports: ['html', 'text-summary', 'json', 'json-summary', 'lcovonly'],
+});
+
+// Read a server bundle's sibling source map and return its `sources` list
+// (Turbopack maps may be sectioned). Returns [] when the map is missing or empty.
+const mapSourcesFor = (bundlePath) => {
+  try {
+    const map = JSON.parse(readFileSync(`${bundlePath}.map`, 'utf8'));
+    const srcs = map.sections
+      ? map.sections.flatMap((s) => s.map?.sources || [])
+      : map.sources || [];
+    return srcs.map(String);
+  } catch {
+    return [];
+  }
+};
+
+// Server-side V8 (e2e): NODE_V8_COVERAGE inspector dumps. These carry no source
+// text, so attach it from disk (MCR drops entries without source); the on-disk
+// `.next/server/**/*.js.map` then resolve offline. We only bother loading source
+// for .next server bundles — Node internals (node:…) are skipped.
+//
+// We also DROP any bundle whose map carries no project `src/` file: Turbopack
+// route stubs ship an empty map (`sources: []`) and runtime/action chunks map
+// only to node_modules. MCR's `sourceFilter` runs solely on sources unpacked FROM
+// a map, so these never reach it — without this gate MCR keeps the raw
+// `.next/server/**` dist file in the report instead of real source files.
+let server = 0;
+const serverDir = path.join(COV, '.raw', `${suite}-server`);
+const loadSource = (entry) => {
+  const url = String(entry.url || '');
+  if (!/[\\/]\.next[\\/]/.test(url)) {
+    return null;
+  }
+  try {
+    const p = url.startsWith('file:') ? fileURLToPath(url) : url;
+    if (!mapSourcesFor(p).some(inSrc)) {
+      return null;
+    }
+    return { ...entry, source: readFileSync(p, 'utf8') };
+  } catch {
+    return null;
+  }
+};
+if (existsSync(serverDir)) {
+  for (const f of readdirSync(serverDir)) {
+    if (!f.endsWith('.json')) {
+      continue;
+    }
+    const { result } = JSON.parse(readFileSync(path.join(serverDir, f), 'utf8'));
+    if (!Array.isArray(result)) {
+      continue;
+    }
+    const withSource = result.map(loadSource).filter(Boolean);
+    if (withSource.length) {
+      await mcr.add(withSource);
+      server++;
+    }
+  }
+}
+
+if (!existsSync(cacheDir) && server === 0) {
+  console.warn(
+    `[coverage:${suite}] no coverage cache at ${path.relative(ROOT, cacheDir)} and no server dumps — did the suite run with COVERAGE=1?`,
+  );
+}
+
+const res = await mcr.generate();
+const pct = res?.summary?.lines?.pct;
+console.log(
+  `[coverage:${suite}] server-dumps=${server} → ${path.relative(ROOT, baseDir)}/coverage-final.json (lines ${pct ?? '?'}%)`,
+);

package/src/coverage/src-filter.mjs

@@ -0,0 +1,50 @@
+/**
+ * Shared source filter for the coverage reports (report-suite.mjs, report-global.mjs).
+ *
+ * Mirrors jest's collectCoverageFrom (.config/jest.config.mjs): the project's own
+ * src/**\/*.{ts,tsx} minus stories, tests, e2e specs and .d.ts, so all four suites
+ * share one file universe.
+ *
+ * The on-disk existence check is load-bearing: bundled third-party packages
+ * (lucide-react, @heroui/*) ship source maps whose `sources` are bare `src/…` /
+ * `shared/src/…` paths with NO node_modules prefix, so a plain `/src/` match would
+ * fold ~230 vendor files into the totals. Resolving the tail against <root>/src and
+ * requiring it to exist keeps only the app's real source files.
+ *
+ * Vendor maps that DO keep the `node_modules/` prefix (e.g.
+ * `node_modules/@opentelemetry/instrumentation/src/instrumentation.ts`) would still
+ * slip through when their tail collides with a real file name (we have
+ * `src/instrumentation.ts`), so reject anything under node_modules outright first.
+ */
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+const SRC_ROOT = path.join(process.cwd(), 'src');
+
+export function inSrc(sourcePath) {
+  const s = String(sourcePath).replace(/\\/g, '/');
+  if (s.includes('node_modules/')) {
+    return false;
+  }
+  const i = s.lastIndexOf('/src/');
+  const rel = i >= 0 ? s.slice(i + 5) : s.startsWith('src/') ? s.slice(4) : null;
+  if (rel == null) {
+    return false;
+  }
+  if (!/\.(ts|tsx)$/.test(rel)) {
+    return false;
+  }
+  if (/\.stories\.tsx$/.test(rel)) {
+    return false;
+  }
+  if (/\.test\.(ts|tsx)$/.test(rel)) {
+    return false;
+  }
+  if (/\.(e2e|storybook)\.spec\.ts$/.test(rel)) {
+    return false;
+  }
+  if (/\.d\.ts$/.test(rel)) {
+    return false;
+  }
+  return existsSync(path.join(SRC_ROOT, rel));
+}