@systemfsoftware/stryker-js 4.0.0 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @systemfsoftware/stryker-js
 
+## 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,80 @@
-# @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 Stryker mutation testing tool: the `stryker` executable, the run engine it
+drives, and the configuration surface a project writes its options against.
 
 ## Install
 
-```sh
-pnpm add @systemfsoftware/stryker-js
+```bash
+pnpm add -D @systemfsoftware/stryker-js
 ```
 
-## Entry point
+## Configure
 
-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:
+```ts
+// stryker.config.ts
+import { defineConfig } from '@systemfsoftware/stryker-js/config'
+
+export default defineConfig(({ isCi }) => ({
+  testRunner: 'vitest',
+  plugins: ['@systemfsoftware/stryker-js-vitest-runner'],
+  mutate: ['src/**/*.ts', '!src/**/*.test.ts'],
+}))
+```
+
+`defineConfig` is an identity function: it preserves literal types and accepts
+an object, a promise, or a function receiving `ConfigEnv` (`command`,
+`isDryRun`, `mode`, `isCi`). `mergeConfig` composes a preset with overrides —
+records merge key by key, and a scalar or array (the default plugin globs among
+them) replaces the default outright.
+
+## Run
+
+```bash
+pnpm exec stryker run
+```
+
+The **`command`** runner ships in the box: it shells out to a configured command
+and reads its exit code.
+
+Projects whose suites depend on a real module graph, DOM emulation, or per-test
+coverage use the satellite `@systemfsoftware/stryker-js-vitest-runner` instead.
+
+## Program from Effect
 
 ```ts
-import { Mutant, ReporterEventSchema, StrykerOptionsSchema } from '@systemfsoftware/stryker-js'
+import { NodeRuntime } from '@effect/platform-node'
+import { strykerCell } from '@systemfsoftware/stryker-js'
+
+NodeRuntime.runMain(strykerCell({ mutate: ['src/**/*.ts'] }))
+```
+
+`strykerCell` is a lazy `Effect`, not a started promise. Callers that speak
+promises import the wrapper instead:
+
+```ts
+import { run } from '@systemfsoftware/stryker-js/promises'
+
+const report = await run({ testRunner: 'command' })
 ```
 
+## Subpaths
+
+| Subpath               | What it is                                                        |
+| --------------------- | ----------------------------------------------------------------- |
+| `.`                   | Programmatic surface: Effect cells, layers and the run vocabulary |
+| `./config`            | `defineConfig`, `mergeConfig`, `ConfigEnv`, `StrykerConfig`       |
+| `./promises`          | `run` — the same run, interpreted for promise callers             |
+| `./builtin-reporters` | The built-in reporter factories                                   |
+| `./plugin-loader`     | Plugin discovery and worker-entry resolution                      |
+
+## Related
+
+- [`@systemfsoftware/stryker-js-instrumenter`](../stryker-js-instrumenter) — AST mutation and the mutant vocabulary
+- [`@systemfsoftware/stryker-js-plugin-interface`](../stryker-js-plugin-interface) — the plugin boundary: RPC groups, payload schemas, typed failures
+- [`@systemfsoftware/stryker-js-vitest-runner`](../stryker-js-vitest-runner) — the Vitest-backed test runner
+- [`@systemfsoftware/stryker-js-html-reporter`](../stryker-js-html-reporter) — the HTML report
+
 ## License
 
-Apache-2.0. Part of [systemfsoftware](https://github.com/systemfsoftware/systemfsoftware/tree/main/packages/stryker-js/stryker-js#readme).
+Apache-2.0

package/dist/Plugins-sA_9VKus.d.mts

@@ -0,0 +1,96 @@
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
+import { ExitClass, WorkerPluginKind } from "@systemfsoftware/stryker-js-plugin-interface";
+import "effect/Option";
+import * as S from "effect/Schema";
+import { Schema } from "effect";
+import * as HashMap from "effect/HashMap";
+import { Ignorer } from "@systemfsoftware/stryker-ignorer-interface";
+//#region src/Run.schema.d.ts
+declare const TypeId: '~stryker/mutation-run/StageError';
+declare const StageError_base: S.Class<StageError, S.TaggedStruct<"StageError", {
+  readonly stage: S.Literals<readonly ["prepare", "instrument", "dryRun", "dryRunNoTests", "mutationTest"]>;
+  readonly reason: S.String;
+  readonly cause: S.optional<S.Defect>;
+  readonly command: S.optional<S.String>;
+}>, import("effect/Cause").YieldableError>;
+declare class StageError extends StageError_base {
+  readonly [TypeId]: "~stryker/mutation-run/StageError";
+  get exitClass(): ExitClass;
+  get message(): string;
+}
+//#endregion
+//#region src/Plugins.schema.d.ts
+declare const PluginNotFoundError_base: Schema.Class<PluginNotFoundError, Schema.TaggedStruct<"PluginNotFoundError", {
+  readonly descriptor: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+declare class PluginNotFoundError extends PluginNotFoundError_base {
+  readonly exitClass: 'ConfigError';
+}
+declare const PluginLoadFailedError_base: Schema.Class<PluginLoadFailedError, Schema.TaggedStruct<"PluginLoadFailedError", {
+  readonly descriptor: Schema.String;
+  readonly cause: Schema.Unknown;
+}>, import("effect/Cause").YieldableError>;
+declare class PluginLoadFailedError extends PluginLoadFailedError_base {
+  readonly exitClass: 'InternalError';
+}
+//#endregion
+//#region src/Plugins.d.ts
+type PluginKind = WorkerPluginKind | 'Evaluator';
+interface WorkerPluginDescriptor<K extends WorkerPluginKind = WorkerPluginKind> {
+  readonly kind: K;
+  readonly name: string;
+  readonly workerEntry: string;
+}
+interface EvaluatorPluginDescriptor {
+  readonly kind: 'Evaluator';
+  readonly name: string;
+}
+type AnyWorkerPluginDescriptor = { [K in WorkerPluginKind]: WorkerPluginDescriptor<K>; }[WorkerPluginKind];
+type AnyPluginDescriptor = AnyWorkerPluginDescriptor | EvaluatorPluginDescriptor;
+type PluginDescriptorOf<K extends PluginKind> = Extract<AnyPluginDescriptor, {
+  readonly kind: K;
+}>;
+type PluginDescriptor<K extends PluginKind = PluginKind> = PluginDescriptorOf<K>;
+interface WorkerPluginSource<K extends WorkerPluginKind = WorkerPluginKind> {
+  readonly kind: K;
+  readonly name: string;
+  readonly modulePath: string;
+  readonly workerEntry: string;
+}
+interface EvaluatorPluginSource {
+  readonly kind: 'Evaluator';
+  readonly name: string;
+  readonly modulePath: string;
+}
+type AnyWorkerPluginSource = { [K in WorkerPluginKind]: WorkerPluginSource<K>; }[WorkerPluginKind];
+type PluginSource = AnyWorkerPluginSource | EvaluatorPluginSource;
+interface PluginLoaderEntryLike {
+  readonly moduleName: string;
+  readonly plugins: readonly PluginDescriptor[] | undefined;
+  readonly schemaContribution: Record<string, unknown> | undefined;
+}
+interface PluginLoadPlan {
+  readonly schemaContributions: readonly Record<string, unknown>[];
+  readonly pluginsByKind: HashMap.HashMap<PluginKind, readonly PluginDescriptor[]>;
+  readonly pluginModulePaths: readonly string[];
+  readonly pluginSources: readonly PluginSource[];
+  readonly shadowings: readonly {
+    readonly kind: PluginKind;
+    readonly name: string;
+    readonly shadowedIndex: number;
+    readonly winnerIndex: number;
+  }[];
+}
+interface LoadedPlugins {
+  readonly schemaContributions: readonly Record<string, unknown>[];
+  readonly pluginsByKind: HashMap.HashMap<PluginKind, readonly PluginDescriptor[]>;
+  readonly pluginModulePaths: readonly string[];
+  readonly pluginSources: readonly PluginSource[];
+  readonly ignorers: readonly Ignorer[];
+}
+declare function loadPlugins(pluginDescriptors: readonly string[]): Effect.Effect<LoadedPlugins, PluginLoadFailedError, Path.Path>;
+declare function create<K extends PluginKind>(pluginsByKind: HashMap.HashMap<PluginKind, readonly AnyPluginDescriptor[]>, kind: K, name: string): Effect.Effect<PluginDescriptorOf<K>, PluginNotFoundError>;
+declare function createAll<K extends PluginKind>(pluginsByKind: HashMap.HashMap<PluginKind, readonly AnyPluginDescriptor[]>, kind: K): Effect.Effect<readonly PluginDescriptorOf<K>[]>;
+//#endregion
+export { PluginLoadPlan as a, create as c, PluginLoadFailedError as d, PluginNotFoundError as f, PluginKind as i, createAll as l, PluginDescriptor as n, PluginLoaderEntryLike as o, StageError as p, PluginDescriptorOf as r, PluginSource as s, LoadedPlugins as t, loadPlugins as u };