@systemfsoftware/stryker-js 13.0.0 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @systemfsoftware/stryker-js
 
+## 14.0.0
+
+### Major Changes
+
+- The incremental cache now reuses a verdict only when nothing that could change it has changed: the covering tests and every module they import, the run inputs (lockfile and configuration), and the mutant-set policy. Moving code or releasing a new version no longer throws the cache away. Incremental reports written by earlier versions are discarded once.
+
+  A mutant whose covering tests did not run is retried once, then reported as `RuntimeError` with reason `no covering test executed`.
+
+  The new `mutator.mutantSetPolicy` option defaults to `'default'`. Under it, mutants in logging, telemetry, timing, and configuration-default calls, redundant relational variants, and replacements identical to the original are reported as `Ignored` with a named rule instead of being run. Set `mutator.mutantSetPolicy: 'full'` to keep the previous mutant set.
+
+### Minor Changes
+
+- The new `annotate` command prints GitHub workflow annotations at the location of every survivor of the finished report, so a run's survivors show up on the changed lines of a pull request.
+
+- The new `compare` command names every mutant whose status differs between a baseline report and a fresh one, leaving out the mutant ids passed with `--noise`.
+
+- `stryker feedback <id> --useful|--not-useful [--reason <text>]` appends one `feedback` stream line for a surfaced survivor to reports/mutation/feedback.jsonl.
+
+- The new `gate` command fails when a run leaves survivors that are missing from a committed baseline of accepted survivors, lists them with how to accept them, and `--update-baseline` rewrites the baseline from the finished report.
+
+- `stryker mcp` serves the finished mutation report to MCP clients over stdio, with tools `list_survivors`, `show_mutant`, `rerun_mutant`, and `report_usefulness`.
+
+- Serving the Mutation Server Protocol over stdio and sockets lets editors and agents configure, discover, and mutation-test a project through framed JSON-RPC, with one run at a time, a loopback-only default listener, and named errors for an unusable bind.
+
+- Every run now also writes a reproducer for each mutant: a unified diff against the original source, so a verdict can be re-checked locally without hunting for which mutation produced it.
+
+- Naming mutant ids on the run command re-runs exactly those mutants, restricting the mutated files to their ids' files with verdict reuse left on and reporting each selected mutant's status, covering tests, killing test, and reproducer command, while the trace names the new rerun span for that path.
+
+- The new `sarif` reporter writes a SARIF 2.1.0 log beside the JSON report with one result per capped survivor, each carrying its mutant id in `partialFingerprints` so code scanning can track it.
+
+- The new `--since <ref>` option mutates only the lines changed since the merge base with `<ref>`, and falls back to a full run when the Stryker config, a test-runner config, the package manifest, or the lockfile changed.
+
+- The clear-text report adds a `Static mutants:` line with how many mutants are static and their share of the total mutant cost.
+
+- The new `surfacing` option (default `{ perLine: 1, perFile: 7 }`) caps how many survivors are listed per line and per file, while every survivor still counts toward the score.
+
+- With `--incremental`, an unchanged project now skips the initial test run; that run otherwise executes the suite twice to find flaky tests, and a verdict that depends on a flaky test, or any static mutant while a test is flaky, is re-tested instead of reused.
+
+### Patch Changes
+
+- With checkers configured, a mutant is sent to a test runner as soon as its own check group passes instead of waiting for earlier groups, so `mutant` events can arrive out of plan order while the final report keeps plan order.
+
+- Incremental runs no longer hold a test runner while the checkpoint is rewritten after every mutant; the checkpoint is written in the background at most once per second, and an interrupted run still keeps every mutant it finished.
+
+- Fixed a rare hang where a run stopped making progress while a test runner or checker worker waited for a message that had already arrived. The message now always wakes the worker waiting for it.
+
+- Repeating an incremental run with no source change now reuses every verdict in a project that defines no ignore patterns of its own: a run's own reports are no longer treated as changed inputs, and options that cannot change a verdict no longer invalidate reuse — neither the ones that only select which mutants and tests run (a git ref scope, a single mutant id) nor reporting and logging options such as reporters, colors, thresholds, surfacing or log levels.
+
+- A re-tested mutant now runs the test file of its previous killing test first, and mutation reports keep naming the right killing test after tests are added or reordered.
+
+- Incremental runs now reuse verdicts written under a different `incrementalFile`, `incrementalSources`, `tempDirName` or `cleanTempDir`, so a shard can reuse the verdicts another shard recorded for a file that moved between shards.
+
+- Changing only the version in a package manifest that tests import no longer invalidates the incremental verdicts of those tests, so releasing a package keeps its cached mutation results.
+
+## 13.1.0
+
+### Minor Changes
+
+- The `stryker` CLI now continues a caller's trace: when `TRACEPARENT` (and optionally `TRACESTATE`) is set in its environment, the `stryker.cli.run` span and everything beneath it join that trace as a child of the carried span, following the OpenTelemetry environment-carrier specification. An absent or malformed `TRACEPARENT` leaves the run on its own root trace, as before.
+
+### Patch Changes
+
+- The packages now depend on `@systemfsoftware/effect-cell-types` 11.
+
+  - Every tagged error now has a one-line message built from its fields, so a failure names the file, mutant, plugin, worker or exit code involved instead of an empty message. The errors' tags, fields and encoded forms are unchanged.
+
 ## 13.0.0
 
 ### Major Changes

package/README.md

@@ -144,6 +144,12 @@ pnpm exec stryker run [options]
 # Mutate specific files only
 pnpm exec stryker run --mutate "src/auth/*.ts"
 
+# Scope the run to lines changed since a git ref
+pnpm exec stryker run --since origin/main
+
+# Re-run named mutants from the previous report
+pnpm exec stryker run --mutant <id,...>
+
 # Re-test only surviving mutants from prior run
 pnpm exec stryker run --survivors
 
@@ -155,8 +161,24 @@ pnpm exec stryker run --concurrency 4
 
 # Merge partial mutation reports from parallel CI shards
 pnpm exec stryker merge-reports --parts reports/shards --out reports/mutation
+
+# Fail on survivors absent from a committed baseline
+pnpm exec stryker gate --baseline .stryker-baseline.json
+
+# Name every mutant whose status differs between two reports
+pnpm exec stryker compare --baseline reports/mutation-report.json --fresh reports/fresh.json
+
+# Annotate a pull request at each surfaced survivor
+pnpm exec stryker annotate --baseline .stryker-baseline.json
+
+# Judge one surfaced survivor, or drive runs from an editor or an agent
+pnpm exec stryker feedback <id> --not-useful --reason "logging only"
+pnpm exec stryker serve stdio
+pnpm exec stryker mcp
 ```
 
+`stryker run --since <ref>` takes the merge base of `<ref>` and the working tree, diffs it at `--unified=0`, and intersects the changed lines with `mutate`; it falls back to a full run when the Stryker config, a test-runner config, `package.json`, or the lockfile changed. `stryker run --mutant <id,...>` admits each id against the previous report (`reports/mutation/mutation.json`), restricts the run to those mutants' files, and emits each one's status, covering tests, killing test, and a `stryker run --mutant <id>` reproducer. `stryker gate` exits non-zero on survivors missing from its baseline, `stryker compare` exits `1` on a status mismatch after subtracting a `--noise` file, and `stryker annotate` prints GitHub workflow commands at each surfaced survivor. `stryker serve stdio|socket` speaks the Mutation Server Protocol and `stryker mcp` serves MCP over stdio.
+
 ## Output Modes
 
 Human output is the default, whether or not `stdout` is a terminal. A machine consumer opts into the NDJSON event stream explicitly:
@@ -168,6 +190,14 @@ 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.
 
+## Reporters, Sidecars, and Verdict Reuse
+
+`reporters` defaults to `['clear-text', 'progress', 'html']`. Add `sarif` to also write `reports/mutation/mutation.sarif` (SARIF 2.1.0, named from `jsonReporter.fileName`): each survivor is a `warning` result, each no-coverage mutant a `note`, the fingerprint is the mutant's content id, and the log is capped at 5,000 results. Every run writes `reports/mutation/reproducers.json`: one entry per mutant in the report, holding its mutated-lines diff and the `stryker run --mutant <id>` command that reproduces it.
+
+The incremental cache is keyed by content: a mutant's id, the import-closure digest of its covering tests, the run inputs, the verdict-semantics version, and the mutant-set policy. Nothing in the key names a shard, branch, report path, or machine, so verdicts from different runs union and are reused wherever their inputs match. `incrementalSources` accepts globs of further incremental reports to union beside `incrementalFile`, which is how a sharded CI workspace reuses the reports it restored from other shards. Each run's stream carries a `reuse` line with the reused, ran, and per-reason refused counts, and an unchanged project reuses its persisted initial test run instead of repeating it.
+
+`mutator.mutantSetPolicy` defaults to `'default'`, which suppresses the mutants a rule proves redundant — a relational replacement outside the sufficient set, a conditional that collapses to a literal, a replacement equal to the original code, or a duplicate already planted at the site — and records the rule id in the mutant's report entry. Set `mutator: { mutantSetPolicy: 'full' }` to keep every variant. `surfacing` (`{ perLine: 1, perFile: 7 }`) caps how many survivors reach the review surfaces and SARIF, without changing what the engine computes.
+
 ## Programmatic API
 
 ### Effect 4 Native Interface

package/dist/Run.schema-DErVOVSj.d.mts

@@ -0,0 +1,24 @@
+import { a as mod_d_exports$6 } from "./index-C5FRZ4Ni.mjs";
+import * as S from "effect/Schema";
+//#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(): mod_d_exports$6.ExitClass;
+  get message(): string;
+}
+declare const PrepareError_base: S.Class<PrepareError, S.TaggedStruct<"PrepareError", {
+  readonly stage: S.Literal<"prepare">;
+  readonly reason: S.String;
+}>, import("effect/Cause").YieldableError>;
+declare class PrepareError extends PrepareError_base {
+  get message(): string;
+}
+//#endregion
+export { StageError as n, PrepareError as t };

package/dist/Run.schema-DuaneDGd.mjs

@@ -0,0 +1,57 @@
+import * as S from "effect/Schema";
+import * as Match from "effect/Match";
+//#region src/Run.schema.ts
+const TypeId = "~stryker/mutation-run/StageError";
+var StageError = class extends S.TaggedError(TypeId)("StageError", {
+	stage: S.Literals([
+		"prepare",
+		"instrument",
+		"dryRun",
+		"dryRunNoTests",
+		"mutationTest"
+	]),
+	reason: S.String,
+	cause: S.optional(S.Defect()),
+	command: S.optional(S.String)
+}) {
+	[TypeId] = TypeId;
+	get exitClass() {
+		return STAGE_PRESENTATION[this.stage].exitClass;
+	}
+	get message() {
+		const failure = `${STAGE_PRESENTATION[this.stage].label} failed: ${this.reason}`;
+		return Match.value(this.command).pipe(Match.when(Match.nonEmptyString, (present) => `${failure} (command: ${present})`), Match.orElse(() => failure));
+	}
+};
+const STAGE_PRESENTATION = {
+	prepare: {
+		label: "Prepare",
+		exitClass: "ConfigError"
+	},
+	instrument: {
+		label: "Instrument",
+		exitClass: "RuntimeError"
+	},
+	dryRun: {
+		label: "Dry run",
+		exitClass: "RuntimeError"
+	},
+	dryRunNoTests: {
+		label: "Dry run",
+		exitClass: "ConfigError"
+	},
+	mutationTest: {
+		label: "Mutation testing",
+		exitClass: "RuntimeError"
+	}
+};
+var PrepareError = class extends S.TaggedError()("PrepareError", {
+	stage: S.Literal("prepare"),
+	reason: S.String
+}) {
+	get message() {
+		return this.reason;
+	}
+};
+//#endregion
+export { StageError as n, PrepareError as t };