@systemfsoftware/stryker-js 11.0.0 → 12.1.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @systemfsoftware/stryker-js
 
+## 12.1.0
+
+### Minor Changes
+
+- A piped `stdout` now gets human output, exactly like a terminal. Machine consumers ask for the NDJSON event stream explicitly, with `--json` or `STRYKER_MODE=machine`; `--format text` names the human format, and passing it together with `--json` is a usage error (exit 2). Under `--json`, `stdout` carries wire records and nothing else, while progress status lines and log output stay on `stderr`.
+
+  Every run also writes those wire records to `reports/mutation-stream.jsonl` in human mode too, so a job that shows a readable log still produces the artifact `stryker merge-reports` rebuilds a shard's report from.
+
+  If a script or CI step read NDJSON from a piped run without requesting it, pass `--json` (or set `STRYKER_MODE=machine`) there.
+
+  Custom `RunEventDrain` implementations must accept a required `toStdout` argument in `drainFramed`; pass-throughs can ignore it.
+
+### Patch Changes
+
+- A run whose selected files produce no mutants, for example because no loaded framework claims them, now runs every test in the dry run and finishes with an empty report. With `testRunner: 'vm'` or `'vitest'` it used to fail with "No tests were executed", because the dry run only looked for tests related to those files. The dry run now relates tests only to the files that carry mutants.
+
+- A run whose `mutate` patterns match no file now finishes successfully instead of stopping with an instrument error. It performs the dry run, writes a mutation report with no files, and passes regardless of `thresholds.break`, the same as upstream StrykerJS. A sharded run whose shard receives no file no longer fails.
+
+  `stryker merge-reports` shows `n/a` for a package whose report has no tested mutant, instead of a score of `0.00`.
+
+  Errors reported for the prepare, dry-run, and mutation-testing stages now carry their reason as the error message, so a printed cause no longer shows up as a bare error name.
+
+- `stryker merge-reports` now rebuilds a package's partial report from the mutants recorded in its stream part when the run ended before writing its final report. Earlier versions recognized none of the recorded mutants and reported the package as having no report.
+
+- Mutation runs with `testRunner: 'vm'` finish in about half the time, with the same verdicts. The engine checks mutant groups on every checker process at once, stops the checkers as soon as checking ends, hands their share of `concurrency` to the test runners, and shares a Node compile cache with every worker it starts. The Vitest runner starts the next isolated worker thread while the current test file runs, so each file still gets a fresh thread but no longer waits for one to boot. On a 319-mutant TypeScript project with the TypeScript checker, a run went from 24.9 s to 12.6 s.
+
+- `testRunner: 'vm'` runs Vitest itself on Vitest's isolated `threads` pool instead of an in-process reimplementation, and stays the default `testRunner`. It reports the same test ids, outcomes and per-mutant verdicts as `testRunner: 'vitest'`, so a project whose Vitest config enables browser mode is refused at startup with a message naming `testRunner: 'vitest'`.
+
+  Stryker no longer discovers test files for `vm`: Vitest selects them from your config, as it does for `testRunner: 'vitest'`. A run that loads no test files fails the dry run naming `testFiles`.
+
+## 12.0.0
+
+### Major Changes
+
+- Restore `defineConfig` and `mergeConfig` on `@systemfsoftware/stryker-js/config`. `defineConfig` accepts an options object, a promise of one, or a `(env: ConfigEnv) => …` factory, as in 10.1.1, and `mergeConfig(defaults, overrides)` composes presets again. `StrykerConfig` is again the partial-options type, so `const config: StrykerConfig = defineConfig({ … })` typechecks. Config files written against the 10.1.1 `./config` surface load and typecheck without edits.
+
+  This removes the 11.0.0 `StrykerConfig` class value. If you adopted it:
+
+  - Replace `StrykerConfig.define(…)` with `defineConfig(…)` and `StrykerConfig.merge(…)` with `mergeConfig(…)`, imported from `@systemfsoftware/stryker-js/config`.
+  - Replace `StrykerConfig.createDefaultOptions()` and `StrykerConfig.defaultOptions` with `Configuration.createDefaultOptions()` and `Configuration.defaultOptions` from the package entry point.
+
+### Patch Changes
+
+- A failed dry run now says which tests broke and why. The refusal names every failing test with its failure message in the error output and in the log at the default level, instead of reporting only how many failed.
+
+- Installing `@systemfsoftware/stryker-js` on its own now works. `effect` was declared an optional peer even though Stryker imports it at runtime. Package managers never install optional peers, so a project without `effect` failed with `Failed to read config` before the run started. `effect` is now a required peer: pnpm and npm install it automatically, and a project that already uses Effect shares its own copy with Stryker.
+
+- The packages now build on the latest `@systemfsoftware/effect-cell-types` 10.2 cell kinds, with no change to their published behavior.
+
+  - `@systemfsoftware/stryker-test-contribution` exports its evaluator as `Judge`, `TestContribution`, and `TestContributionEvaluator`, and now depends on `effect` directly.
+
 ## 11.0.0
 
 ### Patch Changes

package/README.md

@@ -2,8 +2,8 @@
 
 The modern mutation testing framework for JavaScript and TypeScript.
 A ground-up, breaking-change fork of `@stryker-mutator/core` built with Effect 4:
-provides the `stryker` executable, in-process `vm` and isolated Vitest runners,
-and the typed `./config` authoring surface.
+provides the `stryker` executable, the `vm` and `vitest` test runners, and the
+typed `./config` authoring surface.
 
 ## Install
 
@@ -24,9 +24,9 @@ pnpm add -D @systemfsoftware/stryker-js \
 Create `stryker.config.ts` in your project root:
 
 ```ts
-import { StrykerConfig } from '@systemfsoftware/stryker-js/config'
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
 
-export default StrykerConfig.define({
+export default defineConfig({
   testRunner: 'vitest',
   checkers: ['typescript'],
   plugins: [
@@ -54,19 +54,22 @@ pnpm exec stryker run
 
 ## Zero-Plugin Built-in Runners
 
-The `vm` runner is the default: with no `testRunner` and no `testFiles`
-configured, it discovers `*.test` / `*.spec` files itself and runs them. It loads
-your suites through your project's `vitest`, so `vitest` must be installed.
-Set `testFiles` explicitly, or pick one of the runners below, to take control.
+The `vm` runner is the default and needs no plugin packages: `testRunner: 'vm'`
+runs Vitest itself, on Vitest's isolated `threads` pool, through the project's
+own `vitest` install (`vitest` must be installed). With no `testFiles`
+configured, Vitest selects the test files from your config, exactly as
+`vitest run` does. The runner reports the same test ids, outcomes and
+per-mutant verdicts as `vitest run`. Set `testFiles` explicitly, or pick one of
+the runners below, to take control.
 
 ### 1. Shell Command Runner (`testRunner: 'command'`)
 
 Execute any test suite without extra plugins:
 
 ```ts
-import { StrykerConfig } from '@systemfsoftware/stryker-js/config'
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
 
-export default StrykerConfig.define({
+export default defineConfig({
   testRunner: 'command',
   commandRunner: {
     command: 'npm test',
@@ -75,34 +78,42 @@ export default StrykerConfig.define({
 })
 ```
 
-### 2. In-Process `vm` Runner (`testRunner: 'vm'`)
+### 2. The `vm` Runner (`testRunner: 'vm'`)
 
-Runs Vitest suites in-process, in one worker thread per test runner, loading each test file as native ESM through Node's module hooks. No child process and no bundler step. Each file gets its own module state by default; your `vitest.config.*` (environment, setup files, globals, projects) is picked up through your project's `vitest` install. Vitest browser-mode suites are refused with an error naming `testRunner: 'vitest'`; pick the `vitest` runner for those.
+Runs the Vitest runner on Vitest's isolated `threads` pool. Each test file keeps
+Vitest's own per-file isolation, and module mocking, snapshots, environments,
+setup files, projects and custom transforms behave as they do under
+`vitest run`. A Vitest config that enables browser mode is refused with an
+error naming `testRunner: 'vitest'`; pick the `vitest` runner for those.
 
 ```ts
-import { StrykerConfig } from '@systemfsoftware/stryker-js/config'
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
 
-export default StrykerConfig.define({
+export default defineConfig({
   testRunner: 'vm',
   testFiles: ['test/**/*.test.ts'],
   mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
 })
 ```
 
+Suites that need Vitest's `forks` pool (for example `process.chdir`, or native
+addons that are not thread-safe) use `testRunner: 'vitest'` with the
+`@systemfsoftware/stryker-js-vitest-runner` plugin instead.
+
 ## Configuration API (`@systemfsoftware/stryker-js/config`)
 
-The `./config` subpath exports the typed configuration authoring surface:
+The `./config` subpath exports the typed configuration authoring surface, including the `StrykerConfig` type naming the partial options a config file writes: a config annotated `const config: StrykerConfig = defineConfig({ ... })` typechecks and loads.
 
 ```ts
-import { StrykerConfig } from '@systemfsoftware/stryker-js/config'
+import { defineConfig, type StrykerConfig } from '@systemfsoftware/stryker-js/config'
 ```
 
-### `StrykerConfig.define(options | configFactory)`
+### `defineConfig(options | configFactory)`
 
 Identity function providing strict autocompletion and type checking without runtime dependencies. Can take a configuration object or a factory receiving `ConfigEnv`:
 
 ```ts
-export default StrykerConfig.define(({ isCi, command }) => ({
+export default defineConfig(({ isCi, command }) => ({
   testRunner: 'vitest',
   plugins: ['@systemfsoftware/stryker-js-vitest-runner'],
   mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
@@ -110,15 +121,15 @@ export default StrykerConfig.define(({ isCi, command }) => ({
 }))
 ```
 
-### `StrykerConfig.merge(base, overrides)`
+### `mergeConfig(base, overrides)`
 
 Deeply merges configuration presets. Keys in records merge recursively; scalar values and arrays in `overrides` completely replace base values:
 
 ```ts
-import { StrykerConfig } from '@systemfsoftware/stryker-js/config'
+import { mergeConfig } from '@systemfsoftware/stryker-js/config'
 import baseConfig from './stryker.base.config.ts'
 
-export default StrykerConfig.merge(baseConfig, {
+export default mergeConfig(baseConfig, {
   concurrency: 8,
   mutate: ['packages/core/src/**/*.ts'],
 })
@@ -143,9 +154,20 @@ pnpm exec stryker run --incremental
 pnpm exec stryker run --concurrency 4
 
 # Merge partial mutation reports from parallel CI shards
-pnpm exec stryker merge-reports --output reports/mutation/mutation.json "reports/shards/*.json"
+pnpm exec stryker merge-reports --parts reports/shards --out reports/mutation
 ```
 
+## Output Modes
+
+Human output is the default, whether or not `stdout` is a terminal. A machine consumer opts into the NDJSON event stream explicitly:
+
+```bash
+pnpm exec stryker run --json                # wire records on stdout, diagnostics on stderr
+STRYKER_MODE=machine pnpm exec stryker run  # the same, named by environment
+```
+
+`--format text` names the human format explicitly; `--json` together with `--format text` is a usage error (exit 2). Under `--json`, `stdout` carries wire records and nothing else — progress lines and log output stay on `stderr`. Every run also writes the same records to `reports/mutation-stream.jsonl` (`--progressStreamFile`) in both modes, which is the artifact `stryker merge-reports` rebuilds a shard's partial report from.
+
 ## Programmatic API
 
 ### Effect 4 Native Interface
@@ -180,11 +202,11 @@ console.log(`Mutation score: ${verdict.score}%`)
 
 ## Published Subpaths
 
-| Subpath      | Description                                                        |
-| ------------ | ------------------------------------------------------------------ |
-| `.`          | Main entry point: `strykerCell`, runtime layers, and error schemas |
-| `./config`   | `StrykerConfig` authoring surface (`define`, `merge`)              |
-| `./promises` | `run()` wrapper returning standard JavaScript promises             |
+| Subpath      | Description                                                               |
+| ------------ | ------------------------------------------------------------------------- |
+| `.`          | Main entry point: `strykerCell`, runtime layers, and error schemas        |
+| `./config`   | Config authoring surface (`defineConfig`, `mergeConfig`, `StrykerConfig`) |
+| `./promises` | `run()` wrapper returning standard JavaScript promises                    |
 
 ## License