@starci/jest-preset 2.3.6 → 2.4.0

package/dist/index.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORLD_RUNNER = exports.UNIT_COMPILER_OPTIONS = exports.COVERAGE_THRESHOLD = exports.COVERAGE_EXCLUDES = exports.FakeIds = exports.fakeIds = exports.builder = exports.fakeInbox = exports.recordingQueueOutbox = exports.recordingEventBus = exports.fakeLock = exports.fakeCache = exports.FakeClock = exports.fakeTransaction = exports.mockEntityManager = exports.createMock = exports.mock = exports.MODULE_NAME_MAPPER = exports.TEST_KIND_FOLDERS = void 0;
+exports.starciJestConfig = starciJestConfig;
+exports.collectCoverageFrom = collectCoverageFrom;
+exports.rootGlob = rootGlob;
+exports.sonarExclusions = sonarExclusions;
+exports.hasCoverageSubjects = hasCoverageSubjects;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const mock_ts_1 = require("./mock.js");
+Object.defineProperty(exports, "mock", { enumerable: true, get: function () { return mock_ts_1.mock; } });
+Object.defineProperty(exports, "createMock", { enumerable: true, get: function () { return mock_ts_1.createMock; } });
+const entity_manager_ts_1 = require("./entity-manager.js");
+Object.defineProperty(exports, "mockEntityManager", { enumerable: true, get: function () { return entity_manager_ts_1.mockEntityManager; } });
+Object.defineProperty(exports, "fakeTransaction", { enumerable: true, get: function () { return entity_manager_ts_1.fakeTransaction; } });
+const clock_ts_1 = require("./clock.js");
+Object.defineProperty(exports, "FakeClock", { enumerable: true, get: function () { return clock_ts_1.FakeClock; } });
+const cache_ts_1 = require("./cache.js");
+Object.defineProperty(exports, "fakeCache", { enumerable: true, get: function () { return cache_ts_1.fakeCache; } });
+const lock_ts_1 = require("./lock.js");
+Object.defineProperty(exports, "fakeLock", { enumerable: true, get: function () { return lock_ts_1.fakeLock; } });
+const event_bus_ts_1 = require("./event-bus.js");
+Object.defineProperty(exports, "recordingEventBus", { enumerable: true, get: function () { return event_bus_ts_1.recordingEventBus; } });
+const queue_ts_1 = require("./queue.js");
+Object.defineProperty(exports, "recordingQueueOutbox", { enumerable: true, get: function () { return queue_ts_1.recordingQueueOutbox; } });
+const inbox_ts_1 = require("./inbox.js");
+Object.defineProperty(exports, "fakeInbox", { enumerable: true, get: function () { return inbox_ts_1.fakeInbox; } });
+const builders_ts_1 = require("./builders.js");
+Object.defineProperty(exports, "builder", { enumerable: true, get: function () { return builders_ts_1.builder; } });
+const ids_ts_1 = require("./ids.js");
+Object.defineProperty(exports, "fakeIds", { enumerable: true, get: function () { return ids_ts_1.fakeIds; } });
+Object.defineProperty(exports, "FakeIds", { enumerable: true, get: function () { return ids_ts_1.FakeIds; } });
+const SONAR_EXCLUSIONS = require("./sonar-exclusions.js");
+/**
+ * Coverage is measured where logic runs: every file `<name>.<role>.ts` of a LOGIC role (service, policy, projection, guard, mapper, client, ...)
+ * inside the roots the slot manifest marks `coverage: required` (the modules of the back end: domain, integrations, platform, projections).
+ * The features (handlers, resolvers, controllers, consumers, processors, steps, sagas, cli commands) are thin by rule (BE_FEATURE_THIN) and are
+ * never measured. The scope is NOT written here: `starci app sync` renders it from the manifest (scripts/hfs/coverage-scope.mjs) into the repository's
+ * jest.config.js as `starciJestConfig({ coverage: { roots, roles, excludes } })`, and the same derivation renders Sonar's
+ * `sonar.coverage.exclusions` and the Codecov paths and components, so the three can never disagree. Every measured file must reach 100 on every metric.
+ * The unit run also writes `coverage/lcov.info`: Sonar and Codecov import it.
+ */
+const COVERAGE_EXCLUDES = ["**/dist/**", "**/coverage/**"];
+exports.COVERAGE_EXCLUDES = COVERAGE_EXCLUDES;
+/** The four metrics, each held at 100 per file. */
+const COVERAGE_THRESHOLD = Object.freeze({ lines: 100, branches: 100, functions: 100, statements: 100 });
+exports.COVERAGE_THRESHOLD = COVERAGE_THRESHOLD;
+/** The glob one measured root stands for: every file of a logic role below it. */
+function rootGlob(root, roles) {
+    return `${root}**/*.${roles.length === 1 ? roles[0] : `{${roles.join(",")}}`}.ts`;
+}
+/**
+ * jest's `collectCoverageFrom` of a coverage scope `{ roots, roles, excludes }`: the glob of every root, then the none directories inside a
+ * root (`excludes`, each a glob that ends in `**`) and the generated folders as negations.
+ */
+function collectCoverageFrom(coverage) {
+    return [...coverage.roots.map((root) => rootGlob(root, coverage.roles)), ...[...coverage.excludes, ...COVERAGE_EXCLUDES].map((glob) => `!${glob}`)];
+}
+/** One union glob keeps Jest's per-file checks while a scoped map may contain files from only one measured root. */
+function coverageThresholdOf(coverage, root) {
+    const rootGlobs = coverage.roots.map((entry) => rootGlob(entry, coverage.roles)).filter((glob) => hasCoverageSubjects(root, glob));
+    if (rootGlobs.length === 0)
+        return {};
+    const glob = rootGlobs.length === 1 ? rootGlobs[0] : `{${rootGlobs.join(",")}}`;
+    return { [`./${glob}`]: { ...COVERAGE_THRESHOLD } };
+}
+/**
+ * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. The list lives in sonar-exclusions.ts, a
+ * require-free module whose built file @starci/hfs also ships (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs), so `starci app scaffold`
+ * renders the same exclusions before any app dependency is installed.
+ */
+function sonarExclusions() {
+    return SONAR_EXCLUSIONS.join(",");
+}
+const TS_TRANSFORM = String.raw `^.+\.ts$`;
+/**
+ * ts-jest without a type check (`diagnostics: false`; `isolatedModules: true` comes from @starci/tsconfig, which is where
+ * ts-jest 29.4 reads it — the ts-jest option of the same name is deprecated): types are checked once, by `typecheck` / `typecheck:tests`, never per test file.
+ * `npm run test:e2e` (and `test:integration`, `test:contract`) runs `npm run typecheck:tests` first so nobody runs a world spec on code that
+ * does not type-check.
+ */
+function transform(tsconfig) {
+    return { [TS_TRANSFORM]: ["ts-jest", { tsconfig, diagnostics: false }], ...esmDependencyTransform() };
+}
+/**
+ * The runtime dependencies of a back end that ship ECMAScript modules only: jest's CommonJS runtime cannot load them, so their
+ * files are compiled to CommonJS like the repository's own (ts-jest with `allowJs`) instead of being skipped as node_modules.
+ * `jose` is the Supabase access-token verifier of every lite back end (be.integrations.supabase); a lite app keeps full's unit
+ * run (ruling:R212/case-1, amended by ruling:R212/case-4), so a spec that imports its guard must load it.
+ */
+const ESM_ONLY_DEPENDENCIES = Object.freeze(["jose"]);
+const ESM_DEPENDENCY_TRANSFORM = String.raw `^.+[\\/]node_modules[\\/](?:${ESM_ONLY_DEPENDENCIES.join("|")})[\\/].+\.js$`;
+function esmDependencyTransform() {
+    return { [ESM_DEPENDENCY_TRANSFORM]: ["ts-jest", { tsconfig: { allowJs: true, module: "commonjs", target: "es2022", esModuleInterop: true }, diagnostics: false }] };
+}
+/** node_modules stay untransformed except the ESM-only dependencies above. */
+const TRANSFORM_IGNORE_PATTERNS = Object.freeze([String.raw `[\\/]node_modules[\\/](?!(?:${ESM_ONLY_DEPENDENCIES.join("|")})[\\/])`]);
+/** The unit project transpiles each file independently; helpers stay in tslib, source maps distinguish generated metadata, and type checks run separately. */
+const UNIT_COMPILER_OPTIONS = Object.freeze({ isolatedModules: true, importHelpers: true, sourceMap: true });
+exports.UNIT_COMPILER_OPTIONS = UNIT_COMPILER_OPTIONS;
+/** Generated constructor metadata keeps its runtime guards, mapped to a generated-metadata coverage anchor instead of source parameters. */
+function unitTransform() {
+    const unitMetadata = require.resolve("./unit-metadata.js");
+    return {
+        [TS_TRANSFORM]: [unitMetadata, { tsconfig: { ...UNIT_COMPILER_OPTIONS }, diagnostics: false, astTransformers: { after: [unitMetadata] } }],
+        ...esmDependencyTransform(),
+    };
+}
+/**
+ * The path aliases of a StarCi back end: the same three `paths` the managed `tsconfig.json` declares, so jest resolves what
+ * `tsc` resolves. They are part of the preset, not an option: a repository has no other alias.
+ */
+const MODULE_NAME_MAPPER = Object.freeze({
+    "^@features/(.*)$": "<rootDir>/src/features/$1",
+    "^@modules/(.*)$": "<rootDir>/src/modules/$1",
+    "^@tests/(.*)$": "<rootDir>/src/tests/$1",
+});
+exports.MODULE_NAME_MAPPER = MODULE_NAME_MAPPER;
+/** The test folders under `src/tests/` that a project other than `unit` owns (owner test layout 2026-09-30). */
+const TEST_KIND_FOLDERS = Object.freeze(["world", "integration", "e2e", "contract"]);
+exports.TEST_KIND_FOLDERS = TEST_KIND_FOLDERS;
+const underTests = (folder) => String.raw `[\\/]src[\\/]tests[\\/]` + folder + String.raw `[\\/]`;
+/**
+ * The whole jest config of a Nest repository: projects `unit` (colocated `<name>.spec.ts`), `integration`
+ * (`src/tests/integration/<capability>/<name>.integration-spec.ts`), `e2e` (`src/tests/e2e/<area>/<name>.e2e-spec.ts`) and
+ * `contract` (`src/tests/contract/<provider>/<name>.contract-spec.ts`). It takes ONE option, the coverage scope: the repository's `jest.config.js` is a managed file
+ * (R05), rendered by `starci app sync` as `module.exports = require("@starci/jest-preset").starciJestConfig({ coverage: { roots, roles, excludes } })`, the scope derived from the slot manifest.
+ *
+ * The managed scripts select one project each (`test` = unit, `test:integration`, `test:e2e`, `test:contract`); the
+ * contract project is never part of `test` or `test:e2e`, and a contract spec skips itself without sandbox config. The
+ * test tree compiles against `src/tests/tsconfig.json`, the nearest config of every file under `src/tests/`. The
+ * integration, e2e and contract projects share the world's `global-setup.ts`/`global-teardown.ts` (`src/tests/world/`) and
+ * run their spec files up to `min(--maxWorkers, slots)` at once, each in a worker process of its own bound to one data slot
+ * of the test world (`world-runner.js`; a slot's data is reset when a file boots, so no two files ever share a slot). A declared lite app instead runs its existing integration and contract specs without a world, on jest's stock runner. The unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * Coverage is collected from the logic roles of the measured roots only (`coverage` option), with a per-file threshold of 100 on lines, branches, functions and
+ * statements: the `test` script runs the unit project with `--coverage`, fails below it and writes `coverage/lcov.info` for Sonar. It uses v8: istanbul instruments the helpers TypeScript emits (`__decorate`, `__param`, `__awaiter`, interop wrappers)
+ * as thousands of branches no spec can cover, while v8 measures the real source.
+ */
+/** The runner of the integration, e2e and contract projects (`world-runner.js`): every spec file in a worker process of its own. */
+const WORLD_RUNNER = require.resolve("./world-runner.js");
+exports.WORLD_RUNNER = WORLD_RUNNER;
+/** True when the repository at `root` has the test world's global setup (`src/tests/world/global-setup.ts`). */
+function hasTestWorld(root) {
+    return (0, node_fs_1.existsSync)((0, node_path_1.join)(root, "src", "tests", "world", "global-setup.ts"));
+}
+/** The managed config runs in `be/`, one level below the app's edition declaration. */
+function isLiteApp(root) {
+    try {
+        const file = (0, node_path_1.join)(root, "..", "hfs.json");
+        const declaration = JSON.parse((0, node_fs_1.readFileSync)(file, "utf8"));
+        return typeof declaration === "object" && declaration !== null && "edition" in declaration && declaration.edition === "lite";
+    }
+    catch {
+        return false;
+    }
+}
+/** Every alternative a `{a,b}` pattern spells, braces expanded left to right. */
+function braceVariants(value) {
+    const match = /{([^{}]+)}/.exec(value);
+    return match ? (match[1] ?? "").split(",").flatMap((part) => braceVariants(`${value.slice(0, match.index)}${part}${value.slice(match.index + match[0].length)}`)) : [value];
+}
+/** The anchored RegExp of one brace-free glob over a posix path: `**` spans directories, `*` and `?` stay inside a segment. */
+function globRegExp(glob) {
+    let source = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob.charAt(i);
+        if (c === "*" && glob.charAt(i + 1) === "*") {
+            i += 1;
+            if (glob.charAt(i + 1) === "/") {
+                i += 1;
+                source += "(?:.*/)?";
+            }
+            else
+                source += ".*";
+        }
+        else if (c === "*")
+            source += "[^/]*";
+        else if (c === "?")
+            source += "[^/]";
+        else
+            source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c;
+    }
+    return new RegExp(`^${source}$`);
+}
+/**
+ * True when the repository at `root` holds a file the coverage glob matches: jest refuses a threshold key that matches no covered file,
+ * and a back end may have no file of a measured root yet (no projection, no integration), so a root without files gets no key (its files,
+ * once added, are measured and held at 100 like every other).
+ */
+function hasCoverageSubjects(root, glob) {
+    const base = glob.slice(0, Math.max(0, glob.search(/[*?{]/))).replace(/[^/]*$/, "");
+    const patterns = braceVariants(glob).map(globRegExp);
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = (0, node_fs_1.readdirSync)((0, node_path_1.join)(root, dir), { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        return entries.some((entry) => {
+            const rel = `${dir}${entry.name}`;
+            if (entry.isDirectory())
+                return !["node_modules", "dist", "coverage"].includes(entry.name) && walk(`${rel}/`);
+            return patterns.some((pattern) => pattern.test(rel));
+        });
+    };
+    return walk(base);
+}
+const isList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0);
+/** A property of an unknown value, `undefined` when the value is not an object that has it. */
+const fieldOf = (value, name) => (typeof value === "object" && value !== null && name in value ? Reflect.get(value, name) : undefined);
+/** The scope `{ roots, roles, excludes }` of an options object, or a refusal: the scope is rendered by `starci app sync`, never defaulted. */
+function coverageOf(options) {
+    const coverage = fieldOf(options, "coverage");
+    const roots = fieldOf(coverage, "roots");
+    const roles = fieldOf(coverage, "roles");
+    const excludes = fieldOf(coverage, "excludes");
+    if (!coverage || !isList(roots) || !isList(roles) || !roles.length || !isList(excludes)) {
+        throw new Error("starciJestConfig({ coverage: { roots, roles, excludes } }) needs the coverage scope starci app sync renders from the slot manifest; run \"npx starci app sync --write\"");
+    }
+    return { roots, roles, excludes };
+}
+/** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes the coverage scope the managed repository config renders; without it it refuses. */
+function starciJestConfig(options) {
+    const coverage = coverageOf(options);
+    const root = process.cwd();
+    const world = hasTestWorld(root);
+    const shared = {
+        preset: "ts-jest",
+        testEnvironment: "node",
+        rootDir: ".",
+        roots: ["<rootDir>/src", "<rootDir>/apps"],
+        moduleNameMapper: { ...MODULE_NAME_MAPPER },
+        transformIgnorePatterns: [...TRANSFORM_IGNORE_PATTERNS],
+    };
+    const suite = (displayName, suffix) => ({
+        ...shared,
+        transform: transform("src/tests/tsconfig.json"),
+        displayName,
+        // A glob without the root's absolute path: jest's roots (src, apps) already bound the search, and a root path that holds a dot-named folder (a checkout under `.claude`) turns its backslash separator into a glob escape on Windows, so a path-prefixed pattern would match no file.
+        testMatch: [`**/src/tests/${displayName}/**/*.${suffix}.ts`],
+        // Full's world gives every spec file its own process and data slot; lite needs neither its runner nor its hooks.
+        ...(world ? {
+            runner: WORLD_RUNNER,
+            globalSetup: "<rootDir>/src/tests/world/global-setup.ts",
+            globalTeardown: "<rootDir>/src/tests/world/global-teardown.ts",
+        } : {}),
+    });
+    const testProjects = world ? [suite("integration", "integration-spec"), suite("e2e", "e2e-spec"), suite("contract", "contract-spec")] : [];
+    if (!world && isLiteApp(root)) {
+        for (const name of ["integration", "contract"]) {
+            const suffix = `${name}-spec`;
+            if (hasCoverageSubjects(root, `src/tests/${name}/**/*.${suffix}.ts`))
+                testProjects.push(suite(name, suffix));
+        }
+    }
+    // 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";
+    return {
+        coverageProvider: "v8",
+        ...(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.
+            coverageThreshold: coverageThresholdOf(coverage, root),
+        }),
+        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"), {}]],
+        projects: [
+            {
+                ...shared,
+                transform: unitTransform(),
+                displayName: "unit",
+                clearMocks: true,
+                // The Outcome matchers (`toBeRefused`, `toSucceedWith`) exist in the unit project only.
+                setupFilesAfterEnv: [require.resolve("./matchers.js")],
+                testMatch: ["**/*.spec.ts"],
+                testPathIgnorePatterns: ["/node_modules/", ...TEST_KIND_FOLDERS.map(underTests)],
+            },
+            // Jest validates every project's world hooks even under --selectProjects unit. An unfinished full scaffold
+            // keeps only unit; a lite app's present integration/contract lanes need no test world.
+            ...testProjects,
+        ],
+    };
+}

package/dist/lcov.d.ts

@@ -0,0 +1,16 @@
+import type { Context, ReportNode } from "istanbul-lib-report";
+/** The lcov report of istanbul-reports: built with `{ file, projectRoot }`, driven per file by `onDetail` and as a whole by `execute`. */
+interface LcovReportBase {
+    onDetail(node: ReportNode, context: Context): void;
+    execute(context: Context): void;
+}
+type LcovReportConstructor = new (options: {
+    file: string;
+    projectRoot: string;
+}) => LcovReportBase;
+declare const LcovReport: LcovReportConstructor;
+/** LCOV identifies functions by name; append their stable coverage id so same-named callbacks retain separate counts. */
+declare class StarciLcovReport extends LcovReport {
+    onDetail(node: ReportNode, context: Context): void;
+}
+export = StarciLcovReport;

package/dist/lcov.js

@@ -0,0 +1,25 @@
+"use strict";
+const node_module_1 = require("node:module");
+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 reports = fromReporters("istanbul-reports");
+const LcovReport = reports.create("lcov").constructor;
+const METADATA_SOURCE = require.resolve("./unit-metadata.generated.js");
+/** LCOV identifies functions by name; append their stable coverage id so same-named callbacks retain separate counts. */
+class StarciLcovReport extends LcovReport {
+    onDetail(node, context) {
+        if (node.getFileCoverage().path === METADATA_SOURCE)
+            return;
+        const entries = Object.entries(node.getFileCoverage().fnMap);
+        const originals = entries.map(([, meta]) => ({ meta, name: meta.name }));
+        try {
+            entries.forEach(([id, meta]) => { meta.name = `${meta.name}#${id}`; });
+            super.onDetail(node, context);
+        }
+        finally {
+            originals.forEach(({ meta, name }) => { meta.name = name; });
+        }
+    }
+}
+module.exports = StarciLcovReport;

package/dist/lock.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `fakeLock(clock)` -- a behavioural in-memory double of a lease (cross-replica lock with fencing).
+ *
+ * `acquire({ name, holder, ttlMs, at? })` grants `{ name, holder, fence }` when nobody holds the name (or the previous
+ * ttl ran out on the clock) and answers `null` on contention; the fence grows with every grant of one name.
+ * `release({ grant })` lets go only when the grant is still current. A holder acquiring its own live lease renews it.
+ * Inspection: `isHeld(name)`, `holderOf(name)`, `fenceOf(name)`. Expiry is driven by the `FakeClock`; a request may carry
+ * its own `at`, which wins.
+ */
+/** What a caller asks for when it wants a named lease. */
+export interface FakeLockAcquire {
+    readonly name: string;
+    readonly holder: string;
+    readonly ttlMs: number;
+    /** The instant of the request; defaults to the clock of the double. */
+    readonly at?: Date;
+}
+/** A granted lease. */
+export interface FakeLockGrant {
+    readonly name: string;
+    readonly holder: string;
+    readonly fence: number;
+}
+/** A behavioural in-memory lease: acquire, contention, release, ttl expiry on the clock, growing fence. */
+export interface FakeLock {
+    acquire(params: FakeLockAcquire): Promise<FakeLockGrant | null>;
+    release(params: {
+        readonly grant: FakeLockGrant;
+    }): Promise<void>;
+    isHeld(name: string): boolean;
+    holderOf(name: string): string | null;
+    fenceOf(name: string): number | null;
+}
+/** The lock double; expiry follows `clock`, so `clock.advance(ms)` frees a lease whose ttl ran out. */
+export declare function fakeLock(clock?: {
+    now(): Date;
+}): FakeLock;

package/dist/lock.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * `fakeLock(clock)` -- a behavioural in-memory double of a lease (cross-replica lock with fencing).
+ *
+ * `acquire({ name, holder, ttlMs, at? })` grants `{ name, holder, fence }` when nobody holds the name (or the previous
+ * ttl ran out on the clock) and answers `null` on contention; the fence grows with every grant of one name.
+ * `release({ grant })` lets go only when the grant is still current. A holder acquiring its own live lease renews it.
+ * Inspection: `isHeld(name)`, `holderOf(name)`, `fenceOf(name)`. Expiry is driven by the `FakeClock`; a request may carry
+ * its own `at`, which wins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fakeLock = fakeLock;
+/** The lock double; expiry follows `clock`, so `clock.advance(ms)` frees a lease whose ttl ran out. */
+function fakeLock(clock) {
+    const state = new Map();
+    const fences = new Map();
+    const nowOf = (params) => {
+        const at = params.at ?? clock?.now();
+        if (at === undefined)
+            throw new Error("fakeLock: pass the FakeClock, fakeLock(clock), or an `at` on each acquire");
+        return at.getTime();
+    };
+    const liveHold = (name) => {
+        const hold = state.get(name);
+        if (hold === undefined)
+            return undefined;
+        if (clock !== undefined && clock.now().getTime() >= hold.expiresAt) {
+            state.delete(name);
+            return undefined;
+        }
+        return hold;
+    };
+    return {
+        async acquire(params) {
+            const at = nowOf(params);
+            const held = state.get(params.name);
+            const alive = held !== undefined && at < held.expiresAt;
+            if (alive && held.holder !== params.holder)
+                return null;
+            const fence = alive ? held.fence : (fences.get(params.name) ?? 0) + 1;
+            fences.set(params.name, fence);
+            state.set(params.name, { holder: params.holder, fence, expiresAt: at + params.ttlMs });
+            return { name: params.name, holder: params.holder, fence };
+        },
+        async release({ grant }) {
+            const held = state.get(grant.name);
+            if (held !== undefined && held.fence === grant.fence && held.holder === grant.holder)
+                state.delete(grant.name);
+        },
+        /** Whether a live lease exists for `name`. */
+        isHeld: (name) => liveHold(name) !== undefined,
+        /** The holder of the live lease, or null. */
+        holderOf: (name) => liveHold(name)?.holder ?? null,
+        /** The fence of the latest grant of `name`, or null when it was never granted. */
+        fenceOf: (name) => fences.get(name) ?? null,
+    };
+}

package/dist/matchers.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="jest" preserve="true" />
+/**
+ * Outcome matchers, registered by the `unit` project's `setupFilesAfterEnv` (nowhere else).
+ *
+ * They match the platform `Outcome<V, C>` structurally: `{ kind: "ok", value }` or `{ kind: "refused", code, params? }`.
+ * `expect(outcome).toBeRefused("STOCK_EXHAUSTED")` (or `{ code, params }`) and `expect(outcome).toSucceedWith(value)`.
+ */
+/** The refusal a matcher expects: a capability code, or a code with the parameters of its display text. */
+export type RefusalReason = string | {
+    readonly code: string;
+    readonly params?: Record<string, unknown>;
+};
+declare global {
+    namespace jest {
+        interface Matchers<R> {
+            /** The received `Outcome` is `{ kind: "refused" }` with this code (and these params, when given). */
+            toBeRefused(reason: RefusalReason): R;
+            /** The received `Outcome` is `{ kind: "ok" }` whose value equals `value` (recursive equality). */
+            toSucceedWith(value: unknown): R;
+        }
+    }
+}
+/** The matchers registered on `expect`. */
+export declare const matchers: {
+    toBeRefused(this: jest.MatcherContext, received: unknown, reason: RefusalReason): jest.CustomMatcherResult;
+    toSucceedWith(this: jest.MatcherContext, received: unknown, value: unknown): jest.CustomMatcherResult;
+};

package/dist/matchers.js

@@ -0,0 +1,36 @@
+"use strict";
+/// <reference types="jest" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchers = void 0;
+const isOutcome = (received) => typeof received === "object" && received !== null && "kind" in received && (received.kind === "ok" || received.kind === "refused");
+const notOutcome = (utils, received) => `expected an Outcome ({ kind: "ok" | "refused" }), received ${utils.printReceived(received)}`;
+/** The matchers registered on `expect`. */
+exports.matchers = {
+    toBeRefused(received, reason) {
+        if (!isOutcome(received))
+            return { pass: false, message: () => notOutcome(this.utils, received) };
+        const expected = typeof reason === "string" ? { code: reason } : reason;
+        const pass = received.kind === "refused" &&
+            received.code === expected.code &&
+            (!("params" in expected) || this.equals(received.params, expected.params));
+        return {
+            pass,
+            message: () => pass
+                ? `expected the outcome not to be refused with ${this.utils.printExpected(expected)}`
+                : `expected the outcome to be refused with ${this.utils.printExpected(expected)}, received ${this.utils.printReceived(received)}`,
+        };
+    },
+    toSucceedWith(received, value) {
+        if (!isOutcome(received))
+            return { pass: false, message: () => notOutcome(this.utils, received) };
+        const pass = received.kind === "ok" && this.equals(received.value, value);
+        return {
+            pass,
+            message: () => pass
+                ? `expected the outcome not to succeed with ${this.utils.printExpected(value)}`
+                : `expected the outcome to succeed with ${this.utils.printExpected(value)}, received ${this.utils.printReceived(received)}`,
+        };
+    },
+};
+if (typeof expect !== "undefined" && typeof expect.extend === "function")
+    expect.extend(exports.matchers);

package/dist/merge.d.ts

@@ -0,0 +1,14 @@
+/** Every coverage-final.json at or below `target` (a file or a directory), sorted. */
+declare function coverageFilesUnder(target: string): string[];
+/**
+ * Merge the shard reports `inputs` (coverage-final.json files or directories holding them) and write `<outDir>/lcov.info` and `<outDir>/coverage-final.json`.
+ * Returns { reports, files }; throws when no report is found (an empty merge would read as "nothing to measure").
+ */
+declare function mergeCoverage({ inputs, outDir }: {
+    inputs: string[];
+    outDir: string;
+}): {
+    reports: number;
+    files: number;
+};
+export { mergeCoverage, coverageFilesUnder };

package/dist/merge.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeCoverage = mergeCoverage;
+exports.coverageFilesUnder = coverageFilesUnder;
+// merge.ts - the coverage of a sharded unit run merged into the one report the coverage proof, Codecov and Sonar read (`starci app coverage merge`).
+// Each shard runs with STARCI_COVERAGE_SHARD=1 (starciJestConfig): it measures ONLY the files its tests load (no collectCoverageFrom all-files
+// instrumentation, whose fallback transform gives an unloaded file another function and branch set) and writes istanbul JSON (coverage-final.json).
+// The maps of one file come from the same v8 transform in every shard; istanbul-lib-coverage merges them by source location (FileCoverage.merge), and the
+// merged map is written as lcov through this preset's own lcov reporter (lcov.ts: stable function ids, the generated metadata source left out), exactly
+// as an unsharded run writes it. A measured file no shard loaded is absent from the merged map: the coverage proof refuses it (no lcov record, 0%).
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+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");
+/** The folder of a directory entry: `parentPath`, which Node before 20.12 calls `path`. */
+function parentOf(entry) {
+    const legacy = Reflect.get(entry, "path");
+    return entry.parentPath ?? (typeof legacy === "string" ? legacy : "");
+}
+/** Every coverage-final.json at or below `target` (a file or a directory), sorted. */
+function coverageFilesUnder(target) {
+    if (!node_fs_1.default.statSync(target).isDirectory())
+        return [target];
+    return node_fs_1.default.readdirSync(target, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name === "coverage-final.json")
+        .map((entry) => node_path_1.default.join(parentOf(entry), entry.name))
+        .sort();
+}
+/**
+ * Merge the shard reports `inputs` (coverage-final.json files or directories holding them) and write `<outDir>/lcov.info` and `<outDir>/coverage-final.json`.
+ * Returns { reports, files }; throws when no report is found (an empty merge would read as "nothing to measure").
+ */
+function mergeCoverage({ inputs, outDir }) {
+    const reports = inputs.flatMap((input) => coverageFilesUnder(input));
+    if (!reports.length)
+        throw new Error(`no coverage-final.json under ${inputs.join(", ")}: the unit shards wrote none (run them with STARCI_COVERAGE_SHARD=1)`);
+    const map = libCoverage.createCoverageMap({});
+    for (const report of reports) {
+        const data = JSON.parse(node_fs_1.default.readFileSync(report, "utf8"));
+        map.merge(data);
+    }
+    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: process.cwd() }).execute(context);
+    return { reports: reports.length, files: map.files().length };
+}

package/dist/mock.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="jest" preserve="true" />
+/**
+ * `mock<T>()` -- a typed test double that replaces the `{ ... } as unknown as T` cast.
+ *
+ * Every property read yields one stable `jest.fn()` (created on first read), so `mock<Repo>().find` is
+ * already a mock function, `expect(m.find).toHaveBeenCalledWith(...)` works, and `m.find.mockResolvedValue(x)`
+ * type-checks against `Repo["find"]`. Values passed in `overrides` win over the generated functions and may be
+ * partial: the return type is still `T`.
+ *
+ * `createMock` takes the function factory as an argument (called with the property name) so the helper has no hard
+ * dependency on a global `jest`; `mock` binds it to `jest.fn`.
+ */
+/** Function members become jest mocks typed against the real signature; everything else stays as declared. */
+export type MockOf<T> = T & {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? jest.Mock<R, A> & T[K] : T[K];
+};
+/** The factory behind `mock`, for callers that bring their own function factory (used by the package spec). */
+export declare function createMock(makeFn: (property: string) => unknown): <T extends object>(overrides?: Partial<T>) => MockOf<T>;
+export declare function jestFn(implementation?: (...args: never[]) => unknown): unknown;
+/** A typed test double for `T`. `overrides` may be partial; the result is usable wherever a `T` is required. */
+export declare const mock: <T extends object>(overrides?: Partial<T>) => MockOf<T>;

package/dist/mock.js

@@ -0,0 +1,52 @@
+"use strict";
+/// <reference types="jest" preserve="true" />
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mock = void 0;
+exports.createMock = createMock;
+exports.jestFn = jestFn;
+// Probed by promise resolution, jest matchers and serializers: they must read as absent, not as a mock function.
+const ABSENT = new Set(["then", "asymmetricMatch", "$$typeof", "nodeType", "tagName", "toJSON"]);
+/** The factory behind `mock`, for callers that bring their own function factory (used by the package spec). */
+function createMock(makeFn) {
+    function mock(overrides) {
+        const own = new Map();
+        const store = overrides ? { ...overrides } : {};
+        return new Proxy(store, {
+            get(target, property, receiver) {
+                if (Object.hasOwn(target, property))
+                    return Reflect.get(target, property, receiver);
+                if (typeof property === "symbol" || property in Object.prototype)
+                    return Reflect.get(target, property, receiver);
+                if (ABSENT.has(property))
+                    return undefined;
+                if (!own.has(property))
+                    own.set(property, makeFn(property));
+                return own.get(property);
+            },
+            set(target, property, value) {
+                own.delete(property);
+                target[property] = value;
+                return true;
+            },
+            has(target, property) {
+                return Object.hasOwn(target, property) || own.has(property);
+            },
+        });
+    }
+    return mock;
+}
+// jest-runtime hands every module it loads, this one included, a module-scoped `jest` object; it is not a property
+// of globalThis, so it is read as a free identifier. @jest/globals is the fallback for a runner that does not.
+function jestFn(implementation) {
+    if (typeof jest !== "undefined" && typeof jest.fn === "function")
+        return jest.fn(implementation);
+    try {
+        const globals = require("@jest/globals");
+        return globals.jest.fn(implementation);
+    }
+    catch {
+        throw new Error("@starci/jest-preset mock<T>() needs the jest runtime; call it from a jest test");
+    }
+}
+/** A typed test double for `T`. `overrides` may be partial; the result is usable wherever a `T` is required. */
+exports.mock = createMock(() => jestFn());