@starci/hfs 4.7.1 → 4.7.2

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 4.7.2 - 2026-10-18
+- Fixed: `app coverage merge` merges the shard istanbul maps through the installed @starci/jest-preset/merge (4.7.1 merged lcov text and reported phantom gaps on real data); the managed unit step sets STARCI_COVERAGE_SHARD and uploads coverage-final.json; `app lint` accepts a canon inside the app's linked node_modules.
+
 ## 4.7.1 - 2026-10-18
 - Fixed: the package files list carries coverage/ (4.7.0 shipped `app coverage merge` without coverage/cli.mjs); the lint upload condition of the managed CI names the per-side report with format() instead of a nested ${{ }} that actionlint reads as always true.
 

package/coverage/cli.mjs

@@ -1,12 +1,12 @@
-// cli.mjs - `starci app coverage merge --out <lcov> <path>...`: the lcov reports of the sharded unit run (one per `npm test -- --shard=i/N`, downloaded into a
-// directory by the coverage job of the managed CI) merged into the one report the coverage proof, the Codecov upload and the Sonar import read
-// (runtime/scripts/hfs/lcov-merge.mjs: hits summed by line, function and branch identity, one record per source file). A path is an lcov file or a
-// directory searched for every lcov.info below it; no report found is a refusal, so a merge never writes an empty report that would read as "nothing to measure".
-import fs from 'node:fs';
+// cli.mjs - `starci app coverage merge --out <lcov> <report-or-dir>...`: the coverage of the sharded unit run (one coverage-final.json per
+// `STARCI_COVERAGE_SHARD=1 npm test -- --shard=i/N`, downloaded into a directory by the coverage job of the managed CI) merged into the one lcov the
+// coverage proof, the Codecov upload and the Sonar import read. The merge is the app's installed @starci/jest-preset (`@starci/jest-preset/merge`):
+// istanbul-lib-coverage merges the shard maps by source location, and the preset's own lcov reporter writes the result exactly as an unsharded run
+// would. A path is a coverage-final.json or a directory searched for every one below it; no report found refuses (exit 2), never an empty report.
 import path from 'node:path';
-import { lcovFilesUnder, mergeLcov } from '../runtime/scripts/hfs/lcov-merge.mjs';
+import { createRequire } from 'node:module';
 
-const USAGE = 'usage: starci app coverage merge --out <lcov> <lcov-or-dir>... [--cwd <dir>]';
+const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>]';
 
 function parse(argv) {
   const [action, ...rest] = argv;
@@ -23,27 +23,30 @@ function parse(argv) {
     else opts.inputs.push(arg);
   }
   if (!opts.out || !opts.inputs.length) throw new Error(USAGE);
+  if (path.basename(opts.out) !== 'lcov.info') throw new Error(`--out names the lcov.info the coverage proof reads; ${USAGE}`);
   return opts;
 }
 
-/** Exit 0 merged, 2 bad usage or no report found. */
-export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s) } = {}) {
+/** The app's installed preset merge (resolved from the app root, like the presets `starci app sync` loads). */
+function installedMerge(cwd) {
+  try { return createRequire(path.join(cwd, 'package.json'))('@starci/jest-preset/merge').mergeCoverage; } catch (error) {
+    throw new Error(`@starci/jest-preset/merge is not installed under ${cwd} (${error.code ?? error.message}); install the canon @starci/jest-preset`);
+  }
+}
+
+/** Exit 0 merged, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge in a spec. */
+export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge } = {}) {
   let opts;
   try { opts = parse(argv); } catch (error) { stderr(`starci app coverage: ${error.message}\n`); return 2; }
   const cwd = path.resolve(baseCwd, opts.cwd ?? '.');
-  const files = [];
-  for (const input of opts.inputs) {
-    const target = path.resolve(cwd, input);
-    if (!fs.existsSync(target)) { stderr(`starci app coverage: ${input} does not exist\n`); return 2; }
-    files.push(...lcovFilesUnder(target));
+  try {
+    const run = merge ?? installedMerge(cwd);
+    const outDir = path.dirname(path.resolve(cwd, opts.out));
+    const result = run({ inputs: opts.inputs.map((input) => path.resolve(cwd, input)), outDir });
+    stdout(`starci app coverage merge: ${result.reports} shard report(s), ${result.files} source file(s) -> ${path.relative(cwd, path.join(outDir, 'lcov.info')).replaceAll('\\', '/')}\n`);
+    return 0;
+  } catch (error) {
+    stderr(`starci app coverage: ${error.message}\n`);
+    return 2;
   }
-  const out = path.resolve(cwd, opts.out);
-  const sources = files.filter((file) => path.resolve(file) !== out);
-  if (!sources.length) { stderr(`starci app coverage: no lcov report under ${opts.inputs.join(', ')}; the unit shards wrote none\n`); return 2; }
-  const merged = mergeLcov(sources.map((file) => fs.readFileSync(file, 'utf8')));
-  fs.mkdirSync(path.dirname(out), { recursive: true });
-  fs.writeFileSync(out, merged);
-  const records = merged.split('\n').filter((line) => line.startsWith('SF:')).length;
-  stdout(`starci app coverage merge: ${sources.length} report(s), ${records} source file(s) -> ${path.relative(cwd, out).replaceAll('\\', '/')}\n`);
-  return 0;
 }

package/lint/run.mjs

@@ -140,7 +140,10 @@ const inside = (root, file) => { const rel = path.relative(root, file); return r
 /** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
 async function sourceFiles({ repoRoot, cwd, side, scope }) {
   const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
-  if (!inside(fs.realpathSync(repoRoot), fs.realpathSync(entry))) throw new Error('the installed canon is outside the app root');
+  // The canon must be the app's own install: resolved inside the app root, or inside the app's node_modules when that folder is a link to the install
+  // (the runtime's examples lint in a sealed copy whose node_modules links the example's own install, scripts/hfs/example-secrets.mjs).
+  const ownInstall = [repoRoot, path.join(repoRoot, 'node_modules')].filter((dir) => fs.existsSync(dir)).map((dir) => fs.realpathSync(dir));
+  if (!ownInstall.some((root) => inside(root, fs.realpathSync(entry)))) throw new Error('the installed canon is outside the app root');
   const canon = await import(pathToFileURL(entry).href);
   const factory = side === 'be' ? canon.starciBeConfig : canon.starciFeConfig;
   if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.1",
+  "version": "4.7.2",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.6
+    version: 3.4.7
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.6
+    version: 8.4.7
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.1
+    version: 2.3.2
     group: starci
     install: registry
     side: be
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.1
+    version: 1.7.2
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.1
+    version: 4.7.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -57,7 +57,7 @@ items:
     check: ci-standard
   - id: test-sharding
     title: the unit run in shards, merged once
-    requires: "the test job is a matrix over shard (ci.jobs.test.shards, default defaults.shards); each shard runs npm test with --shard=<i>/<N> and without the per-file threshold, uploads its lcov, and the coverage job merges them (starci app coverage merge) before the coverage proof proves 100 per file"
+    requires: "the test job is a matrix over shard (ci.jobs.test.shards, default defaults.shards); each shard runs npm test with --shard=<i>/<N>, STARCI_COVERAGE_SHARD=1 (the preset measures only the files the shard loads, no all-files instrumentation, no per-file threshold) and uploads its istanbul JSON; the coverage job merges them by source location (starci app coverage merge, @starci/jest-preset/merge) and the coverage proof then requires every measured file to be present in the merge at 100 per file"
     covers: [app-ci]
     check: ci-standard
   - id: lint-parallel

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "7cf3ce3c9e0abb27fa139c93abbbf15a2f8cc8aec47ba95f022d946b53d8998f",
+  "hash": "1d8f6ce139e98259571df0aee8deccce139214f6aea6fc86ade937ca2dfb445d",
   "global": [
     {
       "name": "json",
@@ -288,7 +288,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "coverage": {
-          "summary": "merge the lcov reports of the sharded unit run into one report",
+          "summary": "merge the coverage of the sharded unit run into one lcov report",
           "owner": "@starci/hfs",
           "positional": [
             {
@@ -309,7 +309,7 @@ export const CATALOG = {
             {
               "name": "out",
               "type": "string",
-              "summary": "the merged lcov to write (the managed CI writes be/coverage/lcov.info)"
+              "summary": "the merged lcov.info to write (the managed CI writes be/coverage/lcov.info)"
             },
             {
               "name": "cwd",
@@ -319,7 +319,7 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "merged",
-            "2": "bad usage or no report found"
+            "2": "bad usage, no installed preset or no report found"
           },
           "json": "none",
           "examples": [
@@ -331,10 +331,12 @@ export const CATALOG = {
           ],
           "impl": null,
           "conventions": [
-            "the CI standard shards the unit run (npm test -- --shard=i/N); each shard writes an lcov over the whole coverage scope",
-            "merge sums every line, function and branch hit by identity across the reports and writes one record per source file",
-            "a path is an lcov file or a directory searched for every lcov.info below it; no report found refuses (exit 2), never an empty report",
-            "the coverage proof (starci app check --coverage-from), the Codecov upload and the Sonar import read the merged report"
+            "the CI standard shards the unit run: STARCI_COVERAGE_SHARD=1 npm test -- --shard=i/N",
+            "each shard measures only the files it loads and writes istanbul JSON (coverage-final.json)",
+            "merge runs the app's installed @starci/jest-preset/merge: istanbul-lib-coverage joins the shard maps by source location",
+            "the merged lcov is written by the preset's own lcov reporter, as an unsharded run writes it",
+            "a path is a coverage-final.json or a directory searched for every one below it; no report found refuses (exit 2)",
+            "the coverage proof (starci app check --coverage-from) refuses a measured file the merge does not hold"
           ],
           "runtimeSide": "host"
         },

package/runtime/scripts/hfs/example-secrets.mjs

@@ -53,6 +53,10 @@ export async function materializeExample(repoRoot, { createIdentity = generateAp
 function trackExample(repoRoot) {
   const env = withoutGitLocalEnv(process.env);
   if (!initGit(repoRoot, { env }).ok) throw new Error('could not initialize the isolated example git tree');
+  // The linked node_modules (linkExampleDependencies: a junction on Windows, a symlink elsewhere) is the install, never a tracked entry: git treats a
+  // symlink as a file, which the app's `node_modules/` (directory) ignore line does not match, so on Linux `git add -A` tracked it (HFS_TRACKED_MUST_BE_IGNORED,
+  // HFS_ROOT_ENTRY_FORBIDDEN in every examples.yml lint since the link). The copy's own exclude file ignores it in any form.
+  fs.appendFileSync(path.join(repoRoot, '.git', 'info', 'exclude'), ['', '# the linked install of the example (example-secrets.mjs)', 'node_modules', ''].join('\n'));
   const staged = addGit(['-A', '--', '.'], { cwd: repoRoot, env });
   if (staged.error || staged.status !== 0) throw new Error('could not stage the isolated example git tree');
 }

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -75,6 +75,7 @@ function testSharding(doc, say) {
   const total = /--shard=\$\{\{\s*matrix\.shard\s*\}\}\/(\d+)/.exec(unit ? runOf(unit) : '');
   if (unit && !total) out.push(say('test-sharding', 'the unit run must pass --shard=${{ matrix.shard }}/<N>'));
   if (total && Array.isArray(shards) && Number(total[1]) !== shards.length) out.push(say('test-sharding', `the unit run's shard total ${total[1]} must equal the ${shards.length} matrix shards`));
+  if (unit && String(unit.env?.STARCI_COVERAGE_SHARD ?? '') !== '1') out.push(say('test-sharding', 'a shard runs the unit step with STARCI_COVERAGE_SHARD: "1": it measures only the files it loads and writes the istanbul JSON the coverage job merges'));
   if (unit && !runOf(unit).includes('--coverageThreshold={}')) out.push(say('test-sharding', 'a shard measures without the per-file threshold (--coverageThreshold={}); the coverage job proves it on the merged report'));
   const coverage = record(doc.jobs?.coverage) ? stepsOf(doc.jobs.coverage) : [];
   const merge = coverage.findIndex((step) => /app coverage merge\b/.test(runOf(step)));

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -18,7 +18,7 @@ const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(va
 const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
 
 const emptyRecord = (source) => ({ source, lines: new Map(), functions: new Map(), branches: new Map(), summary: {}, problems: [] });
-export const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
+const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
 const parseProblem = (record, line, tag) => record.problems.push(`invalid ${tag} at lcov line ${line}`);
 
 function lineData(record, value, line) {

package/sync/ci-commands.mjs

@@ -234,6 +234,8 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
   return {
     ...settings,
     lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
+    // The istanbul JSON a shard writes beside the lcov (STARCI_COVERAGE_SHARD=1): what the coverage job merges.
+    shardCoverageReport: lcovReport.split('/').slice(0, -1).concat('coverage-final.json').join('/'),
     ciBuildEnv: build.env,
     ciBuildSteps: build.steps,
     ciLint: exampleCommand(source, 'npm run lint'),

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -54,16 +54,18 @@ jobs:
     steps:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/jest-cache.yml}}
-      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
-      # the coverage job proves 100 per file on the merged report.
+      # A shard (STARCI_COVERAGE_SHARD=1, the jest preset) measures only the files its specs load, without the per-file threshold, and writes istanbul
+      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. A small suite may leave a shard empty.
       - name: unit
         run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+        env:
+          STARCI_COVERAGE_SHARD: "1"
 {{> app/ci-workflows/jest-cache-save.yml}}
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        if: always() && hashFiles('{{lcovReport}}') != ''
+        if: always() && hashFiles('{{shardCoverageReport}}') != ''
         with:
           name: coverage-shard-${{ matrix.shard }}
-          path: {{lcovReport}}
+          path: {{shardCoverageReport}}
 
   coverage:
     needs: test

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -54,16 +54,18 @@ jobs:
     steps:
 {{> app/ci-workflows/install-steps.yml}}
 {{> app/ci-workflows/jest-cache.yml}}
-      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
-      # the coverage job proves 100 per file on the merged report.
+      # A shard (STARCI_COVERAGE_SHARD=1, the jest preset) measures only the files its specs load, without the per-file threshold, and writes istanbul
+      # JSON; the coverage job merges the shards by source location and proves 100 per file on the merged report. A small suite may leave a shard empty.
       - name: unit
         run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+        env:
+          STARCI_COVERAGE_SHARD: "1"
 {{> app/ci-workflows/jest-cache-save.yml}}
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
-        if: always() && hashFiles('{{lcovReport}}') != ''
+        if: always() && hashFiles('{{shardCoverageReport}}') != ''
         with:
           name: coverage-shard-${{ matrix.shard }}
-          path: {{lcovReport}}
+          path: {{shardCoverageReport}}
 
   coverage:
     needs: test

package/runtime/scripts/hfs/lcov-merge.mjs

@@ -1,134 +0,0 @@
-// lcov-merge.mjs - the lcov reports of the sharded unit run merged into one (`starci app coverage merge`, the coverage job of the managed CI). Each shard of
-// `npm test -- --shard=i/N` writes its own lcov over the whole collectCoverageFrom scope, so the merge sums every line, function and branch hit by its
-// identity across the shards and writes ONE record per source file, with the summaries recomputed.
-// A record of zeros (no line, function or branch hit) is the placeholder a shard writes for a file none of its tests loaded: jest instruments it on its own
-// (babel-istanbul), so its function names and branch ids are not the ones of the shard that ran it (v8), and summing them would add phantom uncovered
-// entries. Such a placeholder is dropped whenever another report holds a record of the file with a hit; a file that is a placeholder everywhere keeps one,
-// so it stays uncovered and the proof refuses it. Branch ids are not stable either: the v8 provider numbers a file's blocks in the order it met them, and a
-// shard that ran fewer functions numbers them differently. A branch is therefore keyed by its line and its ordinal among the blocks of that line (BRDA
-// <line>,<ordinal>,<branch>), and a record that loaded the file without calling any of its functions brings its lines and functions but not its branches
-// when another report called them. The coverage proof (`starci app check --coverage-from`), the Codecov upload and the Sonar import then read
-// the one be/coverage/lcov.info they always read. Pure over the texts; the file walk is lcovFilesUnder.
-import fs from 'node:fs';
-import path from 'node:path';
-import { byCodeUnit } from '../lib/list.mjs';
-import { addHits as add } from './rules/coverage-below.mjs';
-
-const BOM = String.fromCodePoint(0xfeff);
-const count = (value) => (/^\d+$/.test(value) ? Number(value) : 0);
-
-function recordOf(records, source) {
-  if (!records.has(source)) records.set(source, { lines: new Map(), fnLines: new Map(), fnHits: new Map(), branches: new Map(), rawBranches: [] });
-  return records.get(source);
-}
-
-/** Function data: FN:<line>[,<end>],<name> declares, FNDA:<hits>,<name> counts (a name may hold commas). */
-function functionLine(record, tag, value) {
-  const at = value.indexOf(',');
-  if (at < 0) return;
-  if (tag === 'FN') {
-    let name = value.slice(at + 1);
-    let line = value.slice(0, at);
-    if (/^\d+,/.test(name)) { line = `${line},${name.slice(0, name.indexOf(','))}`; name = name.slice(name.indexOf(',') + 1); }
-    if (!record.fnLines.has(name)) record.fnLines.set(name, line);
-    if (!record.fnHits.has(name)) record.fnHits.set(name, 0);
-  } else add(record.fnHits, value.slice(at + 1), count(value.slice(0, at)));
-}
-
-function dataLine(record, tag, value) {
-  if (tag === 'DA') {
-    const [line, hits] = value.split(',');
-    add(record.lines, Number(line), count(hits ?? ''));
-  } else if (tag === 'FN' || tag === 'FNDA') functionLine(record, tag, value);
-  else if (tag === 'BRDA') {
-    const parts = value.split(',');
-    if (parts.length === 4) record.rawBranches.push({ line: Number(parts[0]), block: Number(parts[1]), branch: Number(parts[2]), hits: parts[3] === '-' ? 0 : count(parts[3]) });
-  }
-}
-
-/** The branches of a record keyed by line and the ordinal of their block on that line: stable across shards that numbered blocks differently. */
-function keyBranches(record) {
-  const blocksByLine = new Map();
-  for (const entry of [...record.rawBranches].sort((a, b) => a.block - b.block || a.branch - b.branch)) {
-    const blocks = blocksByLine.get(entry.line) ?? [];
-    if (!blocks.includes(entry.block)) blocks.push(entry.block);
-    blocksByLine.set(entry.line, blocks);
-    add(record.branches, `${entry.line},${blocks.indexOf(entry.block)},${entry.branch}`, entry.hits);
-  }
-  return record;
-}
-
-/** The records of one text by source file (a source repeated inside one text merges into one record). */
-function recordsOfText(text) {
-  const records = new Map();
-  let current = null;
-  const body = String(text).startsWith(BOM) ? String(text).slice(1) : String(text);
-  for (const raw of body.split(/\r?\n/)) {
-    const line = raw.trim();
-    if (line === 'end_of_record') { current = null; continue; }
-    const colon = line.indexOf(':');
-    if (colon < 0) continue;
-    const tag = line.slice(0, colon);
-    const value = line.slice(colon + 1);
-    if (tag === 'SF') current = recordOf(records, value);
-    else if (current) dataLine(current, tag, value);
-  }
-  for (const record of records.values()) keyBranches(record);
-  return records;
-}
-
-const anyHit = (map) => [...map.values()].some((hits) => hits > 0);
-/** A record no test touched: no line, function or branch hit (the placeholder of a shard that never loaded the file). */
-const placeholder = (record) => !anyHit(record.lines) && !anyHit(record.fnHits) && !anyHit(record.branches);
-
-function mergeInto(target, record, { branches = true } = {}) {
-  for (const [line, hits] of record.lines) add(target.lines, line, hits);
-  for (const [name, line] of record.fnLines) if (!target.fnLines.has(name)) target.fnLines.set(name, line);
-  for (const [name, hits] of record.fnHits) add(target.fnHits, name, hits);
-  if (branches) for (const [branch, hits] of record.branches) add(target.branches, branch, hits);
-}
-
-/** Every record of every text merged by source file (SF) and identity; a placeholder counts only when no report touched the file. */
-function parseAll(texts) {
-  const bySource = new Map();
-  for (const text of texts) for (const [source, record] of recordsOfText(text)) bySource.set(source, [...(bySource.get(source) ?? []), record]);
-  const records = new Map();
-  for (const [source, list] of bySource) {
-    const touched = list.filter((record) => !placeholder(record));
-    const target = recordOf(records, source);
-    const called = touched.some((record) => anyHit(record.fnHits));
-    // A record that loaded the file but called none of its functions keeps only its lines and functions when another record called them.
-    for (const record of touched.length ? touched : list.slice(0, 1)) mergeInto(target, record, { branches: !called || anyHit(record.fnHits) });
-  }
-  return records;
-}
-
-const branchOrder = (a, b) => a.split(',').map(Number).reduce((order, part, index) => order || part - Number(b.split(',')[index]), 0);
-
-function serialize(source, record) {
-  const out = ['TN:', `SF:${source}`];
-  const functions = [...record.fnLines.keys()].sort((a, b) => Number(record.fnLines.get(a).split(',')[0]) - Number(record.fnLines.get(b).split(',')[0]) || byCodeUnit(a, b));
-  for (const name of functions) out.push(`FN:${record.fnLines.get(name)},${name}`);
-  for (const name of functions) out.push(`FNDA:${record.fnHits.get(name) ?? 0},${name}`);
-  out.push(`FNF:${functions.length}`, `FNH:${functions.filter((name) => (record.fnHits.get(name) ?? 0) > 0).length}`);
-  const lines = [...record.lines.keys()].sort((a, b) => a - b);
-  for (const line of lines) out.push(`DA:${line},${record.lines.get(line)}`);
-  out.push(`LF:${lines.length}`, `LH:${lines.filter((line) => record.lines.get(line) > 0).length}`);
-  const branches = [...record.branches.keys()].sort(branchOrder);
-  for (const branch of branches) out.push(`BRDA:${branch},${record.branches.get(branch)}`);
-  out.push(`BRF:${branches.length}`, `BRH:${branches.filter((branch) => record.branches.get(branch) > 0).length}`, 'end_of_record');
-  return out.join('\n');
-}
-
-/** One lcov text of the merged `texts`: a record per source file, sorted by path, hits summed by line, function name and branch identity. */
-export function mergeLcov(texts) {
-  const records = parseAll(texts);
-  return [...records.keys()].sort(byCodeUnit).map((source) => serialize(source, records.get(source))).join('\n') + (records.size ? '\n' : '');
-}
-
-/** The lcov files a path names: the file itself, or every `lcov.info` below a directory (sorted). */
-export function lcovFilesUnder(target) {
-  if (!fs.statSync(target).isDirectory()) return [target];
-  return fs.readdirSync(target, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && entry.name === 'lcov.info')
-    .map((entry) => path.join(entry.parentPath ?? entry.path, entry.name)).sort(byCodeUnit);
-}