@starci/hfs 4.7.0 → 4.7.1

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 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,49 @@
+// 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';
+import path from 'node:path';
+import { lcovFilesUnder, mergeLcov } from '../runtime/scripts/hfs/lcov-merge.mjs';
+
+const USAGE = 'usage: starci app coverage merge --out <lcov> <lcov-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);
+  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) } = {}) {
+  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));
+  }
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "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.6
     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.6
     group: starci
     install: registry
     side: fe
@@ -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.1
     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.1
     group: starci
     install: registry
     side: both

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": "7cf3ce3c9e0abb27fa139c93abbbf15a2f8cc8aec47ba95f022d946b53d8998f",
   "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",
@@ -293,6 +298,11 @@ export const CATALOG = {
               ],
               "required": true,
               "variadic": false
+            },
+            {
+              "name": "paths",
+              "required": true,
+              "variadic": true
             }
           ],
           "flags": [

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

@@ -1,17 +1,24 @@
 // 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.
+// `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() });
+  if (!records.has(source)) records.set(source, { lines: new Map(), fnLines: new Map(), fnHits: new Map(), branches: new Map(), rawBranches: [] });
   return records.get(source);
 }
 
@@ -35,25 +42,63 @@ function dataLine(record, tag, value) {
   } 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]));
+    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]) });
   }
 }
 
-/** Every record of every text, merged by source file (SF) and identity. */
+/** 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 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);
-    }
+  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;
 }

package/sync/ci-commands.mjs

@@ -258,7 +258,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`,