ts-jest 29.4.6 → 29.4.7

package/.opencode/plans/pr3.md

@@ -0,0 +1,127 @@
+# PR 3 — Compiler Factory + CompilerFactoryInterface
+
+## Overview
+
+Introduces `CompilerFactoryInterface` and `CompilerFactory` — the single routing point that decides
+which compiler implementation to instantiate based on resolved config.
+
+**User-visible change**: NO
+**Depends on**: PR 1 (`ResolvedConfigInterface`, `DiagnosticsMode`), PR 2 (`CompilerInterface`,
+`LanguageServiceCompiler`, `FastTranspileCompiler`)
+**Invariant**: zero changes to any existing file
+
+---
+
+## Files to Create
+
+```
+src/experimental/
+  interfaces/
+    compiler-factory.interface.ts
+  compiler/
+    compiler-factory.ts
+```
+
+---
+
+## Requirements
+
+### `src/experimental/interfaces/compiler-factory.interface.ts`
+
+```ts
+interface CompilerFactoryInterface {
+  create(config: ResolvedConfigInterface, runtimeCacheFS: Map<string, string>): CompilerInterface
+}
+```
+
+Single method. `runtimeCacheFS` is a mutable map shared at runtime for in-memory file content
+(used by `LanguageServiceCompiler`; ignored by `FastTranspileCompiler`).
+
+---
+
+### `src/experimental/compiler/compiler-factory.ts`
+
+**Routing logic**:
+
+```
+config.diagnosticsMode === 'disabled'
+  → FastTranspileCompiler(config)
+
+config.diagnosticsMode !== 'disabled'
+  → LanguageServiceCompiler(config, runtimeCacheFS)
+```
+
+`diagnosticsMode` is derived in PR 1 (`diagnostics-config.ts`) from `noCheck` in the resolved
+tsconfig. The factory does not inspect `noCheck` directly — it reads the already-derived mode from
+`config.diagnosticsMode`.
+
+**SWC stub**:
+
+```ts
+case 'swc':
+  throw new NotImplementedError(
+    'SWC compiler support is not yet implemented. ' +
+    'Track progress at https://github.com/kulshekhar/ts-jest/issues/XXXX'
+  )
+```
+
+**esbuild stub**:
+
+```ts
+case 'esbuild':
+  throw new NotImplementedError(
+    'esbuild compiler support is not yet implemented. ' +
+    'Track progress at https://github.com/kulshekhar/ts-jest/issues/XXXX'
+  )
+```
+
+SWC/esbuild stubs are behind a `compilerBackend` option (reserved for future use, not yet in
+`TsJestTransformerOptions`). Currently unreachable in normal flow.
+
+**`NotImplementedError`**:
+
+```ts
+class NotImplementedError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'NotImplementedError'
+  }
+}
+```
+
+---
+
+## Import Rules
+
+- `src/experimental/interfaces/*` — allowed
+- `src/experimental/compiler/language-service-compiler.ts` — allowed
+- `src/experimental/compiler/fast-transpile-compiler.ts` — allowed
+- `src/utils/*` — allowed
+- `src/legacy/**` — FORBIDDEN
+- All other `src/` folders — FORBIDDEN
+
+---
+
+## Test Requirements
+
+Unit tests under `src/experimental/compiler/__tests__/`.
+
+| Test file                  | Key scenarios                                                                                                                                                                                                                                                                        |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `compiler-factory.spec.ts` | `diagnosticsMode: 'disabled'` → returns `FastTranspileCompiler`; `diagnosticsMode: 'full'` → returns `LanguageServiceCompiler`; `diagnosticsMode: 'syntactic'` → returns `LanguageServiceCompiler`; SWC stub throws `NotImplementedError`; esbuild stub throws `NotImplementedError` |
+
+**Existing tests must remain green** (no changes to legacy):
+
+- `src/legacy/compiler/ts-jest-compiler.spec.ts`
+- Legacy `TsJestCompiler` still uses `TsCompiler` directly — untouched
+
+---
+
+## Acceptance Criteria
+
+- [ ] All new unit tests pass
+- [ ] `ts-jest-compiler.spec.ts` unmodified and green
+- [ ] `tsc --noEmit` passes
+- [ ] Factory correctly routes based on `diagnosticsMode`
+- [ ] SWC and esbuild stubs throw `NotImplementedError` with issue tracker link
+- [ ] Every exported symbol has TSDoc

package/.opencode/plans/pr4.md

@@ -0,0 +1,229 @@
+# PR 4 — Transformer Concern Modules
+
+## Overview
+
+Extracts the five discrete concerns from `TsJestTransformer` into focused, independently testable
+modules. This PR produces no user-facing changes — it is groundwork for the new transformer in PR 5.
+
+**User-visible change**: NO
+**Depends on**: PR 1 (`ResolvedConfigInterface`), PR 2 (`CompilerInterface`), PR 3 (`CompilerFactoryInterface`)
+**Invariant**: zero changes to any existing file
+
+---
+
+## Files to Create
+
+```
+src/experimental/transformer/
+  cache-store.ts
+  file-processor.ts
+  cache-key-builder.ts
+  hooks-runner.ts
+  babel-pipeline.ts
+```
+
+---
+
+## Requirements
+
+### `src/experimental/transformer/cache-store.ts`
+
+Replaces the static `_cachedConfigSets: CachedConfigSet[]` array in `TsJestTransformer`.
+
+**Purpose**: deduplicates `ResolvedConfig` instances across `getCacheKey` and `process` calls
+(Jest sometimes splits these calls across separate invocations with the same config but different
+object references).
+
+**2-pass deduplication**:
+
+```
+Pass 1 — object identity:
+  Compare jestConfig reference (===)
+  → Hit: return cached ResolvedConfig
+
+Pass 2 — serialised string:
+  Serialise jestConfig (excluding cacheDirectory) + cacheSuffix
+  → Hit: update stored .value reference, return cached ResolvedConfig
+
+Miss:
+  Merge transformerOptions into config.globals['ts-jest']
+  Create new ResolvedConfig
+  Compute _transformCfgStr = serialize(jest-without-cacheDirectory) + cacheSuffix
+  Detect watch = process.argv.includes('--watch')
+  Store and return
+```
+
+```ts
+class CacheStore {
+  private _entries: CacheEntry[]
+
+  getOrCreate(
+    jestConfig: Config.ProjectConfig,
+    transformerOptions: TsJestTransformerOptions,
+    factory: (config: Config.ProjectConfig, options: TsJestTransformerOptions) => ResolvedConfigInterface,
+  ): ResolvedConfigInterface
+}
+```
+
+Thread-safety: not required (Node.js single-threaded; Jest workers are separate processes).
+
+---
+
+### `src/experimental/transformer/file-processor.ts`
+
+Implements the 5-branch file dispatch logic extracted from `processWithTs()`.
+
+```ts
+function processFile(
+  fileContent: string,
+  filePath: string,
+  options: ProcessFileOptions,
+  config: ResolvedConfigInterface,
+  compiler: CompilerInterface,
+): CompiledOutput
+```
+
+**5 branches in exact order** (first matching branch wins):
+
+1. `config.shouldStringifyContent(filePath)`
+   → `{ code: \`module.exports=\${JSON.stringify(fileContent)}\` }`
+
+2. `filePath.endsWith('.d.ts')`
+   → `{ code: '' }`
+
+3. `isNodeModule(filePath) && (isJs(filePath) || isJsx(filePath))`
+   → fast `ts.transpileModule` with `{ module: useESM && supportsStaticESM ? ESNext : CommonJS }`
+
+   - `isNodeModule`: `filePath.includes(path.sep + 'node_modules' + path.sep)`
+
+4. `isJs(filePath) || isJsx(filePath) || isTs(filePath) || isTsx(filePath)` (not node_modules)
+   → `compiler.getCompiledOutput(fileContent, filePath, compileOptions)`
+
+5. Fallback
+   → warn "unknown extension, returning as-is" + return `{ code: fileContent }`
+
+---
+
+### `src/experimental/transformer/cache-key-builder.ts`
+
+Pure function — `fs.statSync` injected for testability.
+
+```ts
+function buildCacheKey(
+  fileContent: string,
+  filePath: string,
+  options: CacheKeyOptions,
+  config: ResolvedConfigInterface,
+  compiler: CompilerInterface,
+  statSync: (path: string) => { mtimeMs: number },
+): string
+```
+
+**Elements hashed in exact order**:
+
+1. `_transformCfgStr` (from `CacheStore` entry)
+2. `config.rootDir`
+3. `instrument ? 'instrument:on' : 'instrument:off'`
+4. `supportsStaticESM ? 'esm:on' : 'esm:off'`
+5. `fileContent`
+6. `filePath`
+7. If `!config.isolatedModules && config.tsCacheDir`:
+   - For each module in `compiler.getResolvedModules(fileContent, filePath, runtimeCacheFS)`:
+     - `moduleName`
+     - `statSync(moduleName).mtimeMs.toString()`
+
+Returns `sha1(elements.join(''))`.
+
+---
+
+### `src/experimental/transformer/hooks-runner.ts`
+
+Encapsulates `TS_JEST_HOOKS` reading and invocation.
+
+```ts
+function runAfterProcessHook(
+  result: TransformResult,
+  fileContent: string,
+  filePath: string,
+  jestOptions: TransformOptions,
+): TransformResult
+```
+
+**Behaviour**:
+
+- Read `process.env.TS_JEST_HOOKS` **at call time** (not at module load time)
+- If not set → return `result` as-is
+- Resolve hook file path relative to `process.cwd()`
+- `require()` the hooks module
+- Call `hooksModule.afterProcess(result, fileContent, filePath, jestOptions)`
+- If return value is truthy → return it
+- Else → return original `result`
+
+This matches the legacy behavior in `TsJestTransformer.runTsJestHook()` exactly.
+
+---
+
+### `src/experimental/transformer/babel-pipeline.ts`
+
+Shared sync + async Babel transformation logic.
+
+```ts
+function transformWithBabel(
+  result: CompiledOutput,
+  filePath: string,
+  options: TransformOptions,
+  babelJestTransformer: BabelTransformer,
+): TransformResult
+
+async function transformWithBabelAsync(
+  result: CompiledOutput,
+  filePath: string,
+  options: TransformOptions,
+  babelJestTransformer: BabelTransformer,
+): Promise<TransformResult>
+```
+
+**Requirements**:
+
+- Force `instrument: false` when passing to `babelJestTransformer.process()` / `processAsync()`
+  (instrumentation is handled by Jest, not Babel)
+- Pass `result.code` + `result.map` as the content to transform
+- Return the Babel transformer's output directly
+
+---
+
+## Import Rules
+
+- `src/experimental/interfaces/*` — allowed
+- `src/experimental/config/*` — allowed
+- `src/experimental/compiler/*` — allowed
+- `src/utils/*` — allowed (sha1, logger, ts-error)
+- `src/types.ts` — allowed
+- `src/legacy/**` — FORBIDDEN
+- All other `src/` folders — FORBIDDEN
+
+---
+
+## Test Requirements
+
+Unit tests under `src/experimental/transformer/__tests__/`.
+
+| Test file                   | Key scenarios                                                                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cache-store.spec.ts`       | identity hit returns same instance; serialised string hit returns same instance and updates reference; miss creates new instance; watch detection via process.argv          |
+| `file-processor.spec.ts`    | each branch fires in correct priority order; stringify branch; .d.ts returns empty; node_module JS → fast transpile; TS/TSX → compiler; unknown ext → warn + passthrough    |
+| `cache-key-builder.spec.ts` | same inputs → same key; any single input change → different key; isolated mode skips module mtimes; non-isolated includes module mtime                                      |
+| `hooks-runner.spec.ts`      | no TS_JEST_HOOKS env → passthrough; env set → requires module + calls afterProcess; truthy return → used; falsy return → original used; env read at call time not load time |
+| `babel-pipeline.spec.ts`    | calls babelJest with instrument:false; async variant works; result code passed through                                                                                      |
+
+---
+
+## Acceptance Criteria
+
+- [ ] All new unit tests pass
+- [ ] All existing legacy tests unmodified and green
+- [ ] `tsc --noEmit` passes
+- [ ] No import from `src/legacy/`
+- [ ] `cache-key-builder.ts` has no direct `fs` import — `statSync` is injected
+- [ ] `hooks-runner.ts` reads `TS_JEST_HOOKS` at call time, not at module load time
+- [ ] Every exported symbol has TSDoc

package/.opencode/plans/pr5.md

@@ -0,0 +1,211 @@
+# PR 5 — New TsJestTransformer + `future.v30_newTransformer` Opt-in
+
+## Overview
+
+Assembles all experimental modules into a new `TsJestTransformer` class and wires it behind the
+`future.v30_newTransformer` opt-in flag. Users explicitly opt in by adding the flag to their Jest
+config. The legacy transformer continues to be the default.
+
+**User-visible change**: YES — opt-in only via `future: { v30_newTransformer: true }`
+**Depends on**: PR 1, PR 2, PR 3, PR 4
+**Existing file changes**: minimal, additive only (`src/types.ts`, `src/index.ts`)
+
+---
+
+## Files to Create
+
+```
+src/experimental/transformer/
+  transformer.ts
+```
+
+---
+
+## Files to Modify (additive only)
+
+```
+src/types.ts         — add optional future field to TsJestTransformerOptions
+src/index.ts         — createTransformer branches on future.v30_newTransformer
+```
+
+---
+
+## Requirements
+
+### `src/experimental/transformer/transformer.ts`
+
+Clean-room `SyncTransformer<TsJestTransformerOptions>` implementation. No static state, no
+`process.env` writes, all I/O injected.
+
+**Constructor**:
+
+```ts
+constructor(
+  tsJestConfig?: TsJestTransformerOptions,
+  private readonly _fs: Pick<typeof fs, 'statSync'> = fs,
+)
+```
+
+- No `process.env.TS_JEST = '1'` (removed in v30)
+- `_cacheStore = new CacheStore()`
+- `_runtimeCacheFS = new Map<string, string>()`
+
+**`_configsFor(jestConfig)`** (private):
+
+- Delegates to `_cacheStore.getOrCreate(jestConfig, this._tsJestConfig, ResolvedConfig)`
+- Returns `{ config: ResolvedConfigInterface, compiler: CompilerInterface }`
+- `compiler` created lazily via `CompilerFactory.create(config, _runtimeCacheFS)`
+- Compiler is cached per config entry (same config → same compiler instance)
+
+**`process(fileContent, filePath, jestOptions)`**:
+
+1. `{ config, compiler } = _configsFor(jestOptions.transformerConfig ?? {})`
+2. `result = processFile(fileContent, filePath, jestOptions, config, compiler)`
+3. If `config.babelJestTransformer`: `result = transformWithBabel(result, filePath, jestOptions, babelJestTransformer)`
+4. `result = runAfterProcessHook(result, fileContent, filePath, jestOptions)`
+5. Return `result`
+
+**`processAsync(fileContent, filePath, jestOptions)`**:
+
+1. Same as `process` steps 1–2
+2. Collect diagnostics: if `result.diagnostics?.length > 0` → throw `TSError`
+3. If `config.babelJestTransformer`: `result = await transformWithBabelAsync(...)`
+4. `result = runAfterProcessHook(...)`
+5. Return `result`
+
+**`getCacheKey(fileContent, filePath, options)`**:
+
+- `{ config, compiler } = _configsFor(options.transformerConfig ?? {})`
+- Returns `buildCacheKey(fileContent, filePath, options, config, compiler, this._fs.statSync)`
+
+**`getCacheKeyAsync`**: delegates to `getCacheKey` (same logic, wraps in Promise)
+
+**Protected extension points** (for subclassing, preserved from legacy):
+
+```ts
+protected _createConfigSet(config: Config.ProjectConfig): ResolvedConfigInterface
+protected _createCompiler(config: ResolvedConfigInterface): CompilerInterface
+```
+
+**v30 behavioral differences vs legacy** (only active under this flag):
+
+| Scenario                            | Legacy behavior                                | v30 behavior                                               |
+| ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
+| `isolatedModules: true` in tsconfig | routes to `ts.transpileModule` (no type check) | routes to `LanguageServiceCompiler` (type checking works)  |
+| `diagnostics: false`                | silently disables diagnostics                  | accepted + deprecation warning pointing to `noCheck: true` |
+| `noCheck: true` in tsconfig         | unknown (not supported)                        | routes to `FastTranspileCompiler`                          |
+| `process.env.TS_JEST = '1'`         | set in constructor                             | NOT set                                                    |
+
+---
+
+### `src/types.ts` — Additive change
+
+Add `future` field to `TsJestTransformerOptions` (the existing public type):
+
+```ts
+// Addition only — existing fields unchanged
+future?: {
+  /**
+   * Opt in to the v30 transformer rewrite.
+   * @experimental
+   */
+  v30_newTransformer?: boolean
+}
+```
+
+No existing fields modified. No existing types removed.
+
+---
+
+### `src/index.ts` — Additive change
+
+Branch `createTransformer` on the future flag:
+
+```ts
+export const createTransformer = (tsJestConfig?: TsJestTransformerOptions) => {
+  if (tsJestConfig?.future?.v30_newTransformer) {
+    const { NewTsJestTransformer } = require('./experimental/transformer/transformer')
+    return new NewTsJestTransformer(tsJestConfig)
+  }
+  return new TsJestTransformer(tsJestConfig) // legacy path unchanged
+}
+```
+
+The `require()` is intentional: avoids loading any experimental code unless the flag is set.
+No other changes to `src/index.ts`.
+
+---
+
+## Usage (opt-in)
+
+```js
+// jest.config.js
+module.exports = {
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        future: { v30_newTransformer: true },
+      },
+    ],
+  },
+}
+```
+
+Users not setting this flag get identical behavior to before.
+
+---
+
+## Import Rules
+
+### `src/experimental/transformer/transformer.ts`
+
+- `src/experimental/**` — all submodules allowed
+- `src/utils/*` — allowed
+- `src/types.ts` — allowed
+- `src/legacy/**` — FORBIDDEN
+
+### `src/index.ts` change
+
+- Uses `require()` for lazy load of experimental transformer
+- No static import of experimental code at module level
+
+---
+
+## Test Requirements
+
+Unit tests under `src/experimental/transformer/__tests__/`.
+
+| Test file             | Key scenarios                                                                                                                                                                                                                                                                                                                                |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `transformer.spec.ts` | `process` happy path; `processAsync` throws TSError on diagnostics; `getCacheKey` returns stable key; babel pipeline invoked when configured; hooks runner invoked; no `process.env.TS_JEST` set; `isolatedModules: true` → `LanguageServiceCompiler`; `noCheck: true` → `FastTranspileCompiler`; `diagnostics: false` → deprecation warning |
+
+Integration (e2e) — add a new e2e project `e2e/v30-transformer/` exercising the new transformer
+via `future: { v30_newTransformer: true }`:
+
+| Scenario                             | e2e test                                                         |
+| ------------------------------------ | ---------------------------------------------------------------- |
+| Basic TS compilation                 | `.spec.ts` with simple import, passes                            |
+| Type error caught                    | `.spec.ts` with deliberate type error, jest reports it           |
+| `noCheck: true` skips type errors    | `.spec.ts` with type error + `noCheck: true` in tsconfig, passes |
+| Source maps work                     | Source map points to original `.ts` line numbers                 |
+| `isolatedModules: true` + type error | Type error IS caught (fix for legacy bug)                        |
+
+**All existing tests must remain green** — legacy path is completely unchanged.
+
+---
+
+## Acceptance Criteria
+
+- [ ] All new unit tests pass
+- [ ] New e2e tests pass
+- [ ] All existing unit + e2e tests unmodified and green
+- [ ] `tsc --noEmit` passes
+- [ ] `process.env.TS_JEST` is NOT set by new transformer
+- [ ] `future.v30_newTransformer: false` or absent → legacy `TsJestTransformer` used (no regression)
+- [ ] `future.v30_newTransformer: true` → new transformer used
+- [ ] `isolatedModules: true` → `LanguageServiceCompiler` (type checking works)
+- [ ] `diagnostics: false` → deprecation warning logged
+- [ ] `noCheck: true` + `diagnostics.warnOnly` → silent (no warning)
+- [ ] No experimental code loaded unless flag is set
+- [ ] Every exported symbol has TSDoc