peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/mut/assert-scanner.js

@@ -0,0 +1,116 @@
+/**
+ * Per spec §4.2 验收审计 + §7 阶段二 — 5-pattern weak-assertion AST scan.
+ *
+ * Hard constraints:
+ *   H6 (CLI裁决): every detection is regex/AST-based, not LLM-judged.
+ *   KISS: regex matchers on common expect() patterns. Production slice
+ *   would migrate to TypeScript Compiler API; v1 ships regex for speed.
+ *
+ * Weak patterns (5):
+ *   - toBeDefined()
+ *   - toBeTruthy()
+ *   - toEqual(x) where arg === receiver (toEqual-self)
+ *   - expect.anything()
+ *   - toBe(x) where arg === receiver (toBe-self)
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const WEAK_PATTERNS = [
+    { pattern: 'toBeDefined', regex: /\.toBeDefined\s*\(\s*\)/g },
+    { pattern: 'toBeTruthy', regex: /\.toBeTruthy\s*\(\s*\)/g },
+    { pattern: 'expect-anything', regex: /expect\.anything\s*\(\s*\)/g },
+    // Self-equality patterns require matched-pair parsing; handled below.
+];
+const TO_EQUAL_SELF = /\.toEqual\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g;
+const TO_BE_SELF = /\.toBe\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g;
+async function countAssertions(content) {
+    // Approximate: count expect(...).method( occurrences.
+    // Handle nested parens by finding expect( and matching to a balanced close.
+    let count = 0;
+    const re = /expect\s*\(/g;
+    for (const m of content.matchAll(re)) {
+        let depth = 1;
+        let i = (m.index ?? 0) + m[0].length;
+        while (i < content.length && depth > 0) {
+            const ch = content[i];
+            if (ch === '(')
+                depth++;
+            else if (ch === ')')
+                depth--;
+            i++;
+        }
+        // After balanced expect(...), check for .method( pattern.
+        const tail = content.slice(i);
+        if (/^\s*\.\w+\s*\(/.test(tail)) {
+            count++;
+        }
+    }
+    return count;
+}
+function lineOf(content, offset) {
+    return content.slice(0, offset).split('\n').length;
+}
+export async function scanAssertions(input) {
+    let total = 0;
+    let weak = 0;
+    const byPattern = new Map();
+    for (const file of input.testFiles) {
+        const fullPath = join(input.project, file);
+        const content = await readFile(fullPath, 'utf8');
+        total += await countAssertions(content);
+        for (const { pattern, regex } of WEAK_PATTERNS) {
+            const matches = [...content.matchAll(regex)];
+            if (matches.length > 0) {
+                weak += matches.length;
+                const list = byPattern.get(pattern) ?? [];
+                for (const m of matches) {
+                    const idx = m.index ?? 0;
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                }
+                byPattern.set(pattern, list);
+            }
+        }
+        // toEqual-self: needs receiver extraction.
+        const eqSelf = [...content.matchAll(TO_EQUAL_SELF)];
+        for (const m of eqSelf) {
+            const receiverMatch = content.slice(0, m.index ?? 0).match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g);
+            if (receiverMatch && receiverMatch.length > 0) {
+                const lastReceiver = receiverMatch[receiverMatch.length - 1];
+                const receiverName = lastReceiver?.match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/)?.[1];
+                if (receiverName && receiverName === m[1]) {
+                    weak += 1;
+                    const idx = m.index ?? 0;
+                    const list = byPattern.get('toEqual-self') ?? [];
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                    byPattern.set('toEqual-self', list);
+                }
+            }
+        }
+        // toBe-self: same pattern.
+        const beSelf = [...content.matchAll(TO_BE_SELF)];
+        for (const m of beSelf) {
+            const receiverMatch = content.slice(0, m.index ?? 0).match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/g);
+            if (receiverMatch && receiverMatch.length > 0) {
+                const lastReceiver = receiverMatch[receiverMatch.length - 1];
+                const receiverName = lastReceiver?.match(/expect\s*\(\s*([a-zA-Z_$][\w$]*)\s*\)/)?.[1];
+                if (receiverName && receiverName === m[1]) {
+                    weak += 1;
+                    const idx = m.index ?? 0;
+                    const list = byPattern.get('toBe-self') ?? [];
+                    list.push({ file, line: lineOf(content, idx), code: m[0] });
+                    byPattern.set('toBe-self', list);
+                }
+            }
+        }
+    }
+    const weakPatterns = [];
+    for (const [pattern, examples] of byPattern.entries()) {
+        weakPatterns.push({ pattern, count: examples.length, examples });
+    }
+    return {
+        totalAssertions: total,
+        weakAssertions: weak,
+        weakRate: total === 0 ? 0 : weak / total,
+        weakPatterns,
+    };
+}

package/dist/services/mut/index.d.ts

@@ -0,0 +1,8 @@
+export { MutReportSchema } from './types.js';
+export { scanAssertions, type ScanInput } from './assert-scanner.js';
+export { runMutation, type RunMutationInput, type RunMutationOutput, type StrykerInvoker, type StrykerRawResult, } from './mut-runner.js';
+export { createProductionStrykerInvoker } from './production-stryker.js';
+export { buildMutReport, type BuildMutInput } from './report-builder.js';
+export { loadMutReport, mutReportPath, MUT_REPORT_RELATIVE_PATH } from './report-loader.js';
+export { DEFAULT_THRESHOLDS, evaluateThresholds, type Thresholds, type ThresholdEvaluation, type ThresholdViolation, type ThresholdViolationKind, } from './thresholds.js';
+export type { MutReportJson, MutationReport, AssertionsReport, WeakPattern, WeakPatternCount, Followup, } from './types.js';

package/dist/services/mut/index.js

@@ -0,0 +1,7 @@
+export { MutReportSchema } from './types.js';
+export { scanAssertions } from './assert-scanner.js';
+export { runMutation, } from './mut-runner.js';
+export { createProductionStrykerInvoker } from './production-stryker.js';
+export { buildMutReport } from './report-builder.js';
+export { loadMutReport, mutReportPath, MUT_REPORT_RELATIVE_PATH } from './report-loader.js';
+export { DEFAULT_THRESHOLDS, evaluateThresholds, } from './thresholds.js';

package/dist/services/mut/mut-runner.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Per spec §4.2 验收审计 — Stryker wrapper for TS mutation testing.
+ *
+ * Hard constraints:
+ *   H6 (CLI裁决): invokeStryker is injected; production wires it to
+ *       @stryker-mutator/core programmatic API.
+ *   DRY: production implementation lives in this file; tests mock the
+ *       invokeStryker injection point.
+ *   KISS: keep the public surface narrow — input, invoker, output.
+ */
+import type { MutationReport } from './types.js';
+export interface StrykerRawResult {
+    readonly mutantsTotal: number;
+    readonly mutantsKilled: number;
+    readonly mutantsSurvived: number;
+    readonly mutantsTimeout: number;
+    readonly perFile: ReadonlyArray<{
+        readonly file: string;
+        readonly killRate: number;
+        readonly survived: ReadonlyArray<{
+            line: number;
+            mutation: string;
+            survivedBecause: string;
+        }>;
+    }>;
+}
+export type StrykerInvoker = (opts: {
+    project: string;
+    testFiles: ReadonlyArray<string>;
+}) => Promise<StrykerRawResult>;
+export interface RunMutationInput {
+    readonly project: string;
+    readonly testFiles: ReadonlyArray<string>;
+    readonly invokeStryker: StrykerInvoker;
+}
+export interface RunMutationOutput {
+    readonly mutation: MutationReport;
+}
+export declare function runMutation(input: RunMutationInput): Promise<RunMutationOutput>;

package/dist/services/mut/mut-runner.js

@@ -0,0 +1,29 @@
+export async function runMutation(input) {
+    let raw;
+    try {
+        raw = await input.invokeStryker({
+            project: input.project,
+            testFiles: input.testFiles,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Stryker invocation failed: ${message}`);
+    }
+    const killRate = raw.mutantsTotal === 0 ? 0 : raw.mutantsKilled / raw.mutantsTotal;
+    return {
+        mutation: {
+            tool: 'stryker',
+            mutantsTotal: raw.mutantsTotal,
+            mutantsKilled: raw.mutantsKilled,
+            mutantsSurvived: raw.mutantsSurvived,
+            mutantsTimeout: raw.mutantsTimeout,
+            killRate,
+            byFile: raw.perFile.map((f) => ({
+                file: f.file,
+                killRate: f.killRate,
+                survived: f.survived,
+            })),
+        },
+    };
+}

package/dist/services/mut/production-stryker.d.ts

@@ -0,0 +1,2 @@
+import type { StrykerInvoker } from './mut-runner.js';
+export declare function createProductionStrykerInvoker(): StrykerInvoker;

package/dist/services/mut/production-stryker.js

@@ -0,0 +1,75 @@
+/**
+ * Production Stryker invoker. Uses @stryker-mutator/core programmatic API.
+ * Note: this is a thin wrapper — actual Stryker invocation requires the
+ * Stryker config in `stryker.conf.js` to live at the project root.
+ */
+import { relative, isAbsolute } from 'node:path';
+export function createProductionStrykerInvoker() {
+    return async ({ project, testFiles: _testFiles }) => {
+        // Lazy-load Stryker so unit tests don't need it installed.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const Stryker = (await import('@stryker-mutator/core')).Stryker;
+        // Mutation surface is owned by stryker.conf.js. testFiles is a runtime
+        // hint (consumed by the configured testRunner, not by Stryker's `mutate`
+        // field — `mutate` is source files to mutate, never test paths).
+        const stryker = new Stryker({});
+        const mutants = (await stryker.runMutationTest());
+        return normalize(mutants, project);
+    };
+}
+function normalize(mutants, project) {
+    let mutantsKilled = 0;
+    let mutantsSurvived = 0;
+    let mutantsTimeout = 0;
+    for (const m of mutants) {
+        if (m.status === 'Killed')
+            mutantsKilled++;
+        else if (m.status === 'Survived')
+            mutantsSurvived++;
+        else if (m.status === 'Timeout')
+            mutantsTimeout++;
+    }
+    // Bucket mutants by fileName to populate perFile. deriveFollowups iterates
+    // m.byFile to emit per-file followups (e.g. low_kill_rate) — leaving this
+    // empty (as v0 did) silently swallowed those followups in production.
+    const byFile = new Map();
+    for (const m of mutants) {
+        // Stryker 8 returns absolute paths in MutantResult.fileName. Strip the
+        // project root so byFile[].file is repo-relative (e.g. "src/services/loop/...").
+        // path.relative falls back to the absolute path when input is outside
+        // project, which is the safest failure mode.
+        const file = isAbsolute(m.fileName) && m.fileName.startsWith(project)
+            ? relative(project, m.fileName)
+            : m.fileName;
+        let bucket = byFile.get(file);
+        if (!bucket) {
+            bucket = { killed: 0, survived: 0, survivedEntries: [] };
+            byFile.set(file, bucket);
+        }
+        if (m.status === 'Killed')
+            bucket.killed++;
+        else if (m.status === 'Survived') {
+            bucket.survived++;
+            bucket.survivedEntries.push({
+                line: m.location.start.line + 1, // Stryker is 0-based; reports are 1-based.
+                mutation: m.replacement,
+                survivedBecause: m.statusReason ?? '',
+            });
+        }
+    }
+    const perFile = [...byFile.entries()]
+        .map(([file, b]) => {
+        const total = b.killed + b.survived;
+        const killRate = total === 0 ? 0 : b.killed / total;
+        return { file, killRate, survived: b.survivedEntries };
+    })
+        // Stable order for MUT.sig / reports.
+        .sort((a, b) => a.file.localeCompare(b.file));
+    return {
+        mutantsTotal: mutants.length,
+        mutantsKilled,
+        mutantsSurvived,
+        mutantsTimeout,
+        perFile,
+    };
+}

package/dist/services/mut/report-builder.d.ts

@@ -0,0 +1,11 @@
+import { type AssertionsReport, type MutationReport, type MutReportJson } from './types.js';
+import { type Thresholds } from './thresholds.js';
+export interface BuildMutInput {
+    readonly mutation: MutationReport;
+    readonly assertions: AssertionsReport;
+    readonly inputSig: string;
+    readonly out: string;
+    readonly thresholds?: Thresholds;
+    readonly now?: () => Date;
+}
+export declare function buildMutReport(input: BuildMutInput): Promise<MutReportJson>;

package/dist/services/mut/report-builder.js

@@ -0,0 +1,110 @@
+/**
+ * Combines MutationReport + AssertionsReport into MutReportJson, computes
+ * thresholds, derives followups, computes MUT.sig, writes file atomically.
+ *
+ * Hard constraints:
+ *   H8 (audit trail hashable): MUT.sig is sha256 of normalized content;
+ *       generatedAt + sha256 are excluded from the digest to make the
+ *       signature deterministic across runs.
+ *   H6 (CLI裁决): passed boolean + followups computed by CLI, not LLM.
+ *   KISS: keep composition narrow — input, thresholds, output file path.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, rename, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { MutReportSchema, } from './types.js';
+import { DEFAULT_THRESHOLDS, evaluateThresholds, } from './thresholds.js';
+function deriveFollowups(m, a, t) {
+    const out = [];
+    if (m.killRate < t.mutationKillRateMin) {
+        for (const f of m.byFile) {
+            if (f.killRate < t.mutationKillRateMin) {
+                out.push({
+                    file: f.file,
+                    issue: 'low_kill_rate',
+                    severity: 'soft',
+                    suggestion: `Add tests for ${f.survived.length} survived mutants in ${f.file}`,
+                });
+            }
+        }
+    }
+    if (a.weakRate > t.weakAssertionRateMax) {
+        for (const p of a.weakPatterns) {
+            if (p.count > 0) {
+                const exampleFile = p.examples[0]?.file ?? '<unknown>';
+                out.push({
+                    file: exampleFile,
+                    issue: 'high_weak_assertions',
+                    severity: 'hard',
+                    suggestion: `Replace ${p.count} weak assertions of type "${p.pattern}" with concrete value checks`,
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Recursively sort object keys to produce a canonical JSON string.
+ * Arrays preserve order; only object keys are sorted.
+ */
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => canonicalize(v));
+    }
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+        sorted[key] = canonicalize(obj[key]);
+    }
+    return sorted;
+}
+function sha256OfCanonical(value) {
+    const canonical = JSON.stringify(canonicalize(value));
+    return createHash('sha256').update(canonical).digest('hex');
+}
+/**
+ * Compute MUT.sig: sha256 of the report content excluding generatedAt and
+ * sha256 itself. Both fields are removed before canonicalization so the
+ * digest is stable across runs that differ only in timestamp.
+ */
+function computeMutSig(report) {
+    const { generatedAt: _g, ...rest } = report;
+    void _g;
+    return sha256OfCanonical(rest);
+}
+export async function buildMutReport(input) {
+    const thresholds = input.thresholds ?? DEFAULT_THRESHOLDS;
+    const now = input.now ?? (() => new Date());
+    const evalResult = evaluateThresholds(thresholds, input.mutation.killRate, input.assertions.weakRate);
+    const followups = deriveFollowups(input.mutation, input.assertions, thresholds);
+    const partial = {
+        version: '1.0',
+        generatedAt: now().toISOString(),
+        inputSig: input.inputSig,
+        mutation: input.mutation,
+        assertions: input.assertions,
+        thresholds: {
+            mutationKillRateMin: thresholds.mutationKillRateMin,
+            weakAssertionRateMax: thresholds.weakAssertionRateMax,
+            passed: evalResult.passed,
+        },
+        followups,
+    };
+    const sha256 = computeMutSig(partial);
+    const final = { ...partial, sha256 };
+    MutReportSchema.parse(final);
+    await mkdir(dirname(input.out), { recursive: true });
+    const tmp = `${input.out}.tmp`;
+    try {
+        await writeFile(tmp, JSON.stringify(final, null, 2), 'utf8');
+        await rename(tmp, input.out);
+    }
+    catch (err) {
+        await unlink(tmp).catch(() => undefined);
+        throw err;
+    }
+    return final;
+}

package/dist/services/mut/report-loader.d.ts

@@ -0,0 +1,31 @@
+import { type MutReportJson } from './types.js';
+export declare const MUT_REPORT_RELATIVE_PATH = "mut/mut-report.json";
+/**
+ * Build the canonical absolute path of a session's mut-report.json.
+ * Exported so the CLI surface in qa-commands can reuse the same
+ * constant for diagnostic messages.
+ *
+ * Uses POSIX separators intentionally: the one-axis envelope is
+ * documented as `.peaks/_runtime/<sid>/mut/mut-report.json` (forward
+ * slashes) and that path is what the hotfix 81f00ce audit-trail
+ * contract guarantees. `node:path` would produce backslashes on
+ * Windows, breaking the cross-platform invariant. POSIX join is
+ * correct here because the result is a logical path stored in JSON
+ * artifacts and CLI diagnostics — it never gets passed to OS
+ * syscalls directly (readFile / writeFile accept both forms).
+ */
+export declare function mutReportPath(sessionId: string): string;
+/**
+ * Read and validate a session's mut-report.json.
+ *
+ * Returns `null` for any of these cases:
+ *   - file does not exist (ENOENT)
+ *   - file exists but JSON is malformed
+ *   - file exists and parses but does not satisfy `MutReportSchema`
+ *
+ * Never throws. Never logs to stdout (per "no console.log in src/").
+ * Schema-parse failures are reported via `process.stderr` so the
+ * qa-runner operator can see why their report is being treated as
+ * absent.
+ */
+export declare function loadMutReport(sessionId: string): Promise<MutReportJson | null>;

package/dist/services/mut/report-loader.js

@@ -0,0 +1,78 @@
+/**
+ * Plan 2 — Task 8: peaks-qa consumes MUT.sig from peaks-mut.
+ *
+ * `loadMutReport` is the read-side counterpart of `buildMutReport`
+ * (which is the write-side). Both share the canonical path:
+ * `.peaks/_runtime/<sessionId>/mut/mut-report.json` (per hotfix 81f00ce
+ * one-axis envelope — no `.peaks/_runtime/<sessionId>/` fallback).
+ *
+ * Design contract (per spec lines 1292-1341):
+ *   - Missing file      → `null` (gate is skipped, NOT failed)
+ *   - Schema-invalid    → `null` (log via stderr; do not throw — qa is a
+ *                         pre-step, not a precondition)
+ *   - Schema-valid      → the parsed `MutReportJson`
+ *
+ * Returning `null` instead of throwing is what lets peaks-qa treat
+ * "peaks mut was not run" as a no-op. If we threw, the qa gate would
+ * crash on every session that hasn't run peaks-mut yet.
+ */
+import { readFile } from 'node:fs/promises';
+import { posix as pathPosix } from 'node:path';
+import { MutReportSchema } from './types.js';
+export const MUT_REPORT_RELATIVE_PATH = 'mut/mut-report.json';
+/**
+ * Build the canonical absolute path of a session's mut-report.json.
+ * Exported so the CLI surface in qa-commands can reuse the same
+ * constant for diagnostic messages.
+ *
+ * Uses POSIX separators intentionally: the one-axis envelope is
+ * documented as `.peaks/_runtime/<sid>/mut/mut-report.json` (forward
+ * slashes) and that path is what the hotfix 81f00ce audit-trail
+ * contract guarantees. `node:path` would produce backslashes on
+ * Windows, breaking the cross-platform invariant. POSIX join is
+ * correct here because the result is a logical path stored in JSON
+ * artifacts and CLI diagnostics — it never gets passed to OS
+ * syscalls directly (readFile / writeFile accept both forms).
+ */
+export function mutReportPath(sessionId) {
+    return pathPosix.join('.peaks', '_runtime', sessionId, MUT_REPORT_RELATIVE_PATH);
+}
+/**
+ * Read and validate a session's mut-report.json.
+ *
+ * Returns `null` for any of these cases:
+ *   - file does not exist (ENOENT)
+ *   - file exists but JSON is malformed
+ *   - file exists and parses but does not satisfy `MutReportSchema`
+ *
+ * Never throws. Never logs to stdout (per "no console.log in src/").
+ * Schema-parse failures are reported via `process.stderr` so the
+ * qa-runner operator can see why their report is being treated as
+ * absent.
+ */
+export async function loadMutReport(sessionId) {
+    const path = mutReportPath(sessionId);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // ENOENT or permission denied — both treated as "not run".
+        return null;
+    }
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[peaks-qa] mut-report at ${path} is not valid JSON; treating as absent: ${message}\n`);
+        return null;
+    }
+    const parsed = MutReportSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+        process.stderr.write(`[peaks-qa] mut-report at ${path} failed schema validation; treating as absent: ${parsed.error.message}\n`);
+        return null;
+    }
+    return parsed.data;
+}

package/dist/services/mut/thresholds.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Per spec §4.2 验收审计 — Default thresholds + evaluator.
+ *
+ * Override via `peaks-mut.config.json` at project root.
+ */
+export interface Thresholds {
+    readonly mutationKillRateMin: number;
+    readonly weakAssertionRateMax: number;
+}
+export declare const DEFAULT_THRESHOLDS: Thresholds;
+export type ThresholdViolationKind = 'mutationKillRateMin' | 'weakAssertionRateMax';
+export interface ThresholdViolation {
+    readonly kind: ThresholdViolationKind;
+    readonly actual: number;
+    readonly threshold: number;
+}
+export interface ThresholdEvaluation {
+    readonly passed: boolean;
+    readonly violations: ReadonlyArray<ThresholdViolation>;
+}
+export declare function evaluateThresholds(t: Thresholds, actualKillRate: number, actualWeakRate: number): ThresholdEvaluation;

package/dist/services/mut/thresholds.js

@@ -0,0 +1,22 @@
+export const DEFAULT_THRESHOLDS = Object.freeze({
+    mutationKillRateMin: 0.80,
+    weakAssertionRateMax: 0.05,
+});
+export function evaluateThresholds(t, actualKillRate, actualWeakRate) {
+    const violations = [];
+    if (actualKillRate < t.mutationKillRateMin) {
+        violations.push({
+            kind: 'mutationKillRateMin',
+            actual: actualKillRate,
+            threshold: t.mutationKillRateMin,
+        });
+    }
+    if (actualWeakRate > t.weakAssertionRateMax) {
+        violations.push({
+            kind: 'weakAssertionRateMax',
+            actual: actualWeakRate,
+            threshold: t.weakAssertionRateMax,
+        });
+    }
+    return { passed: violations.length === 0, violations };
+}