@starci/jest-preset 1.1.0

package/README.md

@@ -0,0 +1,66 @@
+# @starci/jest-preset
+
+The jest config of a Nest repository, and the typed `mock<T>()` helper. Install it from the npm registry at the exact version in [`knowledge/hfs/canon-pins.yaml`](../../knowledge/hfs/canon-pins.yaml) (see [`packages/README.md`](../README.md)).
+
+```js
+// jest.config.js
+const { pathsToModuleNameMapper } = require("ts-jest")
+const { starciJestConfig } = require("@starci/jest-preset")
+const { compilerOptions } = require("./tsconfig.json")
+
+module.exports = starciJestConfig({
+    moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }),
+    e2e: { globalSetup: "<rootDir>/src/tests/e2e/setup/global-setup.js" },
+})
+```
+
+## What it sets
+
+- **Two projects**: `unit` (`**/*.spec.ts`, mocked, `clearMocks`) and `e2e` (`src/tests/e2e/**/*.e2e-spec.ts`, one worker, 120 s).
+  `src/tests/e2e/live/` is skipped unless `E2E_LIVE=1`; `test:e2e:live` is `E2E_LIVE=1 jest --selectProjects e2e src/tests/e2e/live`.
+- **ts-jest with `diagnostics: false`** in both. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it
+  there; its own option is deprecated). Types are checked once, by `typecheck` (unit specs included) and `typecheck:e2e`, and
+  `test:e2e` is `npm run typecheck:e2e && jest --selectProjects e2e`, so nobody runs e2e on code that does not type-check.
+- **Coverage that matches Sonar.** `collectCoverageFrom` is `src/**/*.ts` and `apps/**/*.ts` minus specs, e2e specs, `dist`,
+  `coverage`, `src/tests/**`, `*.d.ts` and `main.ts`: the same set Sonar counts. `sonarExclusions()` and
+  `sonarCoverageExclusions()` render the two `sonar-project.properties` values from the same lists, so the denominators
+  cannot drift. Reports are `coverage/lcov.info` (Codecov and Sonar read the one file) and a text summary. Thresholds are not
+  set here; Codecov's project and patch targets own the gate.
+
+## `mock<T>()`
+
+Replaces `{ ... } as unknown as T`.
+
+```ts
+import { mock } from "@starci/jest-preset"
+
+const repo = mock<UserRepository>({ name: "users" })       // overrides may be partial
+repo.find.mockResolvedValue({ id: "a" })                   // typed against UserRepository["find"]
+const service = new UserService(repo)                       // assignable wherever a UserRepository is required
+expect(repo.find).toHaveBeenCalledWith("a")
+```
+
+Every property read yields one stable `jest.fn()`, created on first read. The double is not thenable, so returning it from
+an async function does not hang; `then`, `toJSON` and Symbol keys read as absent. A value you pass in `overrides` wins. Wrong
+stubs (`repo.find.mockResolvedValue(1)`) and members the type does not have are compile errors. Fixtures use it instead of
+`as never` and `as unknown as`.
+
+## `FakeClock`
+
+The test double for the injected `Clock` port (`platform/clock`). Business code asks `clock.now()` instead of reading
+`Date.now()` or `new Date()` ambiently (`no-ambient-clock`, `@starci/eslint-canon-be` R79 `BE_AMBIENT_CLOCK`); a spec
+drives time explicitly instead of sleeping for real or racing the wall clock.
+
+```ts
+import { FakeClock } from "@starci/jest-preset/clock"
+
+const clock = new FakeClock("2026-01-01T00:00:00.000Z")   // starts at a chosen instant; no argument starts at real now
+const service = new PlanService(clock)
+
+clock.advance(60_000)          // move the clock forward (or back, with a negative value) without a real sleep
+clock.set("2026-06-15T00:00:00.000Z")   // jump to a chosen instant, e.g. to drive a scheduled job
+expect(clock.now().toISOString()).toBe("2026-06-15T00:00:00.000Z")
+```
+
+`FakeClock` satisfies the `Clock` port structurally (`{ now(): Date }`); no cast is needed to inject it in place of the
+real clock.

package/clock.cjs

@@ -0,0 +1,34 @@
+"use strict"
+
+/**
+ * `FakeClock` -- the test double for the injected `Clock` port (`platform/clock`).
+ *
+ * Business code asks its `Clock` port for the time (`clock.now()`) instead of reading `Date.now()` or
+ * `new Date()` ambiently (`no-ambient-clock`, R79). A spec then drives time explicitly: it starts the
+ * clock at a chosen instant, advances it by a duration, or sets it to a new instant, all without a real
+ * sleep and without a race against the wall clock.
+ */
+
+class FakeClock {
+  /** @param {Date | number | string} [at] - The instant the clock starts at; defaults to now, once, at construction. */
+  constructor(at) {
+    this._now = at === undefined ? new Date() : new Date(at)
+  }
+
+  /** The current instant, matching the `Clock` port's `now(): Date`. */
+  now() {
+    return new Date(this._now.getTime())
+  }
+
+  /** Moves the clock to `at`. */
+  set(at) {
+    this._now = new Date(at)
+  }
+
+  /** Moves the clock forward by `ms` milliseconds (negative moves it back). */
+  advance(ms) {
+    this._now = new Date(this._now.getTime() + ms)
+  }
+}
+
+module.exports = { FakeClock }

package/clock.d.ts

@@ -0,0 +1,13 @@
+/** The test double for the injected `Clock` port: `{ now(): Date }`, plus spec-only time control. */
+export declare class FakeClock {
+  constructor(at?: Date | number | string)
+
+  /** The current instant. Matches the `Clock` port's `now(): Date`, so `FakeClock` satisfies it structurally. */
+  now(): Date
+
+  /** Moves the clock to `at`. */
+  set(at: Date | number | string): void
+
+  /** Moves the clock forward by `ms` milliseconds (negative moves it back). */
+  advance(ms: number): void
+}

package/index.cjs

@@ -0,0 +1,100 @@
+"use strict"
+
+const { mock, createMock } = require("./mock.cjs")
+
+/**
+ * What Sonar counts as production code, expressed once. `sonarCoverageExclusions` renders the same list for
+ * `sonar.coverage.exclusions`, so the jest denominator and the Sonar denominator cannot drift.
+ *
+ * Sonar side (canon sonar-project.properties): sources = src,apps; exclusions = specs, e2e specs, dist, coverage;
+ * coverage.exclusions = src/tests/**, e2e specs, entrypoints and declaration files.
+ */
+const COVERAGE_SOURCES = ["src/**/*.ts", "apps/**/*.ts"]
+/** Sonar `sonar.exclusions`: not analysed at all, so neither counted nor covered. */
+const SONAR_EXCLUSIONS = ["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]
+/** Sonar `sonar.coverage.exclusions`: analysed, but outside the coverage denominator. */
+const COVERAGE_ONLY_EXCLUSIONS = ["src/tests/**", "**/*.d.ts", "**/main.ts"]
+const COVERAGE_EXCLUDES = [...SONAR_EXCLUSIONS, ...COVERAGE_ONLY_EXCLUSIONS]
+
+function collectCoverageFrom() {
+  return [...COVERAGE_SOURCES, ...COVERAGE_EXCLUDES.map((glob) => `!${glob}`)]
+}
+
+/** The `sonar.coverage.exclusions` value that matches `collectCoverageFrom`; `sonar.exclusions` is `sonarExclusions()`. */
+function sonarCoverageExclusions() {
+  return COVERAGE_ONLY_EXCLUSIONS.join(",")
+}
+
+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:e2e`, never per test file.
+ * `npm run test:e2e` must be `npm run typecheck:e2e && jest --selectProjects e2e` so nobody runs e2e on code that
+ * does not type-check.
+ */
+function transform(tsconfig) {
+  return { [TS_TRANSFORM]: ["ts-jest", { tsconfig, diagnostics: false }] }
+}
+
+/**
+ * The whole jest config of a Nest repository: one `unit` project and one `e2e` project.
+ *
+ * @param {object} options
+ * @param {string} [options.tsconfig]            ts-jest tsconfig, default `tsconfig.json`
+ * @param {Record<string,string|string[]>} [options.moduleNameMapper]  path aliases for both projects
+ * @param {string[]} [options.roots]             default `<rootDir>/src`, `<rootDir>/apps`
+ * @param {object} [options.unit]                extra jest project options for unit (setupFiles, ...)
+ * @param {object} [options.e2e]                 extra jest project options for e2e (globalSetup, ...)
+ */
+function starciJestConfig(options = {}) {
+  const tsconfig = options.tsconfig ?? "tsconfig.json"
+  const shared = {
+    preset: "ts-jest",
+    testEnvironment: "node",
+    rootDir: options.rootDir ?? ".",
+    roots: options.roots ?? ["<rootDir>/src", "<rootDir>/apps"],
+    moduleNameMapper: options.moduleNameMapper ?? {},
+    transform: transform(tsconfig),
+  }
+  const live = process.env.E2E_LIVE === "1"
+  return {
+    testTimeout: 120_000,
+    collectCoverageFrom: collectCoverageFrom(),
+    coverageDirectory: "coverage",
+    coverageReporters: ["lcov", "text-summary"],
+    projects: [
+      {
+        ...shared,
+        displayName: "unit",
+        clearMocks: true,
+        testMatch: ["**/*.spec.ts"],
+        testPathIgnorePatterns: ["/node_modules/", "\.e2e-spec\.ts$", "[\\/]src[\\/]tests[\\/]e2e[\\/]"],
+        ...options.unit,
+      },
+      {
+        ...shared,
+        displayName: "e2e",
+        maxWorkers: 1,
+        testMatch: ["<rootDir>/src/tests/e2e/**/*.e2e-spec.ts"],
+        testPathIgnorePatterns: live ? ["/node_modules/"] : ["/node_modules/", "[\\/]src[\\/]tests[\\/]e2e[\\/]live[\\/]"],
+        ...options.e2e,
+      },
+    ],
+  }
+}
+
+module.exports = {
+  starciJestConfig,
+  mock,
+  createMock,
+  collectCoverageFrom,
+  sonarCoverageExclusions,
+  sonarExclusions,
+  COVERAGE_SOURCES,
+  COVERAGE_EXCLUDES,
+}

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { Config } from "jest"
+
+export { mock, createMock, MockOf } from "./mock"
+
+export interface StarciJestOptions {
+  rootDir?: string
+  tsconfig?: string
+  moduleNameMapper?: Record<string, string | string[]>
+  roots?: string[]
+  unit?: Record<string, unknown>
+  e2e?: Record<string, unknown>
+}
+
+export declare function starciJestConfig(options?: StarciJestOptions): Config
+export declare function collectCoverageFrom(): string[]
+export declare function sonarCoverageExclusions(): string
+export declare function sonarExclusions(): string
+export declare const COVERAGE_SOURCES: string[]
+export declare const COVERAGE_EXCLUDES: string[]

package/mock.cjs

@@ -0,0 +1,53 @@
+"use strict"
+
+/**
+ * `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 so the helper has no hard dependency on a global
+ * `jest`; `mock` binds it to `jest.fn`.
+ */
+
+// 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"])
+
+function createMock(makeFn) {
+  return 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())
+        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)
+      },
+    })
+  }
+}
+
+// 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() {
+  if (typeof jest !== "undefined" && typeof jest.fn === "function") return jest.fn()
+  try {
+    return require("@jest/globals").jest.fn()
+  } catch {
+    throw new Error("@starci/jest-preset mock<T>() needs the jest runtime; call it from a jest test")
+  }
+}
+
+module.exports = { mock: createMock(jestFn), createMock }

package/mock.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="jest" />
+
+/** 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]
+}
+
+/** A typed test double for `T`. `overrides` may be partial; the result is usable wherever a `T` is required. */
+export declare function mock<T extends object>(overrides?: Partial<T>): MockOf<T>
+
+/** The factory behind `mock`, for callers that bring their own function factory (used by the package spec). */
+export declare function createMock(makeFn: () => unknown): <T extends object>(overrides?: Partial<T>) => MockOf<T>

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@starci/jest-preset",
+  "version": "1.1.0",
+  "description": "The StarCi jest config for Nest repositories (unit and e2e projects, ts-jest with diagnostics off, coverage matching the Sonar denominators), the typed mock<T>() helper and the FakeClock test double for the platform/clock Clock port.",
+  "license": "UNLICENSED",
+  "private": false,
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.cjs"
+    },
+    "./mock": {
+      "types": "./mock.d.ts",
+      "default": "./mock.cjs"
+    },
+    "./clock": {
+      "types": "./clock.d.ts",
+      "default": "./clock.cjs"
+    }
+  },
+  "files": [
+    "*.cjs",
+    "*.d.ts",
+    "!*.test.*",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@types/jest": ">=29",
+    "jest": ">=29",
+    "ts-jest": ">=29"
+  },
+  "scripts": {
+    "test": "node --test \"*.test.mjs\""
+  }
+}