@boyingliu01/xp-gate 0.24.0 → 0.25.0

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
 **Generated:** 2026-10-14
-**Commit:** e466ce16
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.24.0.0
+**Version:** 0.25.0.0
 
 ## OVERVIEW
 **Gate M** (incremental mutation testing) + **Gate M2** helpers (test-layer detection used by `src/mock-policy/`). Pre-push quality gate. TypeScript-only; uses Stryker.

package/mutation/__tests__/gremlins-runner.test.ts

@@ -0,0 +1,167 @@
+/**
+ * @intent #410: mutmut 3.x depends on fork() and cannot run natively on
+ *         Windows — Gate M (Python) formed a structural deadlock (installed =>
+ *         always blocked, uninstalled => always skipped). pytest-gremlins is
+ *         architecturally cross-platform (mutation switching, no fork), so it
+ *         becomes the second engine. This runner drives
+ *         `pytest --gremlins` and parses the console report.
+ * @covers GremlinsRunner availability probe + console report parsing
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { spawn, execSync, type ChildProcess } from 'child_process';
+
+vi.mock('child_process', () => ({
+  spawn: vi.fn(),
+  execSync: vi.fn(),
+}));
+
+/** Capture the stdout/close callbacks so the test can drive them by hand. */
+function mockChild(capture: {
+  stdout?: (cb: (d: Buffer) => void) => void;
+  stderr?: (cb: (d: Buffer) => void) => void;
+  close?: (cb: (code: number | null) => void) => void;
+  error?: (cb: (e: Error) => void) => void;
+}): ChildProcess {
+  return {
+    stdout: { on: (_e: string, cb: (d: Buffer) => void) => capture.stdout?.(cb) },
+    stderr: { on: (_e: string, cb: (d: Buffer) => void) => capture.stderr?.(cb) },
+    on: (event: string, cb: (arg: never) => void) => {
+      if (event === 'close') capture.close?.(cb as (code: number | null) => void);
+      if (event === 'error') capture.error?.(cb as unknown as (e: Error) => void);
+    },
+    kill: vi.fn(),
+  } as unknown as ChildProcess;
+}
+
+describe('GremlinsRunner', () => {
+  let GremlinsRunner: typeof import('../runners/gremlins-runner').GremlinsRunner;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    vi.mocked(execSync).mockReset();
+    vi.mocked(spawn).mockReset();
+    vi.mocked(execSync).mockReturnValue('' as never);
+    GremlinsRunner = (await import('../runners/gremlins-runner')).GremlinsRunner;
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('declares the pytest-gremlins engine name and the py extension', () => {
+    const runner = new GremlinsRunner();
+    expect(runner.name).toBe('pytest-gremlins');
+    expect(runner.extensions).toEqual(['py']);
+  });
+
+  it('isAvailable probes the pytest_gremlins import', async () => {
+    const runner = new GremlinsRunner();
+    await expect(runner.isAvailable()).resolves.toBe(true);
+    const probed = vi.mocked(execSync).mock.calls[0]?.[0] as string;
+    expect(probed).toContain('import pytest_gremlins');
+  });
+
+  it('isAvailable returns false when the import probe fails', async () => {
+    vi.mocked(execSync).mockImplementation(() => {
+      throw new Error('ModuleNotFoundError');
+    });
+    const runner = new GremlinsRunner();
+    await expect(runner.isAvailable()).resolves.toBe(false);
+  });
+
+  it('parses the console report (Zapped/Survived) into a normalized result', async () => {
+    let closeCb: ((code: number | null) => void) | undefined;
+    let stdoutCb: ((d: Buffer) => void) | undefined;
+    vi.mocked(spawn).mockReturnValue(
+      mockChild({
+        stdout: cb => { stdoutCb = cb; },
+        close: cb => { closeCb = cb; },
+      }),
+    );
+
+    const runner = new GremlinsRunner();
+    const promise = runner.run({ files: ['src/foo.py'], timeoutMs: 5000, cwd: '/tmp' });
+    await new Promise(r => setTimeout(r, 0));
+
+    stdoutCb?.(
+      Buffer.from(
+        '================== pytest-gremlins mutation report ==================\n' +
+          'Zapped: 142 gremlins (89%)\n' +
+          'Survived: 18 gremlins (11%)\n' +
+          '=====================================================================\n',
+      ),
+    );
+    closeCb?.(0);
+
+    const outcome = await promise;
+    expect(outcome.report).not.toBeNull();
+    expect(outcome.report?.nrOfKilledMutants).toBe(142);
+    expect(outcome.report?.nrOfSurvivedMutants).toBe(18);
+    expect(outcome.report?.nrOfMutants).toBe(160);
+    expect(Math.round(outcome.report!.mutationScore)).toBe(89);
+    expect(outcome.timedOut).toBe(false);
+  });
+
+  it('returns report=null (never throws) when the report lines are absent', async () => {
+    let closeCb: ((code: number | null) => void) | undefined;
+    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } }));
+
+    const runner = new GremlinsRunner();
+    const promise = runner.run({ files: ['src/foo.py'], timeoutMs: 5000, cwd: '/tmp' });
+    await new Promise(r => setTimeout(r, 0));
+    closeCb?.(1);
+
+    const outcome = await promise;
+    expect(outcome.report).toBeNull();
+  });
+
+  it('returns report=null when the report has zero gremlins', async () => {
+    let closeCb: ((code: number | null) => void) | undefined;
+    let stdoutCb: ((d: Buffer) => void) | undefined;
+    vi.mocked(spawn).mockReturnValue(
+      mockChild({ stdout: cb => { stdoutCb = cb; }, close: cb => { closeCb = cb; } }),
+    );
+
+    const runner = new GremlinsRunner();
+    const promise = runner.run({ files: ['src/foo.py'], timeoutMs: 5000, cwd: '/tmp' });
+    await new Promise(r => setTimeout(r, 0));
+    stdoutCb?.(Buffer.from('Zapped: 0 gremlins (0%)\nSurvived: 0 gremlins (0%)\n'));
+    closeCb?.(0);
+
+    const outcome = await promise;
+    expect(outcome.report).toBeNull();
+  });
+
+  it('passes --gremlin-targets derived from the changed file directories', async () => {
+    let closeCb: ((code: number | null) => void) | undefined;
+    vi.mocked(spawn).mockReturnValue(mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } }));
+
+    const runner = new GremlinsRunner();
+    const promise = runner.run({ files: ['src/foo/bar.py', 'src/baz.py'], timeoutMs: 5000, cwd: '/tmp' });
+    await new Promise(r => setTimeout(r, 0));
+    closeCb?.(0);
+    await promise;
+
+    const spawnArgs = vi.mocked(spawn).mock.calls[0]?.[1] as string[];
+    const joined = spawnArgs.join(' ');
+    expect(joined).toContain('--gremlins');
+    expect(joined).toContain('--gremlin-targets=src/foo,src');
+  });
+
+  it('reports timedOut when the child exceeds the deadline', async () => {
+    let closeCb: ((code: number | null) => void) | undefined;
+    const child = mockChild({ stdout: () => {}, close: cb => { closeCb = cb; } });
+    vi.mocked(spawn).mockReturnValue(child);
+
+    const runner = new GremlinsRunner();
+    const promise = runner.run({ files: ['src/foo.py'], timeoutMs: 1, cwd: '/tmp' });
+    await new Promise(r => setTimeout(r, 20));
+    closeCb?.(null);
+
+    const outcome = await promise;
+    expect(outcome.timedOut).toBe(true);
+    expect(child.kill).toHaveBeenCalled();
+  });
+});

package/mutation/__tests__/mutmut-runner.test.ts

@@ -119,7 +119,7 @@ describe('MutmutRunner', () => {
     it('should return true when mutmut is installed', async () => {
       vi.mocked(execSync).mockReturnValue('mutmut, version 3.0.0\n');
 
-      const runner = new MutmutRunner();
+      const runner = new MutmutRunner('linux');
       const result = await runner.isAvailable();
       expect(result).toBe(true);
       expect(execSync).toHaveBeenCalledWith('mutmut --version', {
@@ -150,9 +150,11 @@ describe('MutmutRunner', () => {
       const result = await runner.isAvailable();
 
       expect(result).toBe(true);
-      expect(execSync).toHaveBeenNthCalledWith(2, 'wsl mutmut --version', {
+      // #410: win32 route is decided by the WSL probe alone (no native probe).
+      expect(execSync).toHaveBeenCalledTimes(1);
+      expect(execSync).toHaveBeenCalledWith('wsl mutmut --version', {
         stdio: 'pipe',
-        timeout: 5000,
+        timeout: 10000,
       });
     });
 
@@ -205,7 +207,7 @@ describe('MutmutRunner', () => {
       // No existing pyproject.toml
       vi.mocked(existsSync).mockReturnValue(false);
 
-      const runner = new MutmutRunner();
+      const runner = new MutmutRunner('linux');
       const promise = runner.run({
         files: ['src/main.py'],
         timeoutMs: 60000,
@@ -235,14 +237,12 @@ describe('MutmutRunner', () => {
       expect(result.report!.nrOfSurvivedMutants).toBe(29);
     });
 
-    it('should execute native mutmut when native detection succeeds on Windows', async () => {
-      let closeCb: ((code: number | null) => void) | null = null;
+    it('should be unavailable on Windows when WSL is absent even if native mutmut is installed', async () => {
       const mockChild = {
         stdout: { on: vi.fn() },
         stderr: { on: vi.fn() },
-        on: vi.fn((event: string, cb: (code: number | null) => void) => {
-          if (event === 'close') closeCb = cb;
-        }),
+        // Unavailable route: `run()` never spawns, so `close` is never subscribed.
+        on: vi.fn(),
         kill: vi.fn(),
         killed: false,
       };
@@ -254,22 +254,17 @@ describe('MutmutRunner', () => {
       vi.mocked(existsSync).mockReturnValue(false);
 
       const runner = new MutmutRunner('win32');
-      expect(await runner.isAvailable()).toBe(true);
-      const promise = runner.run({
+      // #410: native mutmut on Windows proves nothing about `mutmut run`
+      // (fork()-based). The WSL route decides availability; no WSL → SKIP.
+      expect(await runner.isAvailable()).toBe(false);
+      const outcome = await runner.run({
         files: ['src/main.py'],
         timeoutMs: 60000,
         cwd: 'C:\\work\\project',
       });
-      await waitForSpawn();
-      closeCb!(0);
-      await promise;
 
-      expect(execSync).toHaveBeenCalledTimes(1);
-      expect(spawn).toHaveBeenCalledWith(
-        'mutmut',
-        ['run'],
-        expect.objectContaining({ cwd: 'C:\\work\\project' }),
-      );
+      expect(outcome).toEqual({ report: null, timedOut: false });
+      expect(spawn).not.toHaveBeenCalled();
     });
 
     it('should execute selected WSL route with Linux --cd and Windows host cwd', async () => {
@@ -428,7 +423,7 @@ describe('MutmutRunner', () => {
         expect(vi.mocked(spawn).mock.calls[0]?.[0]).toBe('wsl');
     });
 
-    it('should follow repeated WSL to native availability transitions', async () => {
+    it('should keep the WSL route on Windows even when native mutmut becomes available', async () => {
       const mockChild = {
         stdout: { on: vi.fn() },
         stderr: { on: vi.fn() },
@@ -450,10 +445,13 @@ describe('MutmutRunner', () => {
       const runner = new MutmutRunner('win32');
       expect(await runner.isAvailable()).toBe(true);
       nativeAvailable = true;
+      // #410: even when native `mutmut --version` starts succeeding, the win32
+      // route is decided by WSL alone — native success proves nothing about
+      // `mutmut run` (fork()). The route must NOT flip to native.
       expect(await runner.isAvailable()).toBe(true);
       await runner.run({ files: ['src/main.py'], timeoutMs: 60000, cwd: 'C:\\repo' });
 
-      expect(vi.mocked(spawn).mock.calls[0]?.[0]).toBe('mutmut');
+      expect(vi.mocked(spawn).mock.calls[0]?.[0]).toBe('wsl');
     });
 
     it('should stop spawning after availability transitions to unavailable', async () => {

package/mutation/__tests__/runners-index.test.ts

@@ -10,6 +10,7 @@ import {
   runnerRegistry,
   registerAllRunners,
   resolveRunner,
+  resolveRunners,
   StrykerRunner,
   MutmutRunner,
   GoMutantRunner,
@@ -32,11 +33,12 @@ describe('runners/index', () => {
     expect(runnerRegistry).toBeInstanceOf(Map);
   });
 
-  it('registerAllRunners() registers all 4 runners', () => {
+  it('registerAllRunners() registers all 5 runners', () => {
     registerAllRunners();
 
-    expect(runnerRegistry.size).toBe(4);
+    expect(runnerRegistry.size).toBe(5);
     expect(runnerRegistry.has('Stryker')).toBe(true);
+    expect(runnerRegistry.has('pytest-gremlins')).toBe(true);
     expect(runnerRegistry.has('mutmut')).toBe(true);
     expect(runnerRegistry.has('gomutants')).toBe(true);
     expect(runnerRegistry.has('pitest')).toBe(true);
@@ -46,6 +48,7 @@ describe('runners/index', () => {
     registerAllRunners();
 
     expect(runnerRegistry.get('Stryker')).toBeInstanceOf(StrykerRunner);
+    expect(runnerRegistry.get('pytest-gremlins')).toBeDefined();
     expect(runnerRegistry.get('mutmut')).toBeInstanceOf(MutmutRunner);
     expect(runnerRegistry.get('gomutants')).toBeInstanceOf(GoMutantRunner);
     expect(runnerRegistry.get('pitest')).toBeInstanceOf(PitestRunner);
@@ -59,7 +62,7 @@ describe('runners/index', () => {
     it.each([
       ['ts', 'Stryker'],
       ['tsx', 'Stryker'],
-      ['py', 'mutmut'],
+      ['py', 'pytest-gremlins'],
       ['go', 'gomutants'],
       ['java', 'pitest'],
       ['kt', 'pitest'],
@@ -83,6 +86,31 @@ describe('runners/index', () => {
     });
   });
 
+  describe('resolveRunners()', () => {
+    beforeEach(() => {
+      registerAllRunners();
+    });
+
+    it('returns the py runners in registration (priority) order for ".py"', () => {
+      const runners = resolveRunners('.py');
+      expect(runners.map(r => r.name)).toEqual(['pytest-gremlins', 'mutmut']);
+    });
+
+    it('returns a single-element list for extensions with one runner', () => {
+      expect(resolveRunners('.go').map(r => r.name)).toEqual(['gomutants']);
+      expect(resolveRunners('.ts').map(r => r.name)).toEqual(['Stryker']);
+    });
+
+    it('returns an empty list for unknown extensions', () => {
+      expect(resolveRunners('.rb')).toEqual([]);
+    });
+
+    it('handles dot-prefixed extensions', () => {
+      const runners = resolveRunners('.py');
+      expect(runners.length).toBeGreaterThan(1);
+    });
+  });
+
   describe('re-exports', () => {
     it('re-exports all runner classes', () => {
       expect(StrykerRunner).toBeDefined();

package/mutation/gate-m.ts

@@ -12,8 +12,10 @@ import {
 import { detectAITestCharacteristics } from './detect-ai-test';
 import {
   resolveRunner,
+  resolveRunners,
   registerAllRunners,
   MutationRunOutcome,
+  MutationRunner,
 } from './runners';
 
 // ── Pre-run auto-registration of all language runners ──
@@ -440,10 +442,14 @@ async function runAllRunners(
   const fileScores: Record<string, number | null> = {};
 
   for (const [, files] of Array.from(groups.entries())) {
-    const runner = resolveRunner(path.extname(files[0]));
-    if (!runner) continue;
-
-    if (!await runner.isAvailable()) {
+    const ext = path.extname(files[0]);
+    // #410 fallback: walk ALL runners for the extension in priority order and
+    // use the first one that is actually available. A pure-mutmut environment
+    // (no pytest-gremlins) thus still gets mutation testing instead of a
+    // silent SKIP — the design contract "gremlins 可用→GremlinsRunner，否则
+    // MutmutRunner" is honored here, not by registration order alone.
+    const runner = await resolveFirstAvailable(ext);
+    if (!runner) {
       applyNullScores(files, fileScores);
       continue;
     }
@@ -455,6 +461,18 @@ async function runAllRunners(
   return fileScores;
 }
 
+/**
+ * Pick the first AVAILABLE runner for an extension, honoring registration
+ * priority. Returns undefined when no registered runner for the extension is
+ * installed on this machine.
+ */
+async function resolveFirstAvailable(ext: string): Promise<MutationRunner | undefined> {
+  for (const candidate of resolveRunners(ext)) {
+    if (await candidate.isAvailable()) return candidate;
+  }
+  return undefined;
+}
+
 function applyNullScores(files: string[], scores: Record<string, number | null>): void {
   for (const f of files) scores[f] = null;
 }

package/mutation/runners/gremlins-runner.ts

@@ -0,0 +1,238 @@
+// @no-test-required: gremlins wrapper — tested via gremlins-runner.test.ts + pre-push Gate M
+import { spawn, execSync, type ChildProcess } from 'child_process';
+import { dirname } from 'path';
+import type {
+  MutationRunner,
+  RunMutationOptions,
+  MutationRunOutcome,
+  MutationRunResult,
+} from './types';
+
+/**
+ * pytest-gremlins mutation runner for Python files (#410).
+ *
+ * Why a second Python engine exists: mutmut 3.x is built on fork(), so on
+ * Windows it can only run under WSL — a native Windows user had a structural
+ * deadlock (installed => `mutmut run` exits 1 => push blocked; uninstalled =>
+ * Gate M skips). pytest-gremlins uses mutation *switching* (instrument once,
+ * flip an env var per mutant) with no fork and no per-mutant file I/O, making
+ * it natively cross-platform. It also matches Gate M's needs: coverage-guided
+ * test selection, an incremental content-hash cache, parallel workers and
+ * console/HTML/JSON reports.
+ *
+ * Constraint: pytest-gremlins requires Python >= 3.11. On older interpreters
+ * the import probe simply fails and the caller keeps the mutmut path (or
+ * SKIPs) — no new hard dependency.
+ */
+/**
+ * How long to wait after SIGTERM before escalating to SIGKILL. pytest-gremlins
+ * runs a whole pytest session per invocation, so a child that ignores SIGTERM
+ * (stuck in a C extension) still needs a hard backstop.
+ */
+const SIGKILL_ESCALATION_MS = 5000;
+
+/** Bound on the one-shot import probe; a hung interpreter must not stall Gate M. */
+const PROBE_TIMEOUT_MS = 10000;
+
+/**
+ * Exactly-once resolve bookkeeping for a spawned mutation run.
+ *
+ * A child can report `close`, `error`, a timeout, and the SIGKILL escalation in
+ * any interleaving; without a single latched gate the Promise resolves twice
+ * (subsequent resolves are silent no-ops, but the *first* one wins, which can
+ * be the wrong verdict). `settled` makes the ordering irrelevant. Extracted
+ * from `spawnGremlins` so that function stays under the long-function budget.
+ *
+ * A factory rather than a class: it holds no collaborators to inject, and the
+ * SOLID analyzer flags `new X()` as a dependency-inversion smell regardless of
+ * whether the type is injectable.
+ */
+function createSettleGuard(resolve: (o: MutationRunOutcome) => void) {
+  let settled = false;
+  let escalationId: NodeJS.Timeout | undefined;
+  let timeoutId: NodeJS.Timeout | undefined;
+
+  const escalateToKill = (child: ChildProcess): void => {
+    if (!settled) child.kill('SIGKILL');
+  };
+
+  const guard = {
+    timedOut: false,
+    /** SIGTERM at `timeoutMs`, escalating to SIGKILL if the child ignores it. */
+    armTimeout(child: ChildProcess, timeoutMs: number): void {
+      timeoutId = setTimeout(() => {
+        guard.timedOut = true;
+        child.kill('SIGTERM');
+        if (settled) return;
+        escalationId = setTimeout(() => escalateToKill(child), SIGKILL_ESCALATION_MS);
+      }, timeoutMs);
+    },
+    settle(outcome: MutationRunOutcome): void {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      if (escalationId) clearTimeout(escalationId);
+      resolve(outcome);
+    },
+  };
+  return guard;
+}
+
+export class GremlinsRunner implements MutationRunner {
+  readonly name = 'pytest-gremlins';
+  readonly extensions = ['py'];
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      execSync('python -c "import pytest_gremlins"', {
+        stdio: 'pipe',
+        timeout: PROBE_TIMEOUT_MS,
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async run(options: RunMutationOptions): Promise<MutationRunOutcome> {
+    if (!(await this.isAvailable())) {
+      return { report: null, timedOut: false };
+    }
+
+    // Spawning can throw synchronously (e.g. ENOENT on a broken interpreter
+    // shim); that must surface as a null report, never as an unhandled
+    // rejection that aborts the whole Gate M orchestration.
+    try {
+      return await this.spawnGremlins(options);
+    } catch (err) {
+      return {
+        report: null,
+        timedOut: false,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  /**
+   * Build the argv for `python -m pytest`.
+   *
+   * `-m pytest` rather than a bare `pytest`: the import probe in
+   * `isAvailable()` already proved *this* interpreter carries the plugin, so
+   * running through the same interpreter is the only way to be sure the plugin
+   * is actually loaded.
+   */
+  private gremlinsArgs(options: RunMutationOptions): string[] {
+    return [
+      '-m',
+      'pytest',
+      '--gremlins',
+      `--gremlin-targets=${buildTargets(options.files)}`,
+      '--gremlin-report=console',
+      '--gremlin-parallel',
+      '--gremlin-cache',
+    ];
+  }
+
+  /** Spawn the child and settle exactly once, on close or on error. */
+  private spawnGremlins(options: RunMutationOptions): Promise<MutationRunOutcome> {
+    return new Promise((resolve) => {
+      const guard = createSettleGuard(resolve);
+      let child: ChildProcess;
+      try {
+        child = spawn('python', this.gremlinsArgs(options), {
+          stdio: 'pipe',
+          cwd: options.cwd,
+        });
+      } catch (err) {
+        guard.settle({
+          report: null,
+          timedOut: false,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return;
+      }
+
+      let stdout = '';
+      let stderr = '';
+      guard.armTimeout(child, options.timeoutMs);
+
+      child.stdout?.on('data', (data: Buffer) => {
+        stdout += data.toString();
+      });
+      child.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString();
+      });
+
+      child.on('close', (code) => {
+        // A missing report is NOT a failure verdict: parse returns null and the
+        // orchestrator keeps its non-blocking semantics (same contract as the
+        // mutmut runner's null report).
+        guard.settle({
+          report: parseConsoleReport(stdout),
+          timedOut: guard.timedOut,
+          error: code !== 0 ? stderr || stdout : undefined,
+        });
+      });
+
+      child.on('error', (err) => {
+        guard.settle({ report: null, timedOut: guard.timedOut, error: err.message });
+      });
+    });
+  }
+}
+
+/**
+ * Comma-separated mutate targets, deduplicated, derived from the changed
+ * files' directories — `--gremlin-targets` accepts files OR directories, and
+ * the directories keep the mutant count bounded to the touched area.
+ *
+ * Module-level and pure so it is directly testable without instantiating the
+ * runner.
+ */
+function buildTargets(files: string[]): string {
+  const dirs = new Set<string>();
+  for (const file of files) {
+    const dir = dirname(file);
+    dirs.add(dir && dir !== '.' ? dir : file);
+  }
+  return Array.from(dirs).join(',');
+}
+
+/**
+ * Parse pytest-gremlins' console report.
+ *
+ * The report prints two lines (plus a banner):
+ *   Zapped: 142 gremlins (89%)
+ *   Survived: 18 gremlins (11%)
+ *
+ * Returns null when neither line is present — a run that never got to the
+ * report (import failure, collection error, timeout) must not be reported as
+ * a 0% score, which would be a fabricated verdict. `Zapped` maps to killed,
+ * `Survived` to survived; the totals are their sum, matching the mutmut
+ * runner's normalization exactly.
+ */
+export function parseConsoleReport(stdout: string): MutationRunResult | null {
+  const zapped = extractCount(stdout, /Zapped:\s*(\d+)\s*gremlins?/i);
+  const survived = extractCount(stdout, /Survived:\s*(\d+)\s*gremlins?/i);
+
+  if (zapped === null && survived === null) return null;
+
+  const nrOfKilledMutants = zapped ?? 0;
+  const nrOfSurvivedMutants = survived ?? 0;
+  const nrOfMutants = nrOfKilledMutants + nrOfSurvivedMutants;
+  if (nrOfMutants === 0) return null;
+
+  return {
+    mutationScore: (nrOfKilledMutants / nrOfMutants) * 100,
+    nrOfMutants,
+    nrOfKilledMutants,
+    nrOfSurvivedMutants,
+  };
+}
+
+function extractCount(text: string, pattern: RegExp): number | null {
+  const match = text.match(pattern);
+  if (!match?.[1]) return null;
+  const value = parseInt(match[1], 10);
+  return Number.isNaN(value) ? null : value;
+}

package/mutation/runners/index.ts

@@ -7,15 +7,17 @@ export type {
   MutationRunner,
 } from './types';
 
-export { registerRunner, resolveRunner, runnerRegistry } from './types';
+export { registerRunner, resolveRunner, resolveRunners, runnerRegistry } from './types';
 
 export { StrykerRunner } from './stryker-runner';
 export { MutmutRunner } from './mutmut-runner';
+export { GremlinsRunner } from './gremlins-runner';
 export { GoMutantRunner } from './go-mutant-runner';
 export { PitestRunner } from './pitest-runner';
 
 import { StrykerRunner } from './stryker-runner';
 import { MutmutRunner } from './mutmut-runner';
+import { GremlinsRunner } from './gremlins-runner';
 import { GoMutantRunner } from './go-mutant-runner';
 import { PitestRunner } from './pitest-runner';
 import { registerRunner } from './types';
@@ -23,6 +25,12 @@ import { registerRunner } from './types';
 /** Auto-register all known runners. */
 export function registerAllRunners(): void {
   registerRunner(new StrykerRunner());
+  // Registration order decides the `py` winner (resolveRunner returns the
+  // FIRST runner whose extensions include the ext). pytest-gremlins is
+  // registered before mutmut deliberately (#410): it is natively
+  // cross-platform, so when both are installed it is the better default —
+  // mutmut stays reachable via its own runner on Unix-only setups.
+  registerRunner(new GremlinsRunner());
   registerRunner(new MutmutRunner());
   registerRunner(new GoMutantRunner());
   registerRunner(new PitestRunner());