@starci/hfs 4.7.0 → 4.7.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.
+
 ## 4.7.0 - 2026-10-18
 - Added: `app release push --execute` pushes the release sha to `release/candidate-<version>` and moves the branch and the tag only when its ci.yml run is green (RELEASE_CANDIDATE_CI_RED / _TIMEOUT, RELEASE_CI_UNKNOWN; the owner's sha-bound override record is the emergency path); the managed ci.yml and pre-push hook carry the candidate ref; R301 CI_STANDARD in the app check.
 - Added: the managed CI shards the unit run (`ci.jobs.test.shards`, default 6), lints each side in its own job and merges coverage in a coverage job (`starci app coverage merge`); `ci.jobs.<job>.timeoutMinutes`; jest/build caches keyed by the lockfile and saved always; `starci app ci local` runs the rendered jobs locally in parallel.

package/ci/local.mjs

@@ -7,7 +7,7 @@
 //   - the unit shards write their lcov to be/coverage/shards/shard-<i> (on GitHub each shard has its own runner and uploads it), which is where the
 //     coverage job's `starci app coverage merge` reads them;
 //   - sonar and db-types run only when --jobs names them.
-// Each instance logs to <tmp>/starci-ci-local-*/<job>[-<matrix>].log. Exit 0 every instance green, 1 one red, 2 bad usage or no ci.yml. Run steps through bash.
+// Each instance logs to <job>[-<matrix>].log in --logs <dir>, else a new <tmp>/starci-ci-local-* directory. Exit 0 every instance green, 1 one red, 2 bad usage or no ci.yml. Run steps through bash.
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -19,15 +19,16 @@ const GITHUB_ONLY_IF = /SONAR_TOKEN\s*!=\s*''|refs\/tags|startsWith\(github\.ref
 const LOCAL_IF = /^(?:\$\{\{\s*)?(?:always\(\)|!cancelled\(\)|env\.SONAR_TOKEN\s*==\s*'')(?:\s*\}\})?$/;
 
 function parseArgs(argv) {
-  const opts = { jobs: null, parallel: Math.max(1, Math.min(4, Math.floor(os.cpus().length / 2))), dryRun: false, json: false };
+  const opts = { logs: null, jobs: null, parallel: Math.max(1, Math.min(4, Math.floor(os.cpus().length / 2))), dryRun: false, json: false };
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === '--dry-run') opts.dryRun = true;
     else if (arg === '--json') opts.json = true;
-    else if (arg === '--jobs' || arg === '--parallel') {
+    else if (arg === '--jobs' || arg === '--parallel' || arg === '--logs') {
       const value = argv[index + 1];
       if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value`);
-      if (arg === '--jobs') opts.jobs = value.split(',').map((job) => job.trim()).filter(Boolean);
+      if (arg === '--logs') opts.logs = value;
+      else if (arg === '--jobs') opts.jobs = value.split(',').map((job) => job.trim()).filter(Boolean);
       else if (!/^[1-9]\d*$/.test(value)) throw new Error('--parallel takes a positive integer');
       else opts.parallel = Number(value);
       index += 1;
@@ -124,7 +125,7 @@ async function runPlan(plan, { parallel, root, env, logs, report }) {
 /** `starci app ci local`. */
 export async function ciLocalMain(argv, { cwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), env = process.env } = {}) {
   let opts;
-  try { opts = parseArgs(argv); } catch (error) { stderr(`starci app ci local: ${error.message}; usage: starci app ci local [--jobs <id,...>] [--parallel <n>] [--dry-run] [--json]\n`); return 2; }
+  try { opts = parseArgs(argv); } catch (error) { stderr(`starci app ci local: ${error.message}; usage: starci app ci local [--jobs <id,...>] [--parallel <n>] [--logs <dir>] [--dry-run] [--json]\n`); return 2; }
   const file = path.join(cwd, '.github', 'workflows', 'ci.yml');
   if (!fs.existsSync(file)) { stderr('starci app ci local: no .github/workflows/ci.yml (run starci app sync --write)\n'); return 2; }
   const plan = localPlan(parseYaml(fs.readFileSync(file, 'utf8')), opts.jobs);
@@ -134,7 +135,8 @@ export async function ciLocalMain(argv, { cwd = process.cwd(), stdout = (s) => p
     else for (const instance of plan) stdout(`${instance.label}${instance.needs.length ? ` (after ${instance.needs.join(', ')})` : ''}\n${instance.steps.map((step) => `  ${step.run !== undefined ? 'run ' : 'skip'} ${step.name}${step.skip ? ` - ${step.skip}` : ''}`).join('\n')}\n`);
     return 0;
   }
-  const logs = fs.mkdtempSync(path.join(os.tmpdir(), 'starci-ci-local-'));
+  const logs = opts.logs ? path.resolve(cwd, opts.logs) : fs.mkdtempSync(path.join(os.tmpdir(), 'starci-ci-local-'));
+  fs.mkdirSync(logs, { recursive: true });
   const defaultBranch = 'main';
   const runEnv = { ...env, CI: 'true', STARCI_BASE_REF: env.STARCI_BASE_REF ?? `origin/${defaultBranch}`, SONAR_TOKEN: '' };
   stdout(`starci app ci local: ${plan.length} job instance(s), ${opts.parallel} at a time; logs in ${logs}\n`);

package/coverage/cli.mjs

@@ -0,0 +1,52 @@
+// 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 { createRequire } from 'node:module';
+
+const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>]';
+
+function parse(argv) {
+  const [action, ...rest] = argv;
+  if (action !== 'merge') throw new Error(USAGE);
+  const opts = { inputs: [] };
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === '--out' || arg === '--cwd') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value; ${USAGE}`);
+      opts[arg.slice(2)] = value;
+      index += 1;
+    } else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}; ${USAGE}`);
+    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;
+}
+
+/** 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 ?? '.');
+  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;
+  }
+}

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.0",
+  "version": "4.7.2",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -22,6 +22,7 @@
     "release/**",
     "db/**",
     "ci/**",
+    "coverage/**",
     "lint/**",
     "scaffold/**",
     "report/**",

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.5
+    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.5
+    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.0
+    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.0
+    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": "441c47efec9ac314fb4ffd8b203fd6469aac65710ca9cd12aace0c032c2c537f",
+  "hash": "1d8f6ce139e98259571df0aee8deccce139214f6aea6fc86ade937ca2dfb445d",
   "global": [
     {
       "name": "json",
@@ -247,6 +247,11 @@ export const CATALOG = {
               "type": "string",
               "summary": "local: job instances run at once (default half the CPUs, at most 4)"
             },
+            {
+              "name": "logs",
+              "type": "string",
+              "summary": "local: the directory the job logs go to (default a new temp directory)"
+            },
             {
               "name": "dry-run",
               "type": "boolean",
@@ -283,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": [
             {
@@ -293,13 +298,18 @@ export const CATALOG = {
               ],
               "required": true,
               "variadic": false
+            },
+            {
+              "name": "paths",
+              "required": true,
+              "variadic": true
             }
           ],
           "flags": [
             {
               "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",
@@ -309,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": [
@@ -321,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'),
@@ -258,7 +260,8 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
         '        env:',
         '          NODE_OPTIONS: --max-old-space-size=6144',
         `      - uses: ${UPLOAD_ARTIFACT}`,
-        `        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.${side}.sonar.json') != ''`,
+        // Inside an if: expression the matrix value is an argument of format(), never a nested ${{ }} (actionlint: a nested expression makes the condition always true).
+        "        if: always() && env.SONAR_TOKEN != '' && hashFiles(format('reports/lint.{0}.sonar.json', matrix.side)) != ''",
         '        with:',
         `          name: sonar-lint-${side}`,
         `          path: reports/lint.${side}.sonar.json`,

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,89 +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 (a file no test of that shard loads is a record of zeros), 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:
-// 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 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() });
-  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) add(record.branches, parts.slice(0, 3).join(','), parts[3] === '-' ? 0 : count(parts[3]));
-  }
-}
-
-/** Every record of every text, merged by source file (SF) and identity. */
-function parseAll(texts) {
-  const records = new Map();
-  for (const text of texts) {
-    let current = null;
-    for (const raw of String(text).replace(/^/, '').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);
-    }
-  }
-  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);
-}