@systemfsoftware/stryker-js 4.0.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # @systemfsoftware/stryker-js
 
+## 6.0.0
+
+### Major Changes
+
+- `testRunner`, `checkers`, and `ignorers` now carry the plugin and its options together.
+
+  - `testRunner` is `'command'`, `'vm'`, or `{ plugin, options?, nodeArgs? }`.
+  - `checkers` is `{ plugin, options?, nodeArgs? }[]`. Each checker is its own plugin.
+  - `ignorers` is plugin file URLs. Every ignorer those modules export runs. There is no separate name list.
+  - Put Vitest settings on `testRunner.options` (`configFile`, `dir`, `related`). There is no `vitest` block.
+  - Put TypeScript checker settings on that checker's `options` (`prioritizePerformanceOverAccuracy`). There is no `typescriptChecker` block.
+
+  Before:
+
+  ```ts
+  export default defineConfig({
+    testRunner: 'vitest',
+    checkers: ['typescript'],
+    plugins: [
+      import.meta.resolve('@systemfsoftware/stryker-js-vitest-runner'),
+      import.meta.resolve('@systemfsoftware/stryker-js-typescript-checker'),
+      import.meta.resolve('@systemfsoftware/stryker-ignorer-effect-schema-declarations'),
+    ],
+    vitest: { configFile: 'vitest.config.ts' },
+    typescriptChecker: { prioritizePerformanceOverAccuracy: true },
+    ignorers: ['effect-schema-declarations'],
+  })
+  ```
+
+  After:
+
+  ```ts
+  export default defineConfig({
+    testRunner: {
+      plugin: import.meta.resolve('@systemfsoftware/stryker-js-vitest-runner'),
+      options: { configFile: 'vitest.config.ts' },
+    },
+    checkers: [
+      {
+        plugin: import.meta.resolve('@systemfsoftware/stryker-js-typescript-checker'),
+        options: { prioritizePerformanceOverAccuracy: true },
+      },
+    ],
+    ignorers: [
+      import.meta.resolve('@systemfsoftware/stryker-ignorer-effect-schema-declarations'),
+    ],
+  })
+  ```
+
+### Patch Changes
+
+- Unix worker sockets are now owner-read-write once the worker has bound them. Named pipes are unchanged.
+
+- Updated dependencies:
+  - @systemfsoftware/stryker-js-plugin-interface@6.0.0
+
+## 5.0.0
+
+### Major Changes
+
+- Plugin entries in `plugins` and `appendPlugins` are now the entrypoints
+  themselves, as `file:` URLs, instead of package names Stryker resolved for you.
+
+  Stryker resolved every specifier against its own module before, so a plugin the
+  project had installed was only found when Node happened to walk to the right
+  `node_modules` from Stryker's location — which is not the project's location for
+  a global install, an `npx` run, or a strict isolated store. The project now
+  resolves each plugin itself, in the config module where the project's own
+  dependencies are visible:
+
+  ```ts
+  import { defineConfig } from '@systemfsoftware/stryker-js/config'
+
+  export default defineConfig({
+    plugins: [import.meta.resolve('@acme/stryker-runner')],
+  })
+  ```
+
+  The `--plugins` and `--appendPlugins` flags take the same resolved URLs. A value
+  that is not a `file:` URL is refused with the entry named.
+
+  Stryker no longer reports an unresolved specifier as a warning it can continue
+  past, because it no longer resolves one: a plugin that cannot be loaded stops
+  the run and names the entry, and a plugin that loads but contributes nothing is
+  still reported as before.
+
+- The engine and the CLI are one package. `@systemfsoftware/stryker-js` now ships
+  the `stryker` binary, the run engine, and the configuration surface, replacing
+  `@systemfsoftware/stryker-js-cli` and `@systemfsoftware/stryker-js-engine`, which
+  are discontinued.
+
+  Two subpaths are new:
+
+  - `./config` — `defineConfig`, `mergeConfig`, `ConfigEnv`, `StrykerConfig`. Use it
+    instead of hand-typing `stryker.config.ts` against the option type.
+  - `./promises` — `run`, the same run interpreted for promise callers, so an
+    embedding script does not need an Effect runtime.
+
+  Migrate by importing from `@systemfsoftware/stryker-js`. Everything the two
+  discontinued packages exported — the option type, `readConfig`, the plugin
+  loader, `WorkerLauncher`, and the exit classification — keeps its name and its
+  behavior at the new address.
+
+  `@systemfsoftware/stryker-js-language` is gone; it is replaced rather than
+  continued. The run-event vocabulary it was carrying — `RunEvents`, `RunIdentity`,
+  `RunPhase`, and the `Run*` event schemas — now ships from
+  `@systemfsoftware/stryker-js`. Two consequences follow for anyone who imported
+  it:
+
+  - The mutant model, the report schemas, and the checker, evaluator and
+    test-runner contracts come from `@systemfsoftware/stryker-js-instrumenter`
+    and `@systemfsoftware/stryker-js-plugin-interface`. Update those imports.
+  - The service identifiers `@systemfsoftware/stryker-js-language/RunEvents` and
+    `@systemfsoftware/stryker-js-language/RunIdentity` are now
+    `@systemfsoftware/stryker-js/RunEvents` and
+    `@systemfsoftware/stryker-js/RunEvents/RunIdentity`. A program that provides or
+    looks up either service by its identifier string must use the new one.
+
+  Two more changes reach programmatic callers:
+
+  - `testRunner: 'vm'` runs the test suite in memory. Stryker strips TypeScript from
+    the test files during preparation and evaluates them in a fresh V8 context per
+    mutant, so a run needs no child process and no manual bundling.
+  - `readConfig` and `resolveExtends` take the invocation a configuration is being
+    read for, so a `stryker.config.ts` may export a factory receiving
+    `{ command, isDryRun, mode, isCi }` and compute its settings per invocation.
+    Both keep working for a plain exported object; the extra argument is the
+    `command` and output `mode` the loader cannot see for itself.
+
 ## 4.0.0
 
 ### Major Changes

package/LICENSE

@@ -1,6 +1,4 @@
-Copyright (c) 2026 Ryan Lee (systemfsoftware)
-
-Apache License
+                                 Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
@@ -180,7 +178,7 @@ Apache License
    APPENDIX: How to apply the Apache License to your work.
 
       To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
+      boilerplate notice, with the fields enclosed by brackets "{}"
       replaced with your own identifying information. (Don't include
       the brackets!)  The text should be enclosed in the appropriate
       comment syntax for the file format. We also recommend that a
@@ -188,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Ryan Lee (systemfsoftware)
+   Copyright {yyyy} {name of copyright owner}
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -201,13 +199,3 @@ Apache License
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-
-
-----------------------------------------------------------------------
-Third-party notices
-
-Portions of this software are derived from @stryker-mutator/vitest-runner
-v9.6.1 (upstream commit e1abfbe), part of StrykerJS
-(https://github.com/stryker-mutator/stryker-js), which is licensed under the
-Apache License, Version 2.0 — the same license this package is distributed
-under. The derived files have been modified.

package/README.md

@@ -1,26 +1,185 @@
-# @systemfsoftware/stryker-js
+# `@systemfsoftware/stryker-js`
 
-The mutation-testing language — the plugin kinds, capability ports, and schemas
-a mutation run is built from, with no platform. The Node host that runs a
-mutation test lives in `@systemfsoftware/stryker-js-engine`.
+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-memory V8 and isolated Vitest runners,
+and the typed `./config` authoring surface.
 
 ## Install
 
-```sh
-pnpm add @systemfsoftware/stryker-js
+```bash
+pnpm add -D @systemfsoftware/stryker-js
 ```
 
-## Entry point
+## Quick Start: Vitest Runner
 
-One specifier carries the whole vocabulary. The package entry
-enumerates every published symbol exactly once — concepts (Checker,
-Evaluator, ExitClass, Ignorer, Metrics, Module, Mutant, Plugin, Report,
-ReporterEvent, Run, Schema, TestRunner) are all imported from the root:
+For TypeScript codebases using Vitest:
+
+```bash
+pnpm add -D @systemfsoftware/stryker-js \
+  @systemfsoftware/stryker-js-vitest-runner \
+  @systemfsoftware/stryker-js-typescript-checker
+```
+
+Create `stryker.config.ts` in your project root:
+
+```ts
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
+
+export default defineConfig({
+  testRunner: 'vitest',
+  checkers: ['typescript'],
+  plugins: [
+    import.meta.resolve('@systemfsoftware/stryker-js-vitest-runner'),
+    import.meta.resolve('@systemfsoftware/stryker-js-typescript-checker'),
+  ],
+  mutate: [
+    'src/**/*.ts',
+    '!src/**/*.test.ts',
+    '!src/**/*.d.ts',
+  ],
+  thresholds: {
+    high: 90,
+    low: 70,
+    break: 80,
+  },
+})
+```
+
+Run mutation testing:
+
+```bash
+pnpm exec stryker run
+```
+
+## Zero-Plugin Built-in Runners
+
+### 1. Shell Command Runner (`testRunner: 'command'`)
+
+Execute any test suite without extra plugins:
+
+```ts
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
+
+export default defineConfig({
+  testRunner: 'command',
+  commandRunner: {
+    command: 'npm test',
+  },
+  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
+})
+```
+
+### 2. In-Memory V8 VM Runner (`testRunner: 'vm'`)
+
+Run pure unit tests directly inside Node's native V8 VM with zero process spawning overhead:
+
+```ts
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
+
+export default defineConfig({
+  testRunner: 'vm',
+  testFiles: ['test/**/*.test.ts'],
+  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
+})
+```
+
+## Configuration API (`@systemfsoftware/stryker-js/config`)
+
+The `./config` subpath exports lightweight, inert TypeScript configuration helpers:
+
+```ts
+import { defineConfig, mergeConfig } from '@systemfsoftware/stryker-js/config'
+```
+
+### `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
-import { Mutant, ReporterEventSchema, StrykerOptionsSchema } from '@systemfsoftware/stryker-js'
+export default defineConfig(({ isCi, command }) => ({
+  testRunner: 'vitest',
+  plugins: [import.meta.resolve('@systemfsoftware/stryker-js-vitest-runner')],
+  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
+  concurrency: isCi ? 2 : 4,
+}))
 ```
 
+### `mergeConfig(base, overrides)`
+
+Deeply merges configuration presets. Keys in records merge recursively; scalar values and arrays in `overrides` completely replace base values:
+
+```ts
+import { mergeConfig } from '@systemfsoftware/stryker-js/config'
+import baseConfig from './stryker.base.config.ts'
+
+export default mergeConfig(baseConfig, {
+  concurrency: 8,
+  mutate: ['packages/core/src/**/*.ts'],
+})
+```
+
+## CLI Usage and Flags
+
+```bash
+# Run mutation testing
+pnpm exec stryker run [options]
+
+# Mutate specific files only
+pnpm exec stryker run --mutate "src/auth/*.ts"
+
+# Re-test only surviving mutants from prior run
+pnpm exec stryker run --survivors
+
+# Enable incremental caching
+pnpm exec stryker run --incremental
+
+# Run with specific concurrency
+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"
+```
+
+## Programmatic API
+
+### Effect 4 Native Interface
+
+```ts
+import { NodeRuntime } from '@effect/platform-node'
+import { strykerCell } from '@systemfsoftware/stryker-js'
+
+NodeRuntime.runMain(strykerCell({
+  mutate: ['src/**/*.ts'],
+  testRunner: 'command',
+}))
+```
+
+### Vanilla Promise Interface (`./promises`)
+
+For non-Effect environments:
+
+```ts
+import { run } from '@systemfsoftware/stryker-js/promises'
+
+const verdict = await run({
+  testRunner: 'command',
+  commandRunner: { command: 'pnpm test' },
+})
+
+console.log(`Mutation score: ${verdict.score}%`)
+```
+
+## Published Subpaths
+
+| Subpath               | Description                                                                  |
+| --------------------- | ---------------------------------------------------------------------------- |
+| `.`                   | Main entry point: `strykerCell`, runtime layers, and error schemas           |
+| `./config`            | `defineConfig`, `mergeConfig`, and `StrykerConfig` typing                    |
+| `./promises`          | `run()` wrapper returning standard JavaScript promises                       |
+| `./builtin-reporters` | Built-in reporter implementations (`clear-text`, `progress`, `json`, `html`) |
+| `./plugin-loader`     | Worker entry resolution and plugin discovery                                 |
+
 ## License
 
-Apache-2.0. Part of [systemfsoftware](https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/stryker-js/stryker-js#readme).
+[Apache-2.0](../../LICENSE)