@boyingliu01/xp-gate 0.23.0 → 0.25.0

package/lib/sprint-state-migrator.js

@@ -57,18 +57,9 @@ function migrateState(state, stateDir) {
   if (!state.phase_history) { state.phase_history = []; }
   if (!state.isolation) { state.isolation = { worktree_path: null, branch: null }; }
 
-  state.phase_history = state.phase_history.map(entry => {
-    const phaseNum = String(entry.phase);
-    const mapped = LEGACY_PHASE_MAP[phaseNum];
-    if (mapped) {
-      warnings.push(`Migrated legacy phase ${entry.phase} → ${mapped.phase} (${mapped.phase_name})`);
-      return { ...entry, phase: mapped.phase, phase_name: mapped.phase_name };
-    }
-    if (!entry.phase_name && entry.phase >= 1 && entry.phase <= 6) {
-      entry.phase_name = PHASE_NAMES[entry.phase - 1];
-    }
-    return entry;
-  });
+  state.phase_history = state.phase_history.map(entry =>
+    normalizePhaseEntry(entry, warnings),
+  );
 
   const currentPhaseNum = String(state.phase);
   const currentMapped = LEGACY_PHASE_MAP[currentPhaseNum];
@@ -91,6 +82,47 @@ function migrateState(state, stateDir) {
   return state;
 }
 
+/**
+ * Migrate and normalize a single phase_history entry.
+ *
+ * Two passes, in this order:
+ *   1. legacy numbering → current numbering via LEGACY_PHASE_MAP;
+ *   2. field normalization: phase 1 historically carried `name` while phase 2+
+ *      carried `phase_name` (transitionPhase always writes `phase_name`).
+ *      Normalize to `phase_name` as the single canonical field, in BOTH
+ *      directions so a half-migrated file converges. The legacy `name` is kept
+ *      (not deleted) so any reader still consulting it keeps working.
+ *
+ * Ordering matters: the normalization must run for every entry, including those
+ * the legacy remap just rewrote — LEGACY_PHASE_MAP covers every phase 1-6, so
+ * gating normalization on "not remapped" would skip exactly the legacy files it
+ * exists for. (#507 left such a file: phase 1 with `name: 'PREP'`, phase 2+
+ * with `phase_name`.)
+ *
+ * @param {Object} entry - One phase_history entry (possibly legacy-shaped)
+ * @param {string[]} warnings - Accumulator for human-readable migration notes
+ * @returns {Object} The normalized entry
+ */
+function normalizePhaseEntry(entry, warnings) {
+  const phaseNum = String(entry.phase);
+  const mapped = LEGACY_PHASE_MAP[phaseNum];
+  if (mapped) {
+    warnings.push(`Migrated legacy phase ${entry.phase} → ${mapped.phase} (${mapped.phase_name})`);
+    entry = { ...entry, phase: mapped.phase, phase_name: mapped.phase_name };
+  }
+
+  if (!entry.phase_name && entry.name) {
+    entry.phase_name = entry.name;
+  }
+  if (!entry.phase_name && entry.phase >= 1 && entry.phase <= 6) {
+    entry.phase_name = PHASE_NAMES[entry.phase - 1];
+  }
+  if (!entry.name && entry.phase_name) {
+    entry.name = entry.phase_name;
+  }
+  return entry;
+}
+
 /**
  * Create initial sprint state for new sprints.
  *
@@ -120,17 +152,23 @@ function createInitialState(projectRoot) {
  * @param {string} stateDir - Path to .sprint-state directory
  */
 function logMigrationWarnings(warnings, stateDir) {
-  if (!fs.existsSync(stateDir)) {
-    fs.mkdirSync(stateDir, { recursive: true });
-  }
-
-  const warningsFile = path.join(stateDir, 'migration-warnings.json');
-  const existing = fs.existsSync(warningsFile)
-    ? JSON.parse(fs.readFileSync(warningsFile, 'utf8'))
-    : [];
+  try {
+    if (!fs.existsSync(stateDir)) {
+      fs.mkdirSync(stateDir, { recursive: true });
+    }
 
-  existing.push({ timestamp: new Date().toISOString(), warnings });
-  fs.writeFileSync(warningsFile, JSON.stringify(existing, null, 2), 'utf8');
+    const warningsFile = path.join(stateDir, 'migration-warnings.json');
+    const existing = fs.existsSync(warningsFile)
+      ? JSON.parse(fs.readFileSync(warningsFile, 'utf8'))
+      : [];
+
+    existing.push({ timestamp: new Date().toISOString(), warnings });
+    fs.writeFileSync(warningsFile, JSON.stringify(existing, null, 2), 'utf8');
+  } catch (err) {
+    // Migration must still return the migrated state; a failure to persist the
+    // warning log is reported to stderr and never thrown.
+    console.warn(`[WARN] could not write migration warnings: ${err.message}`);
+  }
 }
 
 /**

package/mock-policy/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MOCK-POLICY KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.0.0
+**Version:** 0.25.0.0
 
 ## OVERVIEW
 Mock layering policy enforcement — Gate M3 of pre-push hook. Ensures integration tests use real implementations for internal dependencies, mock external dependencies, and annotate pending mocks with removal plans. Combines project scope scanning, mock decision engine, and per-file validation into a single pipeline.

package/mutation/AGENTS.md

@@ -1,9 +1,9 @@
 # SRC/MUTATION KNOWLEDGE BASE
 
-**Generated:** 2026-10-13
-**Commit:** 05a08fcf
+**Generated:** 2026-10-14
+**Commit:** a757d625
 **Branch:** main
-**Version:** 0.21.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;
 }