@systemfsoftware/stryker-js-instrumenter 8.0.2 → 9.0.0

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # @systemfsoftware/stryker-js-instrumenter
 
+## 9.0.0
+
+### Major Changes
+
+- Mutant ids, mutator names and file names are now branded schemas, and the string helpers are replaced by codecs.
+
+  - Build ids and names with `MutantId`, `MutatorName` and `CanonicalFileName`. Empty values are refused.
+  - Replace `errorToString` with `ErrorText.fromCause` and `causeText` with `CauseText.fromCause`. Both return an `Option`.
+  - Replace `normalizeFileName` with a `CanonicalFileName` decode, and `isMutant` with `Schema.is(Mutant)`.
+  - Read the values formerly in `INSTRUMENTER_CONSTANTS` from the `InstrumenterContext` statics.
+
+- Each package's main entry point now groups its exports into namespaces named after a capability, such as `Plugin`, `TestRunner` and `Report`.
+
+  - Import the namespace and qualify each name, for example `Plugin.TestRunnerRpcs` after importing `Plugin` from the plugin interface.
+  - Import instrumenter schemas such as `Location` and `MutantStatus` from the instrumenter's `Mutant` namespace, and plugin-interface names from the plugin interface, instead of through another package's entry point.
+  - The engine's `/config`, `/events` and `/promises` entry points are unchanged.
+
+- HTML templates and Svelte components are no longer instrumented by this package
+  on their own: each format now comes from its framework plugin, the Angular
+  plugin for `.html`, `.htm`, and `.vue` and the Svelte plugin for `.svelte`, both
+  published alongside this release. Install the plugin whose format your project
+  uses and add it to `plugins`. A file whose extension no loaded format claims is
+  reported in the run's skipped files instead of being instrumented, and `svelte`
+  is no longer an optional peer dependency of this package; the
+  `angular-html-parser` dependency moves to the Angular plugin.
+
+  The Angular signal ignore rule is unaffected and continues to ship in
+  `@systemfsoftware/stryker-ignorer-angular`.
+
+- The format registry can now be extended with a framework plugin's contribution:
+  `frameworkEntryOf` adapts a `Framework` into a registry entry whose parse,
+  transform, print, and disable-type-checks hooks delegate to the plugin over its
+  embedded document, and the AST union gains the embedded-document variant those
+  entries parse to.
+
+  A registry entry you build yourself must now declare the `owner` module of its
+  format, the `ownerVersion` incremental state keys on, and a `transform` hook; an
+  entry without them no longer type-checks.
+
+### Patch Changes
+
+- Every mutant now reports its position as 1-based coordinates — the base the
+  mutation-testing report schema uses, where the first line of a file and the
+  first character of a line both sit at the first position.
+
+  A mutant in a plain TypeScript or JavaScript file previously reported a line one
+  below its real position, so pointing a reader at the reported coordinates
+  highlighted the wrong line.
+
+## 8.1.0
+
+### Minor Changes
+
+- Three opt-in mutators plant Effect concurrency faults on top of the default set, so a mutation run can check that your concurrency tests catch races. `AtomicUpdateSplit` splits read-modify-write calls on `Ref` and `SynchronizedRef` into a separate read, a yield, and a separate write. `SynchronizationRemoval` removes semaphore permits, `Effect.uninterruptible`, and `Effect.uninterruptibleMask`. `FinalizerEscape` stops `ensuring`, `onExit`, `onError`, `onInterrupt`, `acquireRelease`, and `acquireUseRelease` cleanup from running on interruption. All three are off by default. Enable any subset by listing them under `mutator: { optInMutations: [...] }` in your configuration. A name that is not an opt-in mutator fails the run, and the error lists the known names. The replacements use Effect 4 APIs, so a repository on Effect 3.x must not opt in.
+
+### Patch Changes
+
+- Disable comments with the `next-line` scope now ignore the mutants on the line directly below the comment and record the given reason. Before this fix they ignored nothing.
+
 ## 8.0.2
 
 ### Patch Changes

package/README.md

@@ -16,6 +16,26 @@ pnpm add @systemfsoftware/stryker-js-instrumenter
 
 The instrumenter is used internally by the Stryker mutation testing framework to instrument source files with mutant coverage and switching logic.
 
+File formats resolve through a format registry: `coreFormatRegistry` carries the built-in `js`/`ts`/`tsx` entries, `frameworkEntryOf` adapts a framework's `Framework` object into an entry, and `registerEntries` folds additions into a registry (an extension already claimed stays with the earlier entry). `instrument(files, options, registry)` and `disableTypeChecks(file, registry)` accept that registry — defaulting to the core one — and `instrument` returns the files it skipped because no entry claimed their extension.
+
+## Opt-in mutators
+
+Three mutators that plant Effect concurrency faults are available on request and stay out of the default set. Enable any subset in your Stryker config:
+
+```json
+{
+  "mutator": {
+    "optInMutations": ["AtomicUpdateSplit", "SynchronizationRemoval", "FinalizerEscape"]
+  }
+}
+```
+
+- **AtomicUpdateSplit** turns read-modify-write calls such as `Ref.update` or `SynchronizedRef.modify` into a separate read, a yield, and a separate write, so an interleaved mutation can lose an update.
+- **SynchronizationRemoval** drops the guarding effect of `Semaphore.withPermits`/`withPermit` and `Effect.uninterruptible`, letting code that assumed exclusivity or uninterruptibility run without it.
+- **FinalizerEscape** weakens `Effect.ensuring`, `Effect.onExit`, `Effect.onError`, and `Effect.onInterrupt` so their cleanup no longer runs on interruption.
+
+Naming a mutator that does not exist fails the run and lists the names that do. The replacements these mutators plant use Effect 4 APIs, so a repository on Effect 3.x must not opt in.
+
 ## License
 
 Apache-2.0. Part of [systemfsoftware](https://github.com/systemfsoftware/stryker-js-effect/tree/main/packages/stryker-js-instrumenter#readme).