@sasjs/lint 4.3.1 → 4.3.2

package/.github/CONTRIBUTING.md

@@ -92,6 +92,51 @@ Two habits catch the failures that plain coverage does not:
 - **Mutation-check your assertions.** Revert the behaviour one piece at a time and confirm a test fails. An assertion that passes on the broken code is documenting nothing. Watch for vacuous cases: for example, a "does not throw" test over a mis-split file passes while the mis-split still contains the string being searched for, so the fixture has to be shaped to fail.
 - **A negative test must fail for the reason it names.** Assert on the specific message or error, never a bare `toThrow()`.
 
+### Mutation testing
+
+The habit above is automated, because the mutant you think to try is rarely the
+one that matters. Stryker rewrites the source in small ways (an operator, a
+string, a branch) and runs the tests; a mutant that survives is behaviour no
+test asserts.
+
+```bash
+npm run mutation:changed     # only the files this branch changed, vs the baseline
+MUTATION_FILES=src/utils/parseMacroCalls.ts npm run mutation:changed   # one file
+npm run mutation             # whatever stryker.conf.json selects
+npm run mutation:watch       # the whole tree; prints a refreshed baseline
+```
+
+The gate compares each file with `mutation-baseline.json` and fails when a file
+carries MORE surviving mutants than the baseline records, so it asks "did this
+branch add an untested behaviour?", not "is the repo perfect yet". A file with no
+baseline must reach 80%. `mutation-pr.yml` runs the changed-file gate on every
+pull request; `mutation-weekly.yml` runs the whole tree and fails if anything
+regressed, which is how the baseline is refreshed (the run prints the new JSON to
+paste in).
+
+Two things to know before running it:
+
+- the dev tree needs Node 22.18 or newer: `@stryker-mutator/core` pulls `@babel/*` 8,
+  whose `engines` start at 22.18. `package.json` records that in `devEngines` (dev installs
+  warn, published installs are unaffected - the tarball carries no devDependencies).
+
+
+- `jest.stryker.config.js` differs from `jest.config.js` in switching coverage
+  off, and in nothing else: a skipped spec records the mutants it covers as
+  legitimate survivors, and the weekly refresh writes them into the baseline.
+  `isIgnored` therefore derives its path with `path.relative(root, file)` and
+  returns false for a path outside the root, and `isIgnored.spec.ts` pins
+  `getProjectRoot()` with a jest mock - the `ignore` package rejects an absolute
+  or `..`-prefixed path, which is what a sandbox run produced before.
+- a run mutates the file(s) in a sandbox under `.stryker-tmp`, and `jest.config.js`
+  ignores that directory by a `<rootDir>`-anchored pattern - an unanchored one
+  makes Stryker's own dry run collect nothing.
+
+A surviving mutant is either a missing test or an EQUIVALENT mutant (a change
+that cannot alter behaviour, such as dropping a check the following regular
+expression repeats). Add the spec that fails on it, or say in the PR body why it
+is equivalent - do not lower the baseline.
+
 ## Regenerating the shipped macro list
 
 The macros SAS ships are language data, owned by `@sasjs/sas-language`. Do not hand-write them here. `npm run generate:macros` reads its `macroStatements` and `macroFunctions` groups and writes `src/utils/sasMacros.generated.ts`, which is committed so the published package carries no runtime dependency. `sasMacros.spec.ts` reads the same data independently and fails when the committed list differs, which is the drift guard. Extending that vocabulary is a PR to `@sasjs/sas-language`.

package/.github/workflows/mutation-pr.yml

@@ -0,0 +1,69 @@
+name: Mutation (changed files)
+
+# Mutation testing answers a question coverage cannot: does any test FAIL when
+# the code is wrong? Stryker flips an operator or a string in the source and runs
+# the tests; a mutant that survives is behaviour nothing asserts.
+#
+# This job mutates only the source files the PR changed, and compares them with
+# mutation-baseline.json - so it asks "did this branch add an untested
+# behaviour?", not "is the repo perfect yet". The baseline is refreshed by
+# mutation-weekly.yml.
+#
+# Cost control: Stryker runs the tests that cover the mutated file
+# (`enableFindRelatedTests`), and only the mutated file is instrumented. A
+# two-file run takes minutes, not the hours a whole-suite run per mutant would.
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'jest.config.js'
+      - 'jest.stryker.config.js'
+      - 'stryker.conf.json'
+      - 'mutation-baseline.json'
+      - 'scripts/mutation-gate.mjs'
+      - 'package.json'
+      - 'package-lock.json'
+
+# a second push supersedes the first run rather than queueing behind it
+concurrency:
+  group: mutation-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  mutation:
+    runs-on: ubuntu-latest
+    # checkout needs read, and the job writes nothing else
+    permissions:
+      contents: read
+    # a changed-file run takes minutes; the default cap is six hours, which would
+    # hold a runner on a stuck mutation run
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # the diff against the base commit needs the base commit
+          fetch-depth: 0
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Mutate the changed files
+        env:
+          MUTATION_BASE: ${{ github.event.pull_request.base.sha }}
+        run: node scripts/mutation-gate.mjs pr
+
+      - name: Keep the report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-report
+          path: reports/mutation/mutation.json
+          if-no-files-found: ignore

package/.github/workflows/mutation-weekly.yml

@@ -0,0 +1,92 @@
+name: Mutation Watch
+
+# The per-PR mutation gate compares a branch's changed files with a baseline, so
+# the baseline is the thing that has to stay honest: if it is never refreshed,
+# files that improve keep their old count and the gate stops asking for more.
+#
+# This runs the whole source tree weekly, prints the new baseline, and fails when
+# any file carries MORE surviving mutants than the recorded one - which means a
+# PR was merged without the gate seeing it (a push to main, a config change, a
+# file the gate skipped). Failure files an issue, as audit-watch.yml does, and
+# only a genuine regression does so.
+
+on:
+  schedule:
+    - cron: '0 7 * * 1' # Mondays, 07:00 UTC
+  workflow_dispatch:
+
+jobs:
+  watch:
+    runs-on: ubuntu-latest
+    # the whole tree takes ~20-30 minutes; bounded so a hang cannot hold a runner
+    # for the six-hour default
+    timeout-minutes: 90
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Mutate the whole source tree
+        id: watch
+        env:
+          MUTATION_WATCH_REPORT: ${{ runner.temp }}/mutation-watch-report.md
+        run: node scripts/mutation-gate.mjs weekly
+
+      - name: Keep the report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: mutation-watch-report
+          path: |
+            reports/mutation/mutation.json
+            ${{ runner.temp }}/mutation-watch-report.md
+          if-no-files-found: ignore
+
+  report:
+    needs: watch
+    # a failure files an issue; a cancelled run does so only when the schedule
+    # cancelled it (the 90-minute timeout), so cancelling a manual run by hand
+    # does not claim a regression that never happened
+    if: >-
+      always() &&
+      (needs.watch.result == 'failure' ||
+       (needs.watch.result == 'cancelled' && github.event_name == 'schedule'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+
+    steps:
+      - name: File an issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          title='Mutation watch: a file carries more surviving mutants than the baseline'
+          existing=$(gh issue list --state open --search "\"$title\" in:title" \
+            --json number --jq '.[0].number // empty')
+
+          if [ -n "$existing" ]; then
+            echo "already tracked in #$existing"
+            exit 0
+          fi
+
+          gh issue create --title "$title" --body \
+            "The weekly mutation run found a file carrying more surviving mutants than mutation-baseline.json records, so behaviour was merged without a test that fails on it.
+
+          The run names the file and each surviving mutant (file:line:column, mutator, replacement), and prints the refreshed baseline:
+
+          $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
+
+          Close this once a spec kills them and mutation-baseline.json is updated from that run."

package/jest.config.js

@@ -1,12 +1,61 @@
 module.exports = {
   preset: 'ts-jest',
   testEnvironment: 'node',
+  // A Stryker run keeps a sandbox under .stryker-tmp with a copy of src/ in it.
+  // Without this, any jest run that overlaps a mutation run collects every spec
+  // twice (measured: 946 tests instead of 464) and reports failures from files
+  // that are being mutated. Anchored to <rootDir> on purpose: inside the sandbox
+  // the whole project IS under .stryker-tmp, and an unanchored pattern would make
+  // Stryker's own dry run collect nothing ("No tests were executed").
+  testPathIgnorePatterns: [
+    '/node_modules/',
+    '<rootDir>/.stryker-tmp/',
+    '<rootDir>/build/'
+  ],
   coverageThreshold: {
     global: {
       branches: 80,
       functions: 80,
       lines: 80,
       statements: -10
+    },
+    // Per-path floors, so a change that hollows out one area cannot hide behind
+    // the aggregate. Every number is the coverage measured when this was written,
+    // rounded down, so the block is a ratchet: raise one when the area improves,
+    // never lower one to get a branch green. `statements` is a PERCENTAGE unless
+    // it is negative, where `-N` reads as "at most N uncovered statements" - so a
+    // plain `0` asserts nothing at all (0% coverage passes), which is why the two
+    // fully-covered areas ask for 100 and the three with known gaps carry a budget
+    // measured from the tree on the day this landed.
+    './src/utils/': {
+      branches: 95,
+      functions: 100,
+      lines: 99,
+      statements: -4
+    },
+    './src/rules/': {
+      branches: 95,
+      functions: 100,
+      lines: 100,
+      statements: 100
+    },
+    './src/lint/': {
+      branches: 85,
+      functions: 100,
+      lines: 100,
+      statements: -2
+    },
+    './src/format/': {
+      branches: 90,
+      functions: 100,
+      lines: 100,
+      statements: 100
+    },
+    './src/types/': {
+      branches: 95,
+      functions: 100,
+      lines: 96,
+      statements: -4
     }
   },
   collectCoverageFrom: ['src/**/{!(index|formatExample|lintExample),}.ts']

package/jest.stryker.config.js

@@ -0,0 +1,17 @@
+/**
+ * Jest config for Stryker runs.
+ *
+ * The only difference from jest.config.js is that coverage is off: Stryker
+ * instruments the code itself, and the coverage thresholds would fail a
+ * single-mutant run. The suite itself runs in full, so the weekly baseline is
+ * built on every test - a skipped spec here would record mutants it covers as
+ * legitimate survivors and let them into the baseline permanently.
+ */
+const base = require('./jest.config.js')
+
+module.exports = {
+  ...base,
+  collectCoverage: false,
+  coverageThreshold: undefined,
+  collectCoverageFrom: undefined
+}

package/mutation-baseline.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "Surviving-mutant counts per file, used by scripts/mutation-gate.mjs. Refresh from the output of npm run mutation:watch; raise a count only with a reason in the PR that raises it.",
+  "generatedAt": "2026-10-25T20:06:38Z",
+  "files": {
+    "src/rules/file/noUnusedMacros.ts": {
+      "score": 100.0,
+      "survived": 0,
+      "killed": 37,
+      "timeout": 0
+    },
+    "src/utils/getIndicesOf.ts": {
+      "score": 100.0,
+      "survived": 0,
+      "killed": 15,
+      "timeout": 6
+    },
+    "src/utils/isIgnored.ts": {
+      "score": 100.0,
+      "survived": 0,
+      "killed": 25,
+      "timeout": 0
+    },
+    "src/utils/parseMacroCalls.ts": {
+      "score": 92.98,
+      "survived": 25,
+      "killed": 293,
+      "timeout": 38
+    }
+  }
+}

package/package.json

@@ -12,7 +12,10 @@
     "publishInit": "cp -r ./build/* . && rm -rf ./build && rm -rf ./src && rm tsconfig.json",
     "package:lib": "npm run build && cp ./package.json ./checkNodeVersion.js build && cp README.md build && cd build && npm version \"5.0.0\" && npm pack",
     "lint:fix": "npx prettier --write \"{src,test}/**/*.{ts,tsx,js,jsx,html,css,sass,less,json,yml,md,graphql}\"",
-    "lint": "npx prettier --check \"{src,test}/**/*.{ts,tsx,js,jsx,html,css,sass,less,json,yml,md,graphql}\""
+    "lint": "npx prettier --check \"{src,test}/**/*.{ts,tsx,js,jsx,html,css,sass,less,json,yml,md,graphql}\"",
+    "mutation": "stryker run",
+    "mutation:changed": "node scripts/mutation-gate.mjs pr",
+    "mutation:watch": "node scripts/mutation-gate.mjs weekly"
   },
   "publishConfig": {
     "access": "public"
@@ -62,6 +65,8 @@
   "devDependencies": {
     "@nogoo9/gitleaks": "8.30.1-post.2",
     "@sasjs/sas-language": "0.3.0",
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/jest-runner": "10.1.1",
     "@types/jest": "30.0.0",
     "@types/node": "26.6.3",
     "jest": "30.5.2",
@@ -73,5 +78,12 @@
     "@sasjs/utils": "4.0.0",
     "ignore": "7.0.11"
   },
-  "version": "4.3.1"
+  "version": "4.3.2",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18",
+      "onFail": "warn"
+    }
+  }
 }

package/scripts/mutation-gate.mjs

@@ -0,0 +1,390 @@
+// Runs mutation testing over the files a branch changed, and fails when a file
+// carries more surviving mutants than the recorded baseline.
+//
+//   node scripts/mutation-gate.mjs pr        # changed files, compare to baseline
+//   node scripts/mutation-gate.mjs weekly    # whole src, print the new baseline
+//
+// Set MUTATION_FILES to run the gate on named files instead of the diff - the
+// way to check a file you are working on before committing it:
+//
+//   MUTATION_FILES=src/utils/parseMacroCalls.ts node scripts/mutation-gate.mjs pr
+//
+// A surviving mutant is a change to the code that no test noticed. The baseline
+// records how many each file already carries, so the gate asks "did this branch
+// add an untested behaviour?", not "is the repo perfect yet" - a threshold on
+// the absolute score would fail every PR until the backlog is cleared.
+import { execFileSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+const BASELINE_FILE = 'mutation-baseline.json'
+const REPORT_FILE = 'reports/mutation/mutation.json'
+const NEW_FILE_FLOOR = 80
+const BASELINE_COMMENT =
+  'Surviving-mutant counts per file, used by scripts/mutation-gate.mjs. Refresh from the output of npm run mutation:watch; raise a count only with a reason in the PR that raises it.'
+
+const mode = process.argv[2] || 'pr'
+
+/**
+ * The baseline to police a branch against.
+ *
+ * With a ref, this is the copy on the BASE branch, read out of git rather than
+ * taken from the working tree: the file travels inside the PR, so a branch that
+ * raises the number it is measured against would otherwise pass, and the weekly
+ * watch - which compares against the merged value - would never fire either.
+ */
+const readBaseline = (ref) => {
+  if (ref) {
+    // A ref that cannot be resolved (a shallow clone, a typo) must fail loudly:
+    // swallowing it drops the run to the new-file floor and reports green, which
+    // is the same fail-open the changedFiles() handler refuses.
+    try {
+      execFileSync(
+        'git',
+        ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+        {
+          stdio: ['ignore', 'ignore', 'ignore']
+        }
+      )
+    } catch (e) {
+      throw new Error(
+        `cannot resolve the base ref '${ref}' - fetch it (fetch-depth: 0 in CI) or set MUTATION_FILES`
+      )
+    }
+
+    // Does the ref carry a baseline at all? Ask git rather than reading the
+    // error text of a failed `git show`, whose wording differs by version and is
+    // empty when stderr is swallowed.
+    try {
+      execFileSync('git', ['cat-file', '-e', `${ref}:${BASELINE_FILE}`], {
+        stdio: ['ignore', 'ignore', 'ignore']
+      })
+    } catch (e) {
+      // the ref resolves but carried no baseline: the PR that adds the file
+      return null
+    }
+
+    try {
+      const raw = execFileSync('git', ['show', `${ref}:${BASELINE_FILE}`], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe']
+      })
+      return JSON.parse(raw)
+    } catch (e) {
+      const detail = (e.stderr && e.stderr.toString().trim()) || e.message
+      throw new Error(`cannot read ${BASELINE_FILE} at '${ref}': ${detail}`)
+    }
+  }
+
+  if (!fs.existsSync(BASELINE_FILE)) return { files: {} }
+  return JSON.parse(fs.readFileSync(BASELINE_FILE, 'utf8'))
+}
+
+/**
+ * The ref a branch is policed against: MUTATION_BASE when set, otherwise the
+ * merge base with origin/main, so the raise-check also fires for the documented
+ * local run (`npm run mutation:changed` with no MUTATION_BASE) instead of
+ * comparing the working copy against itself.
+ */
+const resolveBaseRef = () => {
+  if (process.env.MUTATION_BASE) return process.env.MUTATION_BASE
+  try {
+    return execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim()
+  } catch (e) {
+    return null
+  }
+}
+
+/** The source files this branch changed, relative to the base branch. */
+const changedFiles = () => {
+  const base = resolveBaseRef()
+  if (!base) {
+    console.error(
+      'Could not resolve a base ref (no MUTATION_BASE, no origin/main to merge-base against).'
+    )
+    process.exit(1)
+  }
+  let diff = ''
+  try {
+    diff = execFileSync('git', ['diff', '--name-only', `${base}...HEAD`], {
+      encoding: 'utf8'
+    })
+  } catch (e) {
+    // A broken clone or a missing base sha would otherwise look like "no files
+    // changed" and turn the gate into a green no-op.
+    console.error(`Could not diff against ${base}: ${e.message}`)
+    console.error(
+      'Fetch the base branch (fetch-depth: 0 in CI) or set MUTATION_FILES.'
+    )
+    process.exit(1)
+  }
+
+  const changed = diff
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+
+  const mutable = changed
+    .filter((line) => line.startsWith('src/'))
+    .filter((line) => line.endsWith('.ts'))
+    .filter((line) => !line.endsWith('.spec.ts'))
+    .filter((line) => fs.existsSync(line))
+
+  return { changed, mutable }
+}
+
+const runStryker = (mutate) => {
+  fs.rmSync('reports/mutation', { recursive: true, force: true })
+  execFileSync(
+    'npx',
+    ['stryker', 'run', '--mutate', mutate.join(','), '--reporters', 'json'],
+    { stdio: 'inherit' }
+  )
+  return JSON.parse(fs.readFileSync(REPORT_FILE, 'utf8'))
+}
+
+/** Per-file totals from a Stryker JSON report. */
+const summarise = (report) => {
+  const files = {}
+  for (const [name, file] of Object.entries(report.files)) {
+    const mutants = file.mutants || []
+    const survived = mutants.filter(
+      (m) => m.status === 'Survived' || m.status === 'NoCoverage'
+    )
+    const killed = mutants.filter((m) => m.status === 'Killed').length
+    const timeout = mutants.filter((m) => m.status === 'Timeout').length
+    // Ignored (a `// Stryker disable` comment) and CompileError mutants cannot be
+    // killed by any test, so counting them in the denominator reports a score
+    // below Stryker's own and can fail a file with no real survivor. NoCoverage is
+    // NOT one of them: a mutant no test executes is the untested behaviour this
+    // gate exists to catch, so it counts against the score and as a survivor.
+    const unkillable = mutants.filter(
+      (m) => m.status === 'CompileError' || m.status === 'Ignored'
+    ).length
+    const covered = mutants.length - unkillable
+    files[name] = {
+      // no covered mutants means no test even ran against this file: scoring that
+      // 100 would let a brand-new untested file pass the new-file floor
+      score:
+        covered === 0
+          ? 0
+          : Math.round(((killed + timeout) / covered) * 10000) / 100,
+      survived: survived.length,
+      killed,
+      timeout,
+      survivors: survived.map((m) => ({
+        line: m.location.start.line,
+        column: m.location.start.column,
+        mutator: m.mutatorName,
+        replacement: m.replacement,
+        status: m.status
+      }))
+    }
+  }
+  return files
+}
+
+const describeSurvivor = (file, m) =>
+  `  ${file}:${m.line}:${m.column} ${m.mutator} -> ${m.replacement}${
+    m.status === 'NoCoverage' ? '  (no test executes this line)' : ''
+  }`
+
+if (mode === 'weekly') {
+  const files = summarise(runStryker(['src/**/*.ts', '!src/**/*.spec.ts']))
+
+  const baseline = readBaseline().files || {}
+
+  // A file that reached main with no baseline entry - a push that bypassed the PR
+  // gate, or a file added before this gate existed - is not reported by a
+  // survivors-only comparison. It counts as a regression while it is below the
+  // new-file floor.
+  const regressions = Object.entries(files).filter(([name, stats]) => {
+    const known = baseline[name]
+    if (known === undefined) return stats.score < NEW_FILE_FLOOR
+    return stats.survived > known.survived
+  })
+
+  console.log('\nPer-file mutation score:')
+  for (const [name, stats] of Object.entries(files)) {
+    console.log(
+      `  ${name}: ${stats.score}% (${stats.killed} killed, ${stats.timeout} timeout, ${stats.survived} survived)`
+    )
+  }
+
+  // Printed without the per-mutant detail, so a refresh is a diff of counts
+  // rather than of every survivor's line and column. The timestamp stays: it is
+  // the field a reader uses to judge how stale the counts are.
+  const nextBaseline = {
+    _comment: BASELINE_COMMENT,
+    generatedAt: new Date().toISOString(),
+    files: Object.fromEntries(
+      Object.entries(files)
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([name, stats]) => [
+          name,
+          {
+            score: stats.score,
+            survived: stats.survived,
+            killed: stats.killed,
+            timeout: stats.timeout
+          }
+        ])
+    )
+  }
+  const printed = JSON.stringify(nextBaseline, null, 2)
+  console.log('\nUpdated baseline (commit this as mutation-baseline.json):')
+  console.log(printed)
+
+  // the weekly workflow keeps the refreshed baseline as a job artifact, so the
+  // new counts survive the log
+  if (process.env.MUTATION_WATCH_REPORT)
+    fs.writeFileSync(process.env.MUTATION_WATCH_REPORT, `${printed}\n`)
+
+  if (regressions.length) {
+    console.error('\nSurviving mutants grew since the baseline:')
+    for (const [name, stats] of regressions) {
+      const known = baseline[name]
+      console.error(
+        known === undefined
+          ? `  ${name}: no baseline entry, scores ${stats.score}% (floor ${NEW_FILE_FLOOR}%)`
+          : `  ${name}: ${known.survived} -> ${stats.survived}`
+      )
+      stats.survivors.forEach((m) => console.error(describeSurvivor(name, m)))
+    }
+    process.exit(1)
+  }
+
+  console.log('\nNo file carries more surviving mutants than the baseline.')
+  process.exit(0)
+}
+
+// A PR that changes the gate's own configuration must still exercise it, or a
+// broken config ships green: no source file changed, so the changed-file run has
+// nothing to mutate. The probe is a small file with a baseline entry.
+const PROBE_FILES = ['src/utils/getIndicesOf.ts']
+
+const WATCHED_CONFIG = [
+  'jest.config.js',
+  'jest.stryker.config.js',
+  'stryker.conf.json',
+  'mutation-baseline.json',
+  'scripts/mutation-gate.mjs',
+  'package.json',
+  'package-lock.json'
+]
+
+let mutate = []
+let configOnly = false
+
+if (process.env.MUTATION_FILES) {
+  mutate = process.env.MUTATION_FILES.split(',')
+    .map((f) => f.trim())
+    .filter(Boolean)
+} else {
+  const { changed, mutable } = changedFiles()
+  mutate = mutable
+  configOnly =
+    !mutable.length && changed.some((f) => WATCHED_CONFIG.includes(f))
+  if (configOnly) {
+    console.log(
+      'Only the gate configuration changed; running it against the probe file.'
+    )
+    mutate = PROBE_FILES
+  }
+}
+
+if (!mutate.length) {
+  console.log('No changed source files to mutate.')
+  process.exit(0)
+}
+
+console.log(`Mutating the files this branch changed:\n  ${mutate.join('\n  ')}`)
+
+const files = summarise(runStryker(mutate))
+const baseRef = resolveBaseRef()
+let baseBaseline = null
+if (!baseRef) {
+  console.error(
+    'Could not resolve a base ref (no MUTATION_BASE, no origin/main to merge-base against).'
+  )
+  process.exit(1)
+}
+try {
+  baseBaseline = readBaseline(baseRef)
+} catch (e) {
+  console.error(e.message)
+  process.exit(1)
+}
+console.log(`Base ref: ${baseRef}`)
+const headBaseline = readBaseline().files || {}
+const baseline = baseBaseline ? baseBaseline.files || {} : {}
+const failures = []
+
+// The baseline travels inside the PR, so a branch can otherwise raise the number
+// it is measured against - and the weekly watch compares against the merged
+// value, so it would stay quiet too.
+if (baseBaseline) {
+  Object.entries(headBaseline).forEach(([name, entry]) => {
+    const known = baseline[name]
+    if (!known) {
+      if (!configOnly) console.log(`${name}: added to the baseline in this PR`)
+      return
+    }
+    if (entry.survived > known.survived)
+      failures.push(
+        `${name}: the baseline was raised in this PR, ${known.survived} -> ${entry.survived} surviving mutants`
+      )
+  })
+  Object.keys(baseline).forEach((name) => {
+    if (headBaseline[name]) return
+    // A source file deleted or renamed in this PR takes its entry with it; the
+    // entry only has to go when the file is still there to be mutated.
+    if (!fs.existsSync(name)) {
+      console.log(`${name}: deleted, its baseline entry goes with it`)
+      return
+    }
+    failures.push(`${name}: removed from the baseline in this PR`)
+  })
+}
+
+for (const [name, stats] of Object.entries(files)) {
+  const known = baseline[name]
+
+  if (!known) {
+    if (stats.score < NEW_FILE_FLOOR) {
+      failures.push(
+        `${name} scores ${stats.score}% and has no baseline: a new file must reach ${NEW_FILE_FLOOR}%`
+      )
+      stats.survivors.forEach((m) => failures.push(describeSurvivor(name, m)))
+    } else {
+      console.log(`${name}: ${stats.score}% (new file, above the floor)`)
+    }
+    continue
+  }
+
+  if (stats.survived > known.survived) {
+    failures.push(
+      `${name}: ${known.survived} -> ${stats.survived} surviving mutants`
+    )
+    stats.survivors.forEach((m) => failures.push(describeSurvivor(name, m)))
+  } else {
+    console.log(
+      `${name}: ${stats.score}% (${stats.survived} survived, baseline ${known.survived})`
+    )
+  }
+}
+
+if (failures.length) {
+  console.error('\nMutation gate failed:\n' + failures.join('\n'))
+  console.error(
+    '\nA surviving mutant is a change no test noticed. Add a spec that fails on it,\n' +
+      'then run `npm run mutation:changed` again. If a mutant is genuinely\n' +
+      'equivalent (the change cannot alter behaviour), say so in the PR body.'
+  )
+  process.exit(1)
+}
+
+console.log('\nMutation gate passed.')

package/stryker.conf.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://raw.githubusercontent.com/stryker-mutator/stryker-js/master/packages/core/schema/stryker-schema.json",
+  "packageManager": "npm",
+  "testRunner": "jest",
+  "jest": {
+    "projectType": "custom",
+    "configFile": "jest.stryker.config.js",
+    "enableFindRelatedTests": true
+  },
+  "mutate": ["src/**/*.ts", "!src/**/*.spec.ts"],
+  "reporters": ["clear-text", "json"],
+  "jsonReporter": { "fileName": "reports/mutation/mutation.json" },
+  "coverageAnalysis": "perTest",
+  "concurrency": 4,
+  "timeoutMS": 30000,
+  "thresholds": { "high": 90, "low": 80, "break": null },
+  "tempDirName": ".stryker-tmp",
+  "cleanTempDir": true
+}

package/utils/isIgnored.js

@@ -27,9 +27,24 @@ const isIgnored = (fPath, configuration) => __awaiter(void 0, void 0, void 0, fu
     const config = configuration || (yield (0, _1.getLintConfig)());
     const projectRoot = yield (0, _1.getProjectRoot)();
     const gitIgnoreFilePath = path_1.default.join(projectRoot, '.gitignore');
-    const rootPath = projectRoot + path_1.default.sep;
-    const relativePath = fPath.replace(rootPath, '');
-    if (fPath === projectRoot)
+    // path.relative rather than stripping `projectRoot + sep` from the string: a
+    // separator or a normalisation the caller did not apply leaves the strip with
+    // nothing to remove, and the `ignore` package then receives an absolute path
+    // and rejects it with a RangeError. path.relative is lexical - a symlinked root
+    // still yields a `..`-prefixed path, which the guard below catches.
+    const relativePath = path_1.default.relative(projectRoot, fPath);
+    if (relativePath === '')
+        return false;
+    // On Windows, `path.relative` returns an absolute path when the two paths sit
+    // on different drives, which the two guards below cannot see; passing that on
+    // reaches `ignore` and throws the RangeError this function exists to avoid.
+    if (path_1.default.isAbsolute(relativePath))
+        return false;
+    // Nothing in a project's .gitignore can match a path outside it, and the
+    // `ignore` package rejects a path that escapes the root ("path should be a
+    // path.relative()d string"), so a caller passing one gets `false` rather than
+    // a RangeError.
+    if (relativePath === '..' || relativePath.startsWith(`..${path_1.default.sep}`))
         return false;
     let gitIgnoreFileContent = '';
     if (yield (0, file_1.fileExists)(gitIgnoreFilePath))

package/utils/isIgnored.js.map

@@ -1 +1 @@
-{"version":3,"file":"isIgnored.js","sourceRoot":"","sources":["../../src/utils/isIgnored.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,4CAAwD;AACxD,gDAAuB;AACvB,oDAA2B;AAC3B,wBAAiD;AAGjD;;;;;GAKG;AACI,MAAM,SAAS,GAAG,CACvB,KAAa,EACb,aAA0B,EACR,EAAE;IACpB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,gBAAa,GAAE,CAAC,CAAA;IACvD,MAAM,WAAW,GAAG,MAAM,IAAA,iBAAc,GAAE,CAAA;IAC1C,MAAM,iBAAiB,GAAG,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;IAC9D,MAAM,QAAQ,GAAG,WAAW,GAAG,cAAI,CAAC,GAAG,CAAA;IACvC,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAEhD,IAAI,KAAK,KAAK,WAAW;QAAE,OAAO,KAAK,CAAA;IAEvC,IAAI,oBAAoB,GAAG,EAAE,CAAA;IAE7B,IAAI,MAAM,IAAA,iBAAU,EAAC,iBAAiB,CAAC;QACrC,oBAAoB,GAAG,MAAM,IAAA,eAAQ,EAAC,iBAAiB,CAAC,CAAA;IAE1D,OAAO,IAAA,gBAAM,GAAE;SACZ,GAAG,CAAC,oBAAoB,CAAC;SACzB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC;SACtB,OAAO,CAAC,YAAY,CAAC,CAAA;AAC1B,CAAC,CAAA,CAAA;AArBY,QAAA,SAAS,aAqBrB"}
+{"version":3,"file":"isIgnored.js","sourceRoot":"","sources":["../../src/utils/isIgnored.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,4CAAwD;AACxD,gDAAuB;AACvB,oDAA2B;AAC3B,wBAAiD;AAGjD;;;;;GAKG;AACI,MAAM,SAAS,GAAG,CACvB,KAAa,EACb,aAA0B,EACR,EAAE;IACpB,MAAM,MAAM,GAAG,aAAa,IAAI,CAAC,MAAM,IAAA,gBAAa,GAAE,CAAC,CAAA;IACvD,MAAM,WAAW,GAAG,MAAM,IAAA,iBAAc,GAAE,CAAA;IAC1C,MAAM,iBAAiB,GAAG,cAAI,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAA;IAE9D,6EAA6E;IAC7E,8EAA8E;IAC9E,6EAA6E;IAC7E,gFAAgF;IAChF,oEAAoE;IACpE,MAAM,YAAY,GAAG,cAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,CAAA;IAEtD,IAAI,YAAY,KAAK,EAAE;QAAE,OAAO,KAAK,CAAA;IAErC,8EAA8E;IAC9E,8EAA8E;IAC9E,4EAA4E;IAC5E,IAAI,cAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,KAAK,CAAA;IAE/C,yEAAyE;IACzE,2EAA2E;IAC3E,8EAA8E;IAC9E,gBAAgB;IAChB,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,CAAC,UAAU,CAAC,KAAK,cAAI,CAAC,GAAG,EAAE,CAAC;QACnE,OAAO,KAAK,CAAA;IAEd,IAAI,oBAAoB,GAAG,EAAE,CAAA;IAE7B,IAAI,MAAM,IAAA,iBAAU,EAAC,iBAAiB,CAAC;QACrC,oBAAoB,GAAG,MAAM,IAAA,eAAQ,EAAC,iBAAiB,CAAC,CAAA;IAE1D,OAAO,IAAA,gBAAM,GAAE;SACZ,GAAG,CAAC,oBAAoB,CAAC;SACzB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC;SACtB,OAAO,CAAC,YAAY,CAAC,CAAA;AAC1B,CAAC,CAAA,CAAA;AAtCY,QAAA,SAAS,aAsCrB"}