@starci/jest-preset 2.3.0 → 2.3.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.3.2 - 2026-10-18
+- Added: shard mode `STARCI_COVERAGE_SHARD=1` (only the loaded files are measured, no per-file threshold, istanbul JSON) and `@starci/jest-preset/merge` (istanbul-lib-coverage merge by source location, lcov through the preset reporter): the coverage job of the sharded managed CI.
+
+## 2.3.1 - 2026-10-18
+
+- Fixed: coverage excludes only compiler-emitted constructor `design:paramtypes` metadata guards injected by the preset transform; application source is never excluded, and the generated anchor is omitted from LCOV.
+- Changed: unit transforms use isolated transpilation instead of a per-file type program. A bundled ts-jest after-transformer preserves constructor metadata guards while mapping only those generated calls to a dedicated generated-metadata coverage anchor, keeping per-file 100 coverage reachable without hiding source branches. `importHelpers` stays enabled; type checking remains a separate gate. The bundled LCOV reporter gives repeated callback names unique identities so the app coverage gate can verify function totals.
+
 ## 2.3.0 - 2026-10-16
 
 - Added: a declared lite app (the edition of the `hfs.json` above its `be/`) runs its existing integration and contract specs without a test world: those projects exist only when their spec files do, and neither the world runner nor the world global setup and teardown is attached to a lite run.

package/README.md

@@ -36,11 +36,14 @@ and the exclusions. A repository has no other jest setting to tune.
   `{ lines: 100, branches: 100, functions: 100, statements: 100 }` on each of those globs — a glob key applies to each file on its own, so every file of a
   `ruleParams.be.logicRoles` role inside a measured slot must reach 100 on every metric (an average never passes). The
   managed `test` script runs the unit project with `--coverage` and fails below it. Coverage is measured by v8, which counts the
-  real source. The unit project overlays `isolatedModules: false` and `importHelpers: true` on the repository tsconfig (ts-jest merges an
-  inline `tsconfig` object over the `tsconfig.json` it finds): with `isolatedModules` on, TypeScript emits an unreachable
-  `typeof Dep !== "undefined" ? Dep : Object` guard per class-typed constructor parameter, and inlined decorator helpers carry branches
-  of their own, so 100 would be unreachable. The repository lists `tslib` in its devDependencies (`UNIT_COMPILER_OPTIONS`). Reporters are `text-summary`,
-  `text` and `lcov`: the run writes `coverage/lcov.info` under the repository (be/) root.
+  real source. The unit project overlays `isolatedModules: true`, `importHelpers: true` and `sourceMap: true` on the repository tsconfig, so ts-jest
+  transpiles each file without building a type program. `unit-metadata.cjs`, a ts-jest wrapper and after-transformer, maps
+  only synthetic `typeof value === "function" ? value : Object` guards inside TypeScript's generated `__metadata("design:paramtypes", ...)` calls to the dedicated `unit-metadata.generated.cjs` coverage anchor. Their runtime guards remain unchanged, including
+  the fallback to `Object` for an undefined or non-class dependency; generated branches are not attributed to source parameters.
+  The wrapper restores that second source after ts-jest emits its map. The anchor ignores generated guards only and is omitted from LCOV. Application source calls and guards remain measured. Source maps are enabled even when the build config disables them.
+  Source conditionals, including branches on the same constructor line, still count toward per-file 100 coverage. Decorator helpers
+  come from `tslib`, which the repository lists in its devDependencies (`UNIT_COMPILER_OPTIONS`). Reporters are `text-summary`,
+  `text` and the bundled LCOV reporter (which gives same-named callbacks unique function identities): the run writes `coverage/lcov.info` under the repository (be/) root.
 - **Sonar and Codecov import that lcov, scoped to the same measured files.** `starci app sync` renders `sonar.coverage.exclusions` (the complement of the measured files: SonarQube has no coverage inclusions) and the `codecov.yml`
   status paths and components from the one derivation (`scripts/hfs/coverage-scope.mjs`), so jest, Sonar and Codecov measure the same files;
   the Sonar gate holds coverage at 100 overall, on new code and per file. `sonarExclusions()` still renders `sonar.exclusions`

package/index.cjs

@@ -72,21 +72,15 @@ function esmDependencyTransform() {
 /** 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 compiler options the UNIT project overlays on the repository tsconfig (ts-jest merges an inline `tsconfig` object over the
- * `tsconfig.json` it finds under `rootDir`). They exist so that per-file 100 coverage is reachable for a decorated service:
- *  - `isolatedModules: false`: with it on, TypeScript cannot tell whether an imported name is a class, and emits a
- *    `typeof (_a = typeof Dep !== "undefined" && Dep) === "function" ? _a : Object` guard per class-typed constructor parameter for
- *    `design:paramtypes`; the `Object` arm can never run, so the branch stays uncovered. With the full language service the
- *    metadata is emitted as plain `Dep`.
- *  - `importHelpers: true`: the decorator helpers (`__decorate`, `__param`, `__metadata`) come from `tslib`, not inlined per file
- *    with branches of their own. The repository lists `tslib` in its devDependencies.
- * Integration, e2e and contract keep the repository setting: they measure nothing.
- */
-const UNIT_COMPILER_OPTIONS = Object.freeze({ isolatedModules: false, importHelpers: true })
+/** 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() {
-  return transform({ ...UNIT_COMPILER_OPTIONS })
+  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
 }
 
 /**
@@ -229,15 +223,21 @@ function starciJestConfig(options) {
       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 {
     testTimeout: 120_000,
     coverageProvider: "v8",
-    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: Object.fromEntries(coverage.roots.map((root) => rootGlob(root, coverage.roles)).filter((glob) => hasCoverageSubjects(process.cwd(), glob)).map((glob) => [`./${glob}`, { ...COVERAGE_THRESHOLD }])),
+    ...(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: Object.fromEntries(coverage.roots.map((root) => rootGlob(root, coverage.roles)).filter((glob) => hasCoverageSubjects(process.cwd(), glob)).map((glob) => [`./${glob}`, { ...COVERAGE_THRESHOLD }])),
+    }),
     coverageDirectory: "coverage",
-    // lcov is what Sonar imports (coverage/lcov.info); text-summary and text are what the developer reads.
-    coverageReporters: ["text-summary", "text", "lcov"],
+    // 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,

package/index.d.ts

@@ -32,7 +32,7 @@ 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: false; importHelpers: true }>
+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

@@ -0,0 +1,25 @@
+"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/merge.cjs

@@ -0,0 +1,45 @@
+"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 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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(), fakeCache(), fakeLock(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "MIT",
   "private": false,
@@ -54,6 +54,9 @@
     "./builders": {
       "types": "./builders.d.ts",
       "default": "./builders.cjs"
+    },
+    "./merge": {
+      "default": "./merge.cjs"
     }
   },
   "files": [
@@ -68,11 +71,11 @@
     "access": "public"
   },
   "peerDependencies": {
+    "@jest/globals": ">=29",
     "@types/jest": ">=29",
     "jest": ">=29",
     "ts-jest": ">=29",
-    "typeorm": ">=0.3",
-    "@jest/globals": ">=29"
+    "typeorm": ">=0.3"
   },
   "scripts": {
     "test": "node --test \"*.spec.mjs\""
@@ -90,6 +93,7 @@
     "jest": "29.7.0",
     "jest-util": "29.7.0",
     "ts-jest": "29.4.12",
+    "tslib": "2.8.1",
     "typescript": "5.9.3"
   }
 }

package/unit-metadata.cjs

@@ -0,0 +1,63 @@
+"use strict"
+
+const METADATA_SOURCE = require.resolve("./unit-metadata.generated.cjs")
+const METADATA_TEXT = require("node:fs").readFileSync(METADATA_SOURCE, "utf8")
+
+/** Only synthetic conditional guards inside compiler-emitted parameter metadata map to the dedicated ignore anchor. */
+function factory(compiler) {
+  const ts = compiler.configSet.compilerModule
+  const source = ts.createSourceMapSource(METADATA_SOURCE, METADATA_TEXT)
+  return (context) => {
+    const visit = (node) => {
+      if (isGeneratedMetadata(ts, node)) {
+        const guard = (child) => {
+          if (isGeneratedGuard(ts, child)) {
+            ts.setSourceMapRange(child, { pos: METADATA_TEXT.indexOf("\n") + 1, end: METADATA_TEXT.length - 1, source })
+            ts.setEmitFlags(child, ts.getEmitFlags(child) | ts.EmitFlags.NoNestedSourceMaps)
+            return child
+          }
+          return ts.visitEachChild(child, guard, context)
+        }
+        return ts.visitEachChild(node, guard, context)
+      }
+      return ts.visitEachChild(node, visit, context)
+    }
+    return (file) => ts.visitNode(file, visit)
+  }
+}
+
+/** Only TypeScript's synthetic __metadata("design:paramtypes", ...) call is eligible; source calls remain measured. */
+function isGeneratedMetadata(ts, node) {
+  return node.pos < 0 && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "__metadata" && node.arguments.length === 2 && ts.isStringLiteral(node.arguments[0]) && node.arguments[0].text === "design:paramtypes"
+}
+
+/** A metadata exclusion requires TypeScript's synthetic `typeof value === "function" ? value : Object` guard shape. */
+function isGeneratedGuard(ts, node) {
+  if (node.pos >= 0 || !ts.isConditionalExpression(node)) return false
+  const condition = node.condition
+  return ts.isBinaryExpression(condition) && condition.operatorToken.kind === ts.SyntaxKind.EqualsEqualsEqualsToken && ts.isTypeOfExpression(condition.left) && ts.isStringLiteral(condition.right) && condition.right.text === "function" && ts.isIdentifier(node.whenFalse) && node.whenFalse.text === "Object"
+}
+
+/** ts-jest normalizes map sources to the input file; restore the generated metadata anchor before Jest reads the map. */
+function restoreMetadataSource(result) {
+  const prefix = "sourceMappingURL=data:application/json;charset=utf-8;base64,"
+  const offset = result.code.lastIndexOf(prefix)
+  if (offset < 0) return result
+  const start = offset + prefix.length
+  const map = JSON.parse(Buffer.from(result.code.slice(start), "base64").toString("utf8"))
+  if (map.sourcesContent?.length !== 2 || map.sourcesContent[1] !== METADATA_TEXT) return result
+  map.sources = [map.sources[0], METADATA_SOURCE]
+  return { ...result, code: result.code.slice(0, start) + Buffer.from(JSON.stringify(map)).toString("base64") }
+}
+
+/** Unit transforms delegate compilation and caching to ts-jest; the after-transformer changes metadata mappings only. */
+function createTransformer(options) {
+  const delegate = require("ts-jest").default.createTransformer(options)
+  return {
+    getCacheKey: (...args) => delegate.getCacheKey(...args) + ":starci-unit-metadata-5",
+    process: (...args) => restoreMetadataSource(delegate.process(...args)),
+    processAsync: async (...args) => restoreMetadataSource(await delegate.processAsync(...args)),
+  }
+}
+
+module.exports = { name: "starci-unit-metadata", version: 5, factory, createTransformer }

package/unit-metadata.generated.cjs

@@ -0,0 +1,2 @@
+/* c8 ignore next */
+// Coverage anchor for generated design:paramtypes guards only.