code-review-forge 2.0.0a1__py3-none-any.whl

code_forge/mode_resolver.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""STATE-06 mode resolution.
+
+Pure precedence function: CLI flag > FORGE_MODE env > TTY default.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from .state import Mode
+
+
+VALID_MODE_STRINGS = {"local": Mode.LOCAL, "ci": Mode.CI}
+
+
+def resolve_mode(
+    cli_arg: Optional[str],
+    env: Mapping[str, str],
+    stdout_isatty: bool,
+) -> Mode:
+    """Resolve effective Mode given inputs.
+
+    Precedence (highest first):
+      1. cli_arg if not None (CLI --mode flag value)
+      2. env["FORGE_MODE"] if present and non-empty
+      3. default: Mode.LOCAL if stdout_isatty else Mode.CI
+
+    String values are case-insensitive ("local", "Local", "LOCAL" all OK).
+    Invalid string (anywhere) raises ValueError with the offending value.
+    Empty FORGE_MODE ("") falls through to TTY default (M3 fix).
+    Whitespace-only FORGE_MODE ("  ") raises ValueError (L1 fix).
+
+    Args:
+      cli_arg: value from argparse --mode (None if not provided)
+      env: os.environ or test-injected mapping
+      stdout_isatty: result of sys.stdout.isatty() at process start
+
+    Returns:
+      Mode.LOCAL or Mode.CI
+
+    Raises:
+      ValueError: cli_arg or env value not in {"local", "ci"}
+    """
+    if cli_arg is not None:
+        return _parse_mode_string(cli_arg, source="--mode")
+    env_value = env.get("FORGE_MODE")
+    if env_value is not None and env_value != "":
+        return _parse_mode_string(env_value, source="FORGE_MODE env")
+    return Mode.LOCAL if stdout_isatty else Mode.CI
+
+
+def _parse_mode_string(value: str, source: str) -> Mode:
+    """Lower + lookup; raise with source attribution on miss."""
+    key = value.strip().lower()
+    if key not in VALID_MODE_STRINGS:
+        raise ValueError(
+            "invalid mode %r from %s (expected: local|ci)" % (value, source)
+        )
+    return VALID_MODE_STRINGS[key]

code_forge/mutation.py

@@ -0,0 +1,380 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Mutation testing integration via mutmut subprocess.
+
+Python-only MVP. Runs mutmut on diff-scoped files and parses survivors.
+Swappable design: keep subprocess calls in one place so future language
+runners (cargo-mutants, go-mutesting) can replace implementation without
+changing the l2_runner interface.
+
+mutmut 3.x integration notes:
+- No --paths-to-mutate CLI flag; use setup.cfg [mutmut] paths_to_mutate.
+- Run cwd MUST be the project root (where src/ and tests/ live).
+- paths_to_mutate must be relative to the project root.
+- PYTHONPATH must point into src/ so imports resolve without src. prefix.
+- results format: "    module.fn__mutmut_N: status" (one per line).
+- Any non-zero exit code from mutmut run is a hard error.
+- A temporary setup.cfg is written to project root and cleaned up after.
+- mutants/ directory created by mutmut is also cleaned up after each run.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from .disposition import Disposition
+from .state import StateFinding
+
+# Marker in setup.cfg so we never accidentally overwrite user config
+_CODE_FORGE_CFG_MARKER = "# managed-by-code-forge-mutation"
+
+
+@dataclass
+class Survivor:
+    """A mutant that survived (no test killed it)."""
+    mutant_name: str  # mutmut 3.x identifier e.g. "code_forge.mutation.x_run__mutmut_1"
+    file: str         # source file (empty; mutmut 3.x results omit file paths)
+
+
+def parse_mutmut_results(stdout: str) -> tuple[list[Survivor], list[str]]:
+    """Parse mutmut 3.x results output to extract surviving mutants.
+
+    Expected format from mutmut 3.x results command:
+        {indent}{module}.{mangled_fn}__mutmut_{N}: {status}
+
+    Where status is one of: survived, killed, no tests, not checked,
+    timeout, suspicious, check was interrupted by user.
+
+    Only lines with status "survived" are returned as Survivor objects.
+
+    The mutant_name is the full identifier (e.g. "add.x_add__mutmut_1").
+    The file field is empty string since mutmut 3.x results do not include
+    file paths; callers that need file attribution must use py_files list.
+
+    Args:
+        stdout: raw stdout from mutmut results subprocess
+
+    Returns:
+        tuple[list[Survivor], list[str]] where second element is warnings
+        about unparseable lines. Never raises.
+    """
+    survivors = []
+    warnings = []
+
+    for line in stdout.split("\n"):
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        # Format: "module.fn__mutmut_N: status"
+        if ": " not in stripped:
+            continue
+
+        mutant_name, _, status = stripped.partition(": ")
+        mutant_name = mutant_name.strip()
+        status = status.strip()
+
+        if not mutant_name:
+            continue
+
+        if status == "survived":
+            survivors.append(Survivor(mutant_name=mutant_name, file=""))
+
+    return survivors, warnings
+
+
+def run_mutation(
+    diff_files: list[str],
+    baseline_cmd: list[str],
+    timeout: int = 600,
+    cwd: Path | None = None,
+) -> tuple[list[StateFinding], list[str]]:
+    """Run mutation testing on diff-scoped files.
+
+    Returns tuple[list[StateFinding], list[str]] matching l0_runner
+    signature for consistency.
+
+    Args:
+        diff_files: changed files from git diff --name-only (relative to cwd)
+        baseline_cmd: test command to run for flaky guard and mutmut
+        timeout: mutmut run timeout in seconds (default 600)
+        cwd: project root for mutmut (default: Path.cwd()). Must be the
+            directory containing src/ and tests/.
+
+    Implementation note:
+        mutmut 3.x requires cwd to be the project root. A temporary
+        setup.cfg is written there with paths_to_mutate pointing to the
+        diff-scoped files. The mutants/ directory and temporary setup.cfg
+        are cleaned up after each run.
+
+    Returns:
+        (findings, infra_errors) where findings contains:
+        - CONFIRMED MUTANT findings for survivors
+        - DISMISSED MUTATION_SKIPPED findings for skip conditions
+    """
+    findings: list[StateFinding] = []
+    infra_errors: list[str] = []
+
+    if cwd is None:
+        cwd = Path.cwd()
+    repo_root = str(cwd.resolve())
+
+    # Empty files: no work
+    if not diff_files:
+        return ([], [])
+
+    # Filter to .py files only (Python MVP)
+    py_files = [f for f in diff_files if f.endswith(".py")]
+    if not py_files:
+        findings.append(
+            StateFinding(
+                id="MUTATION_SKIPPED",
+                fingerprint="mutation-no-python",
+                source="MUTANT",
+                disposition=Disposition.DISMISSED,
+                file="",
+                line_range=[],
+                description="no Python files in diff (mutation is Python-only MVP)",
+            )
+        )
+        infra_errors.append("no Python files in diff")
+        return (findings, infra_errors)
+
+    # Flaky guard: run baseline 3x from repo root
+    run_env = os.environ.copy()
+    run_env["PYTHONPATH"] = os.path.join(repo_root, "src")
+
+    for run_num in range(1, 4):
+        try:
+            result = subprocess.run(
+                baseline_cmd,
+                env=run_env,
+                capture_output=True,
+                text=True,
+                timeout=120,
+                check=False,
+                cwd=repo_root,
+            )
+            if result.returncode != 0:
+                findings.append(
+                    StateFinding(
+                        id="MUTATION_SKIPPED",
+                        fingerprint="mutation-flaky",
+                        source="MUTANT",
+                        disposition=Disposition.DISMISSED,
+                        file="",
+                        line_range=[],
+                        description=(
+                            "run %d: tests flaky, mutation unreliable "
+                            "(3x baseline check)" % run_num
+                        ),
+                    )
+                )
+                infra_errors.append(
+                    "flaky guard: baseline failed on run %d" % run_num
+                )
+                return (findings, infra_errors)
+        except subprocess.TimeoutExpired:
+            findings.append(
+                StateFinding(
+                    id="MUTATION_SKIPPED",
+                    fingerprint="mutation-baseline-timeout",
+                    source="MUTANT",
+                    disposition=Disposition.DISMISSED,
+                    file="",
+                    line_range=[],
+                    description="baseline tests timed out (flaky guard)",
+                )
+            )
+            infra_errors.append(
+                "flaky guard: baseline timeout on run %d" % run_num
+            )
+            return (findings, infra_errors)
+
+    # Check mutmut availability
+    if shutil.which("mutmut") is None:
+        findings.append(
+            StateFinding(
+                id="MUTATION_SKIPPED",
+                fingerprint="mutation-unavailable",
+                source="MUTANT",
+                disposition=Disposition.DISMISSED,
+                file="",
+                line_range=[],
+                description="mutmut not installed (soft dependency)",
+            )
+        )
+        return (findings, [])
+
+    # Refuse to overwrite user's existing setup.cfg or [tool.mutmut] config.
+    setup_cfg_path = os.path.join(repo_root, "setup.cfg")
+    pyproject_path = os.path.join(repo_root, "pyproject.toml")
+    wrote_setup_cfg = False
+    try:
+        has_user_setup_cfg = False
+        if os.path.exists(setup_cfg_path):
+            with open(setup_cfg_path, encoding="utf-8") as _fh:
+                has_user_setup_cfg = _CODE_FORGE_CFG_MARKER not in _fh.read()
+        has_user_pyproject_mutmut = False
+        if os.path.exists(pyproject_path):
+            try:
+                with open(pyproject_path, encoding="utf-8") as fh:
+                    raw = fh.read()
+                has_user_pyproject_mutmut = "[tool.mutmut]" in raw
+            except OSError:
+                pass
+
+        if has_user_setup_cfg or has_user_pyproject_mutmut:
+            infra_errors.append(
+                "mutmut config conflict: project already has [mutmut] or "
+                "[tool.mutmut] config; forge cannot override it safely"
+            )
+            findings.append(
+                StateFinding(
+                    id="MUTATION_SKIPPED",
+                    fingerprint="mutation-config-conflict",
+                    source="MUTANT",
+                    disposition=Disposition.DISMISSED,
+                    file="",
+                    line_range=[],
+                    description=(
+                        "mutmut config conflict: existing setup.cfg or "
+                        "pyproject.toml [tool.mutmut] detected"
+                    ),
+                )
+            )
+            return (findings, infra_errors)
+
+        # Write temporary setup.cfg to project root.
+        # paths_to_mutate are relative to the project root.
+        config_content = (
+            "%s\n"
+            "[mutmut]\n"
+            "paths_to_mutate=%s\n"
+            % (_CODE_FORGE_CFG_MARKER, ",".join(py_files))
+        )
+
+        # Write to a temp file first, then rename for atomicity
+        fd, tmp_cfg = tempfile.mkstemp(
+            prefix=".code-forge-mutation-cfg-",
+            dir=repo_root,
+            suffix=".cfg",
+        )
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                fh.write(config_content)
+            os.rename(tmp_cfg, setup_cfg_path)
+            wrote_setup_cfg = True
+        except OSError:
+            try:
+                os.unlink(tmp_cfg)
+            except OSError:
+                pass
+            raise
+
+        try:
+            result = subprocess.run(
+                ["mutmut", "run"],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+                env=run_env,
+                cwd=repo_root,
+            )
+
+            # Any non-zero exit is an error (attempt 2 bug: only caught ==2)
+            if result.returncode != 0:
+                findings.append(
+                    StateFinding(
+                        id="MUTATION_ERROR",
+                        fingerprint="mutation-invocation-error",
+                        source="MUTANT",
+                        disposition=Disposition.CONFIRMED,
+                        file="",
+                        line_range=[],
+                        description=(
+                            "mutmut run failed (exit %d): %s"
+                            % (result.returncode, result.stderr[:200])
+                        ),
+                    )
+                )
+                infra_errors.append(
+                    "mutmut error (exit %d): %s"
+                    % (result.returncode, result.stderr[:100])
+                )
+                return (findings, infra_errors)
+
+        except subprocess.TimeoutExpired:
+            findings.append(
+                StateFinding(
+                    id="MUTATION_SKIPPED",
+                    fingerprint="mutation-timeout",
+                    source="MUTANT",
+                    disposition=Disposition.DISMISSED,
+                    file="",
+                    line_range=[],
+                    description="mutmut timed out after %ds" % timeout,
+                )
+            )
+            return (findings, [])
+
+        # Parse results from repo_root
+        try:
+            results_proc = subprocess.run(
+                ["mutmut", "results"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+                check=False,
+                cwd=repo_root,
+                env=run_env,
+            )
+            survivors, parse_warnings = parse_mutmut_results(results_proc.stdout)
+            infra_errors.extend(parse_warnings)
+        except subprocess.TimeoutExpired:
+            findings.append(
+                StateFinding(
+                    id="MUTATION_SKIPPED",
+                    fingerprint="mutation-results-timeout",
+                    source="MUTANT",
+                    disposition=Disposition.DISMISSED,
+                    file="",
+                    line_range=[],
+                    description="mutmut results timed out",
+                )
+            )
+            return (findings, [])
+
+        # Convert survivors to findings
+        for survivor in survivors:
+            findings.append(
+                StateFinding(
+                    id="mutant-%s" % survivor.mutant_name,
+                    fingerprint="mutant:%s" % survivor.mutant_name,
+                    source="MUTANT",
+                    disposition=Disposition.CONFIRMED,
+                    file=survivor.file,
+                    line_range=[0, 0],  # mutmut 3.x results omit line numbers
+                    description=(
+                        "mutant survived: %s" % survivor.mutant_name
+                    ),
+                )
+            )
+
+    finally:
+        # Clean up temporary setup.cfg and mutants/ directory
+        if wrote_setup_cfg:
+            try:
+                os.unlink(setup_cfg_path)
+            except OSError:
+                pass
+        mutants_dir = os.path.join(repo_root, "mutants")
+        shutil.rmtree(mutants_dir, ignore_errors=True)
+
+    return (findings, infra_errors)

code_forge/parsers/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Parser subsystem -- tool output to Finding conversion.
+
+Exports PARSER_DISPATCH (format -> parser function) and parse_output()
+for dispatch by output_format string.
+"""
+
+from code_forge.parsers.base import Finding, ToolError
+from code_forge.parsers.shellcheck import parse_shellcheck
+from code_forge.parsers.ruff import parse_ruff
+from code_forge.parsers.semgrep import parse_semgrep
+from code_forge.parsers.clippy import parse_clippy
+from code_forge.parsers.checkpatch import parse_checkpatch
+from code_forge.parsers.non_ascii import parse_non_ascii
+from code_forge.parsers._sarif import _parse_sarif
+
+# 5 keys map to 6 tools: ruff and semgrep both use output_format="sarif"
+# in tools.yaml, dispatching to the shared _parse_sarif function.
+# The tool_name parameter distinguishes them in the Finding objects.
+PARSER_DISPATCH: dict = {
+    "shellcheck_json": parse_shellcheck,
+    "sarif": _parse_sarif,
+    "clippy_json": parse_clippy,
+    "checkpatch_emacs": parse_checkpatch,
+    "grep_line": parse_non_ascii,
+}
+
+
+def parse_output(
+    output: str,
+    output_format: str,
+    tool_name: str,
+    exit_code: int = 0,
+) -> list[Finding | ToolError]:
+    """Dispatch to the correct parser by output_format.
+
+    Raises KeyError on unknown format (registry validation happens
+    at dispatch time per Mimo F-01).
+    """
+    parser_fn = PARSER_DISPATCH[output_format]
+    return parser_fn(output, tool_name, exit_code)
+
+
+__all__ = [
+    "Finding",
+    "ToolError",
+    "PARSER_DISPATCH",
+    "parse_output",
+    "parse_shellcheck",
+    "parse_ruff",
+    "parse_semgrep",
+    "parse_clippy",
+    "parse_checkpatch",
+    "parse_non_ascii",
+]

code_forge/parsers/_sarif.py

@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Shared SARIF 2.1.0 parser for ruff and semgrep (DRY)."""
+
+import json
+
+from code_forge.parsers.base import Finding, ToolError
+
+
+def _parse_sarif(
+    output: str,
+    tool_name: str,
+    exit_code: int = 0,
+) -> list[Finding | ToolError]:
+    """Parse SARIF 2.1.0 JSON into Finding objects.
+
+    Shared by ruff and semgrep -- tool_name distinguishes them.
+
+    Returns:
+        [] on empty string (clean run).
+        [Finding, ...] on valid SARIF with results.
+        [ToolError] on malformed/unparseable output.
+    """
+    if not output.strip():
+        return []
+    try:
+        sarif = json.loads(output)
+    except (json.JSONDecodeError, ValueError):
+        return [ToolError(
+            tool_name=tool_name,
+            exit_code=exit_code,
+            stderr="",
+            message=f"Failed to parse {tool_name} SARIF output",
+        )]
+
+    findings = []
+    try:
+        for run in sarif.get("runs", []):
+            for result in run.get("results", []):
+                for location in result.get("locations", []):
+                    phys = location.get("physicalLocation", {})
+                    artifact = phys.get("artifactLocation", {})
+                    region = phys.get("region", {})
+                    uri = artifact.get("uri", "")
+                    # Strip file:// prefix
+                    if uri.startswith("file:///"):
+                        uri = uri[len("file:///"):]
+                    elif uri.startswith("file://"):
+                        uri = uri[len("file://"):]
+                    start_line = region.get("startLine", 0)
+                    end_line_raw = region.get("endLine")
+                    findings.append(Finding(
+                        file=uri,
+                        line=start_line,
+                        end_line=(
+                            end_line_raw if end_line_raw is not None
+                            else start_line
+                        ),
+                        column=(region.get("startColumn") or 0),
+                        rule_id=result.get("ruleId", "unknown"),
+                        level=result.get("level", "warning"),
+                        message=(
+                            result.get("message", {}).get("text", "")
+                        ),
+                        tool_name=tool_name,
+                    ))
+    except (KeyError, TypeError, AttributeError):
+        return [ToolError(
+            tool_name=tool_name,
+            exit_code=exit_code,
+            stderr="",
+            message=(
+                f"Failed to parse {tool_name} SARIF output: "
+                "unexpected structure"
+            ),
+        )]
+    return findings

code_forge/parsers/base.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Base types for the forge parser subsystem.
+
+Finding: frozen dataclass representing a single tool finding.
+ToolError: sentinel type representing a tool execution failure.
+"""
+
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A single finding from a deterministic tool.
+
+    All fields are immutable (frozen=True). The `fix` field is optional
+    and defaults to None when no suggested fix is available.
+    """
+
+    file: str           # relative path from repo root
+    line: int           # 1-based start line
+    end_line: int       # 1-based end line (same as line if single-line)
+    column: int         # 1-based start column (0 if unknown)
+    rule_id: str        # tool-specific rule identifier
+    level: str          # "error" | "warning" | "note"
+    message: str        # human-readable description
+    tool_name: str      # which tool produced this
+    fix: Optional[str] = None  # suggested fix text
+
+    def to_dict(self) -> dict:
+        """Serialize to plain dict for JSON state persistence."""
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class ToolError:
+    """Sentinel returned by parsers when tool execution failed.
+
+    Distinguishes 'no findings' (empty list) from 'tool crashed'
+    (ToolError in list). Addresses review Consensus #4: tool crash
+    must not produce false PASS.
+
+    Downstream code checks ``isinstance(item, ToolError)`` to
+    distinguish tool failure from a clean run.
+    """
+
+    tool_name: str   # which tool failed
+    exit_code: int   # tool's exit code
+    stderr: str      # stderr output (for diagnostics)
+    message: str     # human-readable error description
+
+    def to_dict(self) -> dict:
+        """Serialize to plain dict for JSON state persistence.
+
+        Addresses Round 3 C-3: state.py needs to serialize ToolError
+        to state.json via this method. Without it, json.dumps crashes
+        on ToolError objects.
+        """
+        return {
+            "tool_name": self.tool_name,
+            "exit_code": self.exit_code,
+            "stderr": self.stderr,
+            "message": self.message,
+        }