Mutation-test the source lines a chunk changes with mutation-tests/run.sh

AGENTS.md

@@ -116,6 +116,8 @@ holes through each other's lines.
 generators and run parameters properties share live in `src/conformance/property-harness.ts`,
 outside the build and coverage.
 
+A review mutation-tests a chunk with `mutation-tests/run.sh` rather than setting Stryker up by hand.
+
 Each `- ` bullet in `spec/flavour.md`'s `## Block nodes`, `## Inline nodes` and `## Marks` declares
 the nodes named before its first em dash, with the attributes following `Attributes: ` — a
 parenthesized value set reading `string`; fenced examples are skipped. Keep prose out of a bullet.

README.md

@@ -194,6 +194,7 @@ Nothing throws. `code` is from a closed list, so a `switch` with no `default` co
 - [The guarantees](#the-guarantees)
 - [The package](#the-package)
 - [Everything exported](#everything-exported)
+- [Changing the source](#changing-the-source)
 - [Links](#links)
 
 ## Goals
@@ -726,6 +727,14 @@ Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/do
 | `losslessMarkdownToAdf` | function | the lossless flavour to ADF |
 | `portableMarkdownToAdf` | function | portable markdown to ADF |
 
+## Changing the source
+
+Both commands need only Docker, git and bash 5.
+
+- `./ci.sh` runs the gate: every check CI runs.
+- `./mutation-tests/run.sh [<base>]` mutation-tests the source lines changed since `<base>`,
+  `origin/main` by default, running each mutant against only the test files that reach it.
+
 ## Links
 
 - [Changelog](https://github.com/larvit/adf-codec/blob/main/CHANGELOG.md)

mutation-tests/package.json

@@ -0,0 +1,7 @@
+{
+  "private": true,
+  "devDependencies": {
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/tap-runner": "10.1.1"
+  }
+}

mutation-tests/run.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+source ./docker-runner.sh
+
+base=$(git merge-base "${1:-origin/main}" HEAD)
+# Each hunk's added lines as path:first-last, in the working tree's numbering; a hunk that only deletes has none to mutate.
+mutate=$(git diff -U0 --no-color "$base" -- 'src/*.ts' ':!src/*.test.ts' ':!src/conformance/property-harness.ts' | awk '
+  /^\+\+\+ / { path = substr($2, 3) }
+  /^@@ / {
+    split($3, added, ",")
+    first = substr(added[1], 2)
+    count = (2 in added) ? added[2] : 1
+    if (count > 0) { printf "%s%s:%d-%d", separator, path, first, first + count - 1; separator = "," }
+  }')
+if [ -z "$mutate" ]; then
+  echo "no source line changed since $base"
+  exit 0
+fi
+
+leg "install ($node_image)" in_image "$node_image" sh -c 'npm ci --no-audit --no-fund && npm ci --no-audit --no-fund --prefix mutation-tests'
+leg "mutation tests ($node_image)" in_image "$node_image" mutation-tests/node_modules/.bin/stryker run mutation-tests/stryker.config.mjs --mutate "$mutate"

mutation-tests/stryker.config.mjs

@@ -0,0 +1,12 @@
+export default {
+  // A test file peaks near 2.6 GB: past four workers a 6 GB container kills some, and a killed worker's mutant reads as an error, hiding a survivor.
+  concurrency: 4,
+  coverageAnalysis: 'perTest',
+  ignorePatterns: ['/browser-tests', '/converter-comparison', '/dist', '/mutation-tests', '/package-tests'],
+  reporters: ['clear-text', 'progress-append-only'],
+  tap: { testFiles: ['src/**/*.test.ts'] },
+  tempDirName: '/tmp/stryker',
+  testRunner: 'tap',
+  // TypeScript 7 has no JavaScript API for Stryker's tsconfig rewrite to call; a file that is not there skips it.
+  tsconfigFile: 'no-tsconfig.json',
+}