@starci/jest-preset 2.2.7 → 2.3.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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.
+- Changed: a full app without a test world keeps only the unit project (an unfinished full scaffold), as before; the cited ruling is now ruling:R212/case-1 amended by ruling:R212/case-4.
+
 ## 2.2.7 - 2026-10-13
 
 - Fixed: the ESM-only runtime dependency `jose` (the Supabase access-token verifier of every lite back end) is compiled to CommonJS by ts-jest instead of being skipped with node_modules, so a lite app's unit run can load its guard (owner ruling 2026-10-12: lite keeps full's unit 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

@@ -60,7 +60,7 @@ function transform(tsconfig) {
  * 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 (owner ruling 2026-10-12), so a spec that imports its guard must load it.
+ * 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$`
@@ -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
 }
 
 /**
@@ -114,7 +108,7 @@ const underTests = (folder) => String.raw`[\\/]src[\\/]tests[\\/]` + folder + St
  * 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); the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * 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.
@@ -127,6 +121,16 @@ 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)
@@ -189,6 +193,8 @@ function coverageOf(options) {
 
 function starciJestConfig(options) {
   const coverage = coverageOf(options)
+  const root = process.cwd()
+  const world = hasTestWorld(root)
   const shared = {
     preset: "ts-jest",
     testEnvironment: "node",
@@ -201,15 +207,22 @@ function starciJestConfig(options) {
     ...shared,
     transform: transform("src/tests/tsconfig.json"),
     displayName,
-    // Every spec file in a process of its own (never in band): nothing one file or the globalSetup put on a process global
-    // (a framework registry such as @nestjs/graphql's type metadata) reaches another file. See world-runner.cjs.
-    runner: WORLD_RUNNER,
     // 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`],
-    // The one test world: started once per run of a project that has a test to run, torn down after it.
-    globalSetup: "<rootDir>/src/tests/world/global-setup.ts",
-    globalTeardown: "<rootDir>/src/tests/world/global-teardown.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))
+    }
+  }
   return {
     testTimeout: 120_000,
     coverageProvider: "v8",
@@ -218,7 +231,7 @@ function starciJestConfig(options) {
     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"],
+    coverageReporters: ["text-summary", "text", [require.resolve("./lcov.cjs"), {}]],
     projects: [
       {
         ...shared,
@@ -230,10 +243,9 @@ function starciJestConfig(options) {
         testMatch: ["**/*.spec.ts"],
         testPathIgnorePatterns: ["/node_modules/", ...TEST_KIND_FOLDERS.map(underTests)],
       },
-      // The integration, e2e and contract projects exist only where the repository has its test world: jest validates
-      // every project's globalSetup even under --selectProjects unit, so a repository whose world is not written yet
-      // would otherwise fail to run its unit specs with the managed config.
-      ...(hasTestWorld(process.cwd()) ? [suite("integration", "integration-spec"), suite("e2e", "e2e-spec"), suite("contract", "contract-spec")] : []),
+      // 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.2.7",
+  "version": "2.3.1",
   "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,
@@ -68,11 +68,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 +90,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.