@starci/jest-preset 2.3.6 → 2.4.0

package/inbox.d.ts

@@ -1,58 +0,0 @@
-/** One claim or release of a delivery. */
-export interface InboxEntry {
-  readonly source: string
-  readonly eventId: string
-}
-/** The inbox operations `failNext` can make reject. */
-export type InboxOperation = "claim" | "release" | "runClient" | "sweepClients"
-
-/** The client operation namespace, exact key and JSON request whose outcome the inbox stores. */
-export interface InboxClientOperation {
-  readonly principalId: string
-  readonly operation: string
-  readonly idempotencyKey: string
-  readonly request: unknown
-}
-
-/** A client claim with the manager passed by its caller. */
-export interface InboxClientEntry extends InboxEntry {
-  readonly tx: unknown
-  readonly inTransaction: boolean
-}
-
-/** One retention sweep with the cutoff instant and manager passed by its caller. */
-export interface InboxSweep {
-  readonly cutoff: Date
-  readonly tx: unknown
-  readonly inTransaction: boolean
-}
-
-/** An `Inbox` double with the behaviour of the real claim. */
-export interface FakeInbox {
-  /** True for the first claim of a (source, eventId) pair, false for every later one until it is released. */
-  claim(source: string, eventId: string): Promise<boolean>
-  /** Gives an ordinary delivery claim back while preserving client receipts and their outcomes. */
-  release(source: string, eventId: string): Promise<void>
-  /** Runs once for the client namespace and key, replays the JSON outcome and refuses a different body. */
-  runClient<T>(request: InboxClientOperation, tx: unknown, effect: () => Promise<T>): Promise<T>
-  /** Deletes at most one batch of completed client claims older than the cutoff. */
-  sweepClients(cutoff: Date, tx: unknown): Promise<number>
-  /** Marks a pair as already claimed (a redelivery). */
-  seen(source: string, eventId: string): void
-  /** Makes the next call of `operation` reject with `error`, once. */
-  failNext(operation: InboxOperation, error: Error): void
-  /** Every claim, in order, duplicates included. */
-  readonly claims: ReadonlyArray<InboxEntry>
-  /** The pairs held now: claimed and not released. */
-  readonly claimed: ReadonlyArray<InboxEntry>
-  /** Every release, in order. */
-  readonly released: ReadonlyArray<InboxEntry>
-  /** Every client claim with its manager; this double records transaction ownership, not database commit semantics. */
-  readonly clientEntries: ReadonlyArray<InboxClientEntry>
-  /** Every sweep attempt with its cutoff and transaction, including a scripted failure. */
-  readonly sweeps: ReadonlyArray<InboxSweep>
-  clear(): void
-}
-
-/** The inbox double. Pass a driven clock to test retention; omitted clocks stamp client claims at the Unix epoch. */
-export declare function fakeInbox(clock?: { now(): Date }): FakeInbox

package/index.cjs

@@ -1,295 +0,0 @@
-"use strict"
-
-const { mock, createMock } = require("./mock.cjs")
-const { mockEntityManager, fakeTransaction } = require("./entity-manager.cjs")
-const { FakeClock } = require("./clock.cjs")
-const { fakeCache } = require("./cache.cjs")
-const { fakeLock } = require("./lock.cjs")
-const { recordingEventBus } = require("./event-bus.cjs")
-const { recordingQueueOutbox } = require("./queue.cjs")
-const { fakeInbox } = require("./inbox.cjs")
-const { builder } = require("./builders.cjs")
-const { fakeIds, FakeIds } = require("./ids.cjs")
-
-/**
- * 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/**"]
-/** The four metrics, each held at 100 per file. */
-const COVERAGE_THRESHOLD = Object.freeze({ lines: 100, branches: 100, functions: 100, statements: 100 })
-
-/** 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.cjs, a
- * require-free module @starci/hfs also ships byte for byte (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs), so `starci app scaffold`
- * renders the same exclusions before any app dependency is installed.
- */
-const SONAR_EXCLUSIONS = require("./sonar-exclusions.cjs")
-
-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 })
-
-/** Generated constructor metadata keeps its runtime guards, mapped to a generated-metadata coverage anchor instead of source parameters. */
-function unitTransform() {
-  const transforms = transform({ ...UNIT_COMPILER_OPTIONS })
-  transforms[TS_TRANSFORM][0] = require.resolve("./unit-metadata.cjs")
-  transforms[TS_TRANSFORM][1].astTransformers = { after: [require.resolve("./unit-metadata.cjs")] }
-  return transforms
-}
-
-/**
- * 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",
-})
-
-/** 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"])
-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.cjs`; 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: one fresh worker process per spec file. */
-const WORLD_RUNNER = require.resolve("./world-runner.cjs")
-
-/** True when the repository at `root` has the test world's global setup (`src/tests/world/global-setup.ts`). */
-function hasTestWorld(root) {
-  return require("node:fs").existsSync(require("node:path").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 = require("node:path").join(root, "..", "hfs.json")
-    return JSON.parse(require("node:fs").readFileSync(file, "utf8")).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[i]
-    if (c === "*" && glob[i + 1] === "*") {
-      i += 1
-      if (glob[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 fsx = require("node:fs")
-  const pathx = require("node:path")
-  const base = glob.slice(0, Math.max(0, glob.search(/[*?{]/))).replace(/[^/]*$/, "")
-  const patterns = braceVariants(glob).map(globRegExp)
-  const walk = (dir) => {
-    let entries
-    try {
-      entries = fsx.readdirSync(pathx.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)
-}
-
-/** 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 = options?.coverage
-  const list = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0)
-  if (!coverage || !list(coverage.roots) || !list(coverage.roles) || !coverage.roles.length || !list(coverage.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 coverage
-}
-
-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.cjs) 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.cjs"), {}]],
-    projects: [
-      {
-        ...shared,
-        transform: unitTransform(),
-        displayName: "unit",
-        clearMocks: true,
-        // The Outcome matchers (`toBeRefused`, `toSucceedWith`) exist in the unit project only.
-        setupFilesAfterEnv: [require.resolve("./matchers.cjs")],
-        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,
-    ],
-  }
-}
-
-module.exports = {
-  starciJestConfig,
-  TEST_KIND_FOLDERS,
-  MODULE_NAME_MAPPER,
-  mock,
-  createMock,
-  mockEntityManager,
-  fakeTransaction,
-  FakeClock,
-  fakeCache,
-  fakeLock,
-  recordingEventBus,
-  recordingQueueOutbox,
-  fakeInbox,
-  builder,
-  fakeIds,
-  FakeIds,
-  collectCoverageFrom,
-  rootGlob,
-  sonarExclusions,
-  hasCoverageSubjects,
-  COVERAGE_EXCLUDES,
-  COVERAGE_THRESHOLD,
-  UNIT_COMPILER_OPTIONS,
-  WORLD_RUNNER,
-}

package/index.d.ts

@@ -1,38 +0,0 @@
-import type { Config } from "jest"
-
-export { mock, createMock, MockOf } from "./mock"
-export { mockEntityManager, fakeTransaction, MockEntityManager, FakeTransaction, EntityClass } from "./entity-manager"
-export { fakeCache, FakeCache } from "./cache"
-export { fakeLock, FakeLock } from "./lock"
-export { recordingEventBus, RecordingEventBus } from "./event-bus"
-export { recordingQueueOutbox, RecordingQueueOutbox } from "./queue"
-export { fakeInbox, FakeInbox } from "./inbox"
-export { builder } from "./builders"
-export { FakeClock } from "./clock"
-export { fakeIds, FakeIds } from "./ids"
-export { RefusalReason } from "./matchers"
-
-/** The coverage scope `starci app sync` renders from the slot manifest: the measured roots (a directory pattern per measured slot, a placeholder folder written as a star), the logic roles measured in them and the directories inside a root that are never measured (each ending in a double star). */
-export interface StarciCoverageScope {
-  readonly roots: readonly string[]
-  readonly roles: readonly string[]
-  readonly excludes: readonly string[]
-}
-export interface StarciJestOptions {
-  readonly coverage: StarciCoverageScope
-}
-/** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes the coverage scope the managed repository config renders; without it it refuses. */
-export declare function starciJestConfig(options: StarciJestOptions): Config
-export declare const MODULE_NAME_MAPPER: Readonly<Record<string, string>>
-export declare function collectCoverageFrom(coverage: StarciCoverageScope): string[]
-/** The glob one measured root stands for: every file of a logic role below it. */
-export declare function rootGlob(root: string, roles: readonly string[]): string
-/** True when `root` holds a file the coverage `glob` matches (a threshold key that matches nothing is refused by jest). */
-export declare function hasCoverageSubjects(root: string, glob: string): boolean
-export declare function sonarExclusions(): string
-export declare const COVERAGE_EXCLUDES: string[]
-/** The compiler options the unit project overlays on the repository tsconfig so per-file 100 coverage of a decorated service is reachable. */
-export declare const UNIT_COMPILER_OPTIONS: Readonly<{ isolatedModules: true; importHelpers: true; sourceMap: true }>
-/** The runner of the integration, e2e and contract projects (`world-runner.cjs`): every spec file in a worker process of its own. */
-export declare const WORLD_RUNNER: string
-export declare const COVERAGE_THRESHOLD: Readonly<{ lines: 100; branches: 100; functions: 100; statements: 100 }>

package/lcov.cjs

@@ -1,25 +0,0 @@
-"use strict"
-
-const { createRequire } = require("node:module")
-const fromJest = createRequire(require.resolve("jest"))
-const fromCore = createRequire(fromJest.resolve("@jest/core"))
-const fromReporters = createRequire(fromCore.resolve("@jest/reporters"))
-const LcovReport = fromReporters("istanbul-reports").create("lcov").constructor
-const METADATA_SOURCE = require.resolve("./unit-metadata.generated.cjs")
-
-/** 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 names = entries.map(([, meta]) => meta.name)
-    try {
-      entries.forEach(([id, meta]) => { meta.name = `${meta.name}#${id}` })
-      super.onDetail(node, context)
-    } finally {
-      entries.forEach(([, meta], index) => { meta.name = names[index] })
-    }
-  }
-}
-
-module.exports = StarciLcovReport

package/lock.cjs

@@ -1,56 +0,0 @@
-"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.
- */
-
-/** @param {{ now(): Date }} [clock] */
-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,
-  }
-}
-
-module.exports = { fakeLock }

package/lock.d.ts

@@ -1,26 +0,0 @@
-/** 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/matchers.cjs

@@ -1,45 +0,0 @@
-"use strict"
-
-/**
- * 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)`.
- */
-
-const isOutcome = (received) => typeof received === "object" && received !== null && (received.kind === "ok" || received.kind === "refused")
-
-const notOutcome = (utils, received) => `expected an Outcome ({ kind: "ok" | "refused" }), received ${utils.printReceived(received)}`
-
-const 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(matchers)
-
-module.exports = { matchers }

package/matchers.d.ts

@@ -1,17 +0,0 @@
-/// <reference types="jest" />
-
-/** 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
-    }
-  }
-}
-
-export declare const matchers: Record<"toBeRefused" | "toSucceedWith", (this: jest.MatcherContext, received: unknown, expected: unknown) => jest.CustomMatcherResult>

package/merge.cjs

@@ -1,45 +0,0 @@
-"use strict"
-
-// merge.cjs - 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.cjs: 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 fs = require("node:fs")
-const path = require("node:path")
-const { createRequire } = require("node:module")
-
-const fromJest = createRequire(require.resolve("jest"))
-const fromCore = createRequire(fromJest.resolve("@jest/core"))
-const fromReporters = createRequire(fromCore.resolve("@jest/reporters"))
-const libCoverage = fromReporters("istanbul-lib-coverage")
-const libReport = fromReporters("istanbul-lib-report")
-const StarciLcovReport = require("./lcov.cjs")
-
-/** Every coverage-final.json at or below `target` (a file or a directory), sorted. */
-function coverageFilesUnder(target) {
-  if (!fs.statSync(target).isDirectory()) return [target]
-  return fs.readdirSync(target, { recursive: true, withFileTypes: true })
-    .filter((entry) => entry.isFile() && entry.name === "coverage-final.json")
-    .map((entry) => path.join(entry.parentPath ?? entry.path, 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) map.merge(JSON.parse(fs.readFileSync(report, "utf8")))
-  fs.mkdirSync(outDir, { recursive: true })
-  fs.writeFileSync(path.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 }
-}
-
-module.exports = { mergeCoverage, coverageFilesUnder }