@starci/jest-preset 2.5.3 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 2.6.0 - 2026-10-31
+
+- Added: the per-spec coverage of the app check cache. With `STARCI_SPEC_COVERAGE_DIR=<folder>` the config adds the reporter `spec-coverage-reporter.js` and runs like a shard (no all-files instrumentation, no threshold): each spec file writes the covered and not-covered statements, functions and branch locations of every measured source as flags, never hit counts, and a failed spec writes none. `@starci/jest-preset/spec-coverage` merges the records of every spec (an item is covered when any spec covers it) into the lcov and coverage-final.json an unsharded run writes. Specs: `test/spec-coverage.spec.ts`.
+
 ## 2.5.3 - 2026-10-30
 
 - Changed: the message that names the managed sync command says `starci app sync --execute`.

package/dist/index.js

@@ -272,9 +272,13 @@ function starciJestConfig(options) {
     // A shard of the managed CI (STARCI_COVERAGE_SHARD=1, one of npm test -- --shard=i/N) measures only the files its tests load, without the per-file threshold, and
     // writes istanbul JSON: the coverage job merges the shards by source location (merge.ts) and the coverage proof enforces 100 per file on the merged report. The
     // all-files instrumentation of collectCoverageFrom is off there: it instruments an unloaded file with another transform (other functions and branches).
-    const shard = process.env.STARCI_COVERAGE_SHARD === "1";
+    // The check cache's unit run (STARCI_SPEC_COVERAGE_DIR=<folder>, `starci app check --test`) is a partial run too: it runs the specs whose key changed, writes the coverage of
+    // each spec file on its own (spec-coverage-reporter.ts) and leaves the threshold to the merged total of every spec's record.
+    const specCoverageDir = process.env.STARCI_SPEC_COVERAGE_DIR;
+    const shard = process.env.STARCI_COVERAGE_SHARD === "1" || Boolean(specCoverageDir);
     return {
         coverageProvider: "v8",
+        ...(specCoverageDir ? { reporters: ["default", [require.resolve("./spec-coverage-reporter.js"), { dir: specCoverageDir, include: collectCoverageFrom(coverage) }]] } : {}),
         ...(shard ? {} : {
             collectCoverageFrom: collectCoverageFrom(coverage),
             // A glob key is applied to every matching file on its own: each measured file must reach 100, not the average.
@@ -282,7 +286,7 @@ function starciJestConfig(options) {
         }),
         coverageDirectory: "coverage",
         // lcov is what Sonar imports (coverage/lcov.info); text-summary and text are what the developer reads; a shard writes the json the merge reads.
-        coverageReporters: shard ? ["text-summary", "json"] : ["text-summary", "text", [require.resolve("./lcov.js"), {}]],
+        coverageReporters: shard ? ["text-summary", ...(specCoverageDir ? [] : ["json"])] : ["text-summary", "text", [require.resolve("./lcov.js"), {}]],
         projects: [
             {
                 ...shared,

package/dist/spec-coverage-reporter.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "@jest/types";
+import type { TestResult } from "@jest/test-result";
+import type { Test } from "@jest/reporters";
+/** The options of the reporter: the folder it writes into and the `collectCoverageFrom` globs that select the measured sources. */
+interface SpecCoverageOptions {
+    readonly dir: string;
+    readonly include: readonly string[];
+}
+declare class SpecCoverageReporter {
+    private readonly options;
+    private readonly pending;
+    constructor(_globalConfig: Config.GlobalConfig, options: SpecCoverageOptions);
+    onTestResult(test: Test, result: TestResult): void;
+    onRunComplete(): Promise<void>;
+    private write;
+    /** The project-relative posix path of a measured source (a path or file URL), undefined when it is not measured. */
+    private relativeSource;
+}
+export = SpecCoverageReporter;

package/dist/spec-coverage-reporter.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+// spec-coverage-reporter.ts - the Jest reporter that writes the coverage of each spec file on its own (see spec-coverage.ts). starciJestConfig adds it
+// (`reporters: ["default", [require.resolve("./spec-coverage-reporter.js"), { dir, include }]]`) when STARCI_SPEC_COVERAGE_DIR names the folder. Jest runs custom
+// reporters before its coverage reporter, so the spec's v8 coverage is still on the test result when it arrives. A failed spec writes `passed: false` and no source.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const node_module_1 = require("node:module");
+const spec_coverage_ts_1 = require("./spec-coverage.js");
+const fromJest = (0, node_module_1.createRequire)(require.resolve("jest"));
+const fromCore = (0, node_module_1.createRequire)(fromJest.resolve("@jest/core"));
+const fromReporters = (0, node_module_1.createRequire)(fromCore.resolve("@jest/reporters"));
+const v8ToIstanbul = fromReporters("v8-to-istanbul");
+const micromatch = fromCore("micromatch");
+const mergeProcessCovs = fromReporters("@bcoe/v8-coverage").mergeProcessCovs;
+const METADATA_SOURCE = require.resolve("./unit-metadata.generated.js");
+const posix = (file) => file.split(node_path_1.default.sep).join("/");
+/** True when a test result is clean: the suite ran and no test failed. */
+function isPassed(result) {
+    return !result.testExecError && !result.failureMessage && result.numFailingTests === 0;
+}
+class SpecCoverageReporter {
+    options;
+    pending = [];
+    constructor(_globalConfig, options) {
+        if (typeof options?.dir !== "string" || !Array.isArray(options.include))
+            throw new Error("the spec coverage reporter needs { dir, include }");
+        this.options = options;
+        node_fs_1.default.mkdirSync(options.dir, { recursive: true });
+    }
+    onTestResult(test, result) {
+        const root = test.context.config.rootDir;
+        this.pending.push(this.write(root, posix(node_path_1.default.relative(root, test.path)), result));
+    }
+    async onRunComplete() {
+        await Promise.all(this.pending);
+    }
+    async write(root, spec, result) {
+        const passed = isPassed(result);
+        const sources = {};
+        if (passed && result.v8Coverage) {
+            const merged = mergeProcessCovs([{ result: result.v8Coverage.map((entry) => entry.result) }]);
+            const transforms = new Map(result.v8Coverage.flatMap((entry) => (entry.codeTransformResult ? [[entry.result.url, entry.codeTransformResult]] : [])));
+            for (const script of merged.result) {
+                if (this.relativeSource(root, script.url) === undefined)
+                    continue;
+                const transform = transforms.get(script.url);
+                const sourceMap = transform?.sourceMapPath && node_fs_1.default.existsSync(transform.sourceMapPath) ? JSON.parse(node_fs_1.default.readFileSync(transform.sourceMapPath, "utf8")) : undefined;
+                const converter = v8ToIstanbul(script.url, transform?.wrapperLength ?? 0, transform && sourceMap
+                    ? { originalSource: transform.originalCode, source: transform.code, sourceMap: { sourcemap: { file: script.url, ...sourceMap } } }
+                    : { source: node_fs_1.default.readFileSync(script.url.startsWith("file:") ? (0, node_url_1.fileURLToPath)(script.url) : script.url, "utf8") });
+                await converter.load();
+                converter.applyCoverage(script.functions);
+                for (const data of Object.values(converter.toIstanbul())) {
+                    const file = this.relativeSource(root, data.path);
+                    if (file !== undefined)
+                        sources[file] = (0, spec_coverage_ts_1.sourceCoverageOf)(data);
+                }
+            }
+        }
+        const record = { spec, passed, sources: Object.fromEntries(Object.entries(sources).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) };
+        node_fs_1.default.writeFileSync(node_path_1.default.join(this.options.dir, (0, spec_coverage_ts_1.specCoverageFileName)(spec)), JSON.stringify(record));
+    }
+    /** The project-relative posix path of a measured source (a path or file URL), undefined when it is not measured. */
+    relativeSource(root, location) {
+        const resolved = node_path_1.default.resolve(location.startsWith("file:") ? (0, node_url_1.fileURLToPath)(location) : location);
+        if (resolved === METADATA_SOURCE)
+            return undefined;
+        const relative = posix(node_path_1.default.relative(root, resolved));
+        if (relative.startsWith("..") || node_path_1.default.isAbsolute(relative))
+            return undefined;
+        const positive = this.options.include.filter((glob) => !glob.startsWith("!"));
+        const negative = this.options.include.filter((glob) => glob.startsWith("!")).map((glob) => glob.slice(1));
+        const measured = micromatch.isMatch(relative, positive, { dot: true }) && !(negative.length > 0 && micromatch.isMatch(relative, negative, { dot: true }));
+        return measured ? relative : undefined;
+    }
+}
+module.exports = SpecCoverageReporter;

package/dist/spec-coverage.d.ts

@@ -0,0 +1,51 @@
+import type { CoverageMap, FileCoverageData } from "istanbul-lib-coverage";
+/** A source range: start line, start column, end line, end column. */
+export type Range = readonly [number, number, number, number];
+/** 1 when the spec covered the item, 0 when the item is instrumented and the spec did not reach it. */
+export type Flag = 0 | 1;
+/** A statement: its range and flag. */
+export type StatementItem = readonly [number, number, number, number, Flag];
+/** A function: its name, declaration range, body range and flag. */
+export type FunctionItem = readonly [string, Range, Range, Flag];
+/** A branch: its type, range and the flag of each of its locations. */
+export type BranchItem = readonly [string, Range, ReadonlyArray<readonly [Range, Flag]>];
+/** What one spec says of one source: every instrumented item and whether the spec covered it. */
+export interface SourceCoverage {
+    readonly s: readonly StatementItem[];
+    readonly f: readonly FunctionItem[];
+    readonly b: readonly BranchItem[];
+}
+/** What the reporter writes for one spec file (`<dir>/<specCoverageFileName(spec)>`). */
+export interface SpecCoverageFile {
+    /** The spec's path relative to the project root, posix. */
+    readonly spec: string;
+    /** False when a test of the spec failed or the spec could not run: it then holds no source, and its coverage is never stored. */
+    readonly passed: boolean;
+    /** Per measured source (path relative to the project root, posix), sorted by path. */
+    readonly sources: Readonly<Record<string, SourceCoverage>>;
+}
+/** The covered/not-covered items of one file's istanbul coverage, sorted so equal coverage is equal bytes. */
+export declare function sourceCoverageOf(data: FileCoverageData): SourceCoverage;
+/** The istanbul coverage of `source` that a record stands for: a covered item has count 1, an uncovered one 0. */
+export declare function fileCoverageOf(source: string, coverage: SourceCoverage): FileCoverageData;
+/** The lines a source's coverage covers (a line is covered when a covered statement starts on it), sorted. */
+export declare function coveredLines(coverage: SourceCoverage): number[];
+/** The merged coverage map of per-spec records: per source the union of the instrumented items, covered when any record covers them. */
+export declare function mergeSourceCoverage(records: Iterable<Readonly<Record<string, SourceCoverage>>>): CoverageMap;
+/**
+ * The union of the per-spec records written as `<outDir>/lcov.info` and `<outDir>/coverage-final.json`; `projectRoot` is the folder the record paths are
+ * relative to (the lcov lists each source relative to it, like an unsharded run's) and `recordRoot` the folder the record paths are relative to when that is
+ * another (the app root, for records that carry app-relative paths). Returns the number of sources.
+ */
+export declare function mergeSpecCoverage({ records, outDir, projectRoot, recordRoot }: {
+    records: Iterable<Readonly<Record<string, SourceCoverage>>>;
+    outDir: string;
+    projectRoot: string;
+    recordRoot?: string;
+}): {
+    files: number;
+};
+/** The file the reporter writes for the spec at `spec` (project-relative, posix). */
+export declare function specCoverageFileName(spec: string): string;
+/** Every spec file the reporter wrote into `dir`, sorted by spec path. */
+export declare function readSpecCoverage(dir: string): SpecCoverageFile[];

package/dist/spec-coverage.js

@@ -0,0 +1,96 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceCoverageOf = sourceCoverageOf;
+exports.fileCoverageOf = fileCoverageOf;
+exports.coveredLines = coveredLines;
+exports.mergeSourceCoverage = mergeSourceCoverage;
+exports.mergeSpecCoverage = mergeSpecCoverage;
+exports.specCoverageFileName = specCoverageFileName;
+exports.readSpecCoverage = readSpecCoverage;
+// spec-coverage.ts - the per-spec coverage of the unit run, the input of the committed check cache (`starci app check --test`).
+// The reporter (spec-coverage-reporter.ts) turns the v8 coverage of ONE spec file into the instrumented items of each measured source and whether this spec
+// covered each: a statement, a function and every location of a branch is 1 (covered) or 0 (instrumented, not covered), never a hit count, so the same run
+// writes the same bytes. This module holds that record and its other direction: `mergeSpecCoverage` is the union of the records of every spec (an item is
+// covered when any spec covers it) written as the lcov and coverage-final.json an unsharded run would write, which is the total the per-file threshold,
+// Codecov and Sonar read.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const node_module_1 = require("node:module");
+const StarciLcovReport = require("./lcov.js");
+const fromJest = (0, node_module_1.createRequire)(require.resolve("jest"));
+const fromCore = (0, node_module_1.createRequire)(fromJest.resolve("@jest/core"));
+const fromReporters = (0, node_module_1.createRequire)(fromCore.resolve("@jest/reporters"));
+const libCoverage = fromReporters("istanbul-lib-coverage");
+const libReport = fromReporters("istanbul-lib-report");
+const rangeOf = (loc) => [loc.start.line, loc.start.column, loc.end.line, loc.end.column];
+const locOf = (range) => ({ start: { line: range[0], column: range[1] }, end: { line: range[2], column: range[3] } });
+const flagOf = (count) => (count > 0 ? 1 : 0);
+const compare = (left, right) => {
+    const a = JSON.stringify(left);
+    const b = JSON.stringify(right);
+    return a < b ? -1 : a > b ? 1 : 0;
+};
+/** The covered/not-covered items of one file's istanbul coverage, sorted so equal coverage is equal bytes. */
+function sourceCoverageOf(data) {
+    const s = Object.entries(data.statementMap).map(([id, loc]) => [loc.start.line, loc.start.column, loc.end.line, loc.end.column, flagOf(data.s[id] ?? 0)]).sort(compare);
+    const f = Object.entries(data.fnMap).map(([id, meta]) => [meta.name, rangeOf(meta.decl), rangeOf(meta.loc), flagOf(data.f[id] ?? 0)]).sort(compare);
+    const b = Object.entries(data.branchMap).map(([id, meta]) => [meta.type, rangeOf(meta.loc), meta.locations.map((loc, index) => [rangeOf(loc), flagOf(data.b[id]?.[index] ?? 0)])]).sort(compare);
+    return { s, f, b };
+}
+/** The istanbul coverage of `source` that a record stands for: a covered item has count 1, an uncovered one 0. */
+function fileCoverageOf(source, coverage) {
+    const data = { path: source, statementMap: {}, fnMap: {}, branchMap: {}, s: {}, f: {}, b: {} };
+    coverage.s.forEach((item, index) => {
+        data.statementMap[String(index)] = locOf([item[0], item[1], item[2], item[3]]);
+        data.s[String(index)] = item[4];
+    });
+    coverage.f.forEach(([name, decl, loc, flag], index) => {
+        data.fnMap[String(index)] = { name, decl: locOf(decl), loc: locOf(loc), line: loc[0] };
+        data.f[String(index)] = flag;
+    });
+    coverage.b.forEach(([type, loc, locations], index) => {
+        data.branchMap[String(index)] = { type, loc: locOf(loc), locations: locations.map(([range]) => locOf(range)), line: loc[0] };
+        data.b[String(index)] = locations.map(([, flag]) => flag);
+    });
+    return data;
+}
+/** The lines a source's coverage covers (a line is covered when a covered statement starts on it), sorted. */
+function coveredLines(coverage) {
+    return [...new Set(coverage.s.filter((item) => item[4] === 1).map((item) => item[0]))].sort((a, b) => a - b);
+}
+/** The merged coverage map of per-spec records: per source the union of the instrumented items, covered when any record covers them. */
+function mergeSourceCoverage(records) {
+    const map = libCoverage.createCoverageMap({});
+    for (const record of records) {
+        for (const [source, coverage] of Object.entries(record))
+            map.merge({ [source]: fileCoverageOf(source, coverage) });
+    }
+    return map;
+}
+/**
+ * The union of the per-spec records written as `<outDir>/lcov.info` and `<outDir>/coverage-final.json`; `projectRoot` is the folder the record paths are
+ * relative to (the lcov lists each source relative to it, like an unsharded run's) and `recordRoot` the folder the record paths are relative to when that is
+ * another (the app root, for records that carry app-relative paths). Returns the number of sources.
+ */
+function mergeSpecCoverage({ records, outDir, projectRoot, recordRoot = projectRoot }) {
+    const absolute = [...records].map((record) => Object.fromEntries(Object.entries(record).map(([source, coverage]) => [node_path_1.default.resolve(recordRoot, source), coverage])));
+    const map = mergeSourceCoverage(absolute);
+    node_fs_1.default.mkdirSync(outDir, { recursive: true });
+    node_fs_1.default.writeFileSync(node_path_1.default.join(outDir, "coverage-final.json"), JSON.stringify(map.toJSON()));
+    const context = libReport.createContext({ dir: outDir, coverageMap: map });
+    new StarciLcovReport({ file: "lcov.info", projectRoot }).execute(context);
+    return { files: map.files().length };
+}
+/** The file the reporter writes for the spec at `spec` (project-relative, posix). */
+function specCoverageFileName(spec) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(spec).digest("hex").slice(0, 24)}.json`;
+}
+/** Every spec file the reporter wrote into `dir`, sorted by spec path. */
+function readSpecCoverage(dir) {
+    const files = node_fs_1.default.readdirSync(dir).filter((name) => name.endsWith(".json")).map((name) => JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(dir, name), "utf8")));
+    return files.sort((a, b) => (a.spec < b.spec ? -1 : a.spec > b.spec ? 1 : 0));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.5.3",
+  "version": "2.6.0",
   "description": "The StarCi jest config for Nest repositories (unit, integration, e2e and contract projects, ts-jest with diagnostics off, per-file 100 coverage of *.service.ts only) and the one shared unit-test double kit: typed mock<T>(), mockEntityManager(), fakeTransaction(), fakeQueryBuilder(), queueQueryBuilders(), fakeCache(), fakeLock(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "MIT",
   "author": "starci183",
@@ -73,6 +73,10 @@
     "./merge": {
       "types": "./dist/merge.d.ts",
       "default": "./dist/merge.js"
+    },
+    "./spec-coverage": {
+      "types": "./dist/spec-coverage.d.ts",
+      "default": "./dist/spec-coverage.js"
     }
   },
   "files": [