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

code_forge/env_resolver.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""CLI-03 env override resolution (cli_value > env > default).
+
+FORGE_MODE is intentionally NOT here -- 02-04 resolve_mode owns it.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from .disposition import MAX_FIX_ATTEMPTS_PER_FINGERPRINT
+from .errors import CliError
+
+
+DEFAULT_MAX_TOTAL_ROUNDS = 20
+MAX_REASONABLE_FIX_ATTEMPTS = 100   # sanity bound
+MAX_REASONABLE_TOTAL_ROUNDS = 1000  # sanity bound
+
+
+def resolve_max_total_rounds(
+    cli_value: Optional[int], env: Mapping[str, str]
+) -> int:
+    """Resolve max total rounds: cli > env > default (20)."""
+    if cli_value is not None:
+        return _validate_int(
+            cli_value, "--max-total-rounds", MAX_REASONABLE_TOTAL_ROUNDS
+        )
+    raw = env.get("FORGE_MAX_TOTAL_ROUNDS")
+    if raw is None or raw == "":
+        return DEFAULT_MAX_TOTAL_ROUNDS
+    return _parse_env_int(
+        raw, "FORGE_MAX_TOTAL_ROUNDS", MAX_REASONABLE_TOTAL_ROUNDS
+    )
+
+
+def resolve_max_fix_attempts(
+    cli_value: Optional[int], env: Mapping[str, str]
+) -> int:
+    """Resolve max fix attempts: cli > env > default (3)."""
+    if cli_value is not None:
+        return _validate_int(
+            cli_value, "--max-fix-attempts", MAX_REASONABLE_FIX_ATTEMPTS
+        )
+    raw = env.get("FORGE_MAX_FIX_ATTEMPTS_PER_FINGERPRINT")
+    if raw is None or raw == "":
+        return MAX_FIX_ATTEMPTS_PER_FINGERPRINT
+    return _parse_env_int(
+        raw, "FORGE_MAX_FIX_ATTEMPTS_PER_FINGERPRINT",
+        MAX_REASONABLE_FIX_ATTEMPTS,
+    )
+
+
+def resolve_falsification_engine(
+    cli_value: Optional[str], env: Mapping[str, str]
+) -> str:
+    """Resolve falsification engine: cli > env > default (auto)."""
+    if cli_value is not None:
+        return cli_value
+    raw = env.get("FORGE_FALSIFICATION_ENGINE")
+    if raw is None or raw == "":
+        return "auto"
+    key = raw.strip().lower()
+    if key not in {"auto", "stub", "real"}:
+        raise CliError(
+            "invalid FORGE_FALSIFICATION_ENGINE: %r "
+            "(expected auto|stub|real)" % raw
+        )
+    return key
+
+
+def _parse_env_int(raw: str, name: str, sanity_cap: int) -> int:
+    """Parse string env value to int with validation."""
+    try:
+        value = int(raw.strip())
+    except ValueError:
+        raise CliError("invalid %s: %r (expected int)" % (name, raw))
+    return _validate_int(value, name, sanity_cap)
+
+
+def _validate_int(value: int, name: str, sanity_cap: int) -> int:
+    """Validate int >= 1 and <= sanity_cap."""
+    if value < 1:
+        raise CliError(
+            "invalid %s: %d (must be >= 1)" % (name, value)
+        )
+    if value > sanity_cap:
+        raise CliError(
+            "invalid %s: %d (exceeds sanity cap %d)"
+            % (name, value, sanity_cap)
+        )
+    return value

code_forge/errors.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Forge-specific error types for state management."""
+
+
+class SchemaVersionMismatchError(Exception):
+    """Raised when state.json schema_version does not match expected."""
+
+
+class CorruptedStateError(Exception):
+    """Raised when state.json is corrupt or internally inconsistent."""
+
+
+class BaselineResolutionError(Exception):
+    """Raised when baseline resolution fails (invalid ref, bad combination)."""
+
+
+class SnapshotSchemaMismatchError(Exception):
+    """Raised when snapshot schema_version does not match expected."""
+
+
+class CorruptedSnapshotError(Exception):
+    """Raised when snapshot file is corrupt or unparseable."""
+
+
+class CliError(Exception):
+    """Raised on invalid CLI args or env values.
+
+    main() catches and maps to EXIT_CLI_ERROR (exit 2).
+    """
+
+
+class ComponentsConfigError(Exception):
+    """Raised when .code-forge/components.yaml fails schema validation."""

code_forge/exit_codes.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""CLI-02 exit code constants + Verdict -> exit mapping.
+
+Phase 1 cli.py had EXIT_PASS / EXIT_FAIL inline. 02-05 promotes them
+to a dedicated module and adds CLI_ERROR / BUSY / ESCALATED.
+"""
+from __future__ import annotations
+
+from .state import Verdict
+
+
+EXIT_PASS = 0
+EXIT_FAIL = 1
+EXIT_CLI_ERROR = 2
+EXIT_BUSY = 3
+EXIT_ESCALATED = 4
+
+
+def verdict_to_exit(verdict: Verdict) -> int:
+    """Map terminal Verdict to CLI-02 exit code.
+
+    Raises ValueError on Verdict.PENDING (caller bug: HOLD should have
+    been consumed by HOLD-resume loop before reaching this mapping).
+    """
+    if verdict == Verdict.PASS:
+        return EXIT_PASS
+    if verdict == Verdict.FAIL:
+        return EXIT_FAIL
+    if verdict == Verdict.ESCALATED:
+        return EXIT_ESCALATED
+    if verdict == Verdict.PENDING:
+        raise ValueError(
+            "verdict_to_exit called with PENDING; HOLD-resume loop "
+            "must consume PENDING before terminal mapping"
+        )
+    raise ValueError("unknown verdict: %r" % verdict)

code_forge/factories.py

@@ -0,0 +1,191 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""STATE-10 falsifier + autofixer + revert_fn factories.
+
+Centralizes "which impl do we instantiate" decisions so cli.py stays
+declarative and Phase 4 can swap impls without touching the CLI.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Callable
+
+from .autofix import AutoFixer, FixOutcome, StubAutoFixer
+from .baseline import ResolvedReview
+from .disposition import Disposition
+from .falsify import Falsifier, StubFalsifier
+from .e2e_check import run_e2e_check
+from .mutation import run_mutation
+from .state import StateFinding
+
+
+def build_falsifier(engine: str) -> Falsifier:
+    """STATE-10 engine factory.
+
+    engine = "auto": try Phase 4 import; fall back to stub if absent.
+    engine = "stub": always StubFalsifier.
+    engine = "real": Phase 4 falsifier (NOT shipped v2.0).
+    """
+    if engine == "stub":
+        return StubFalsifier()
+    if engine == "auto":
+        try:
+            from .falsify_real import RealFalsifier  # noqa: F401
+            return RealFalsifier()
+        except ImportError:
+            return StubFalsifier()
+    if engine == "real":
+        try:
+            from .falsify_real import RealFalsifier
+            return RealFalsifier()
+        except ImportError:
+            raise NotImplementedError(
+                "--falsification-engine=real requires Phase 4 "
+                "(not shipped in v2.0). Use "
+                "--falsification-engine=auto or =stub."
+            )
+    raise ValueError(
+        "unknown engine: %r (expected auto|stub|real)" % engine
+    )
+
+
+def build_autofixer(resolved: ResolvedReview) -> AutoFixer:
+    """v2.0 returns StubAutoFixer; non-git wraps to prevent PARSE_FAIL.
+
+    R2-M1: non-git mode wraps StubAutoFixer in _NonGitSafeAutoFixer
+    to convert PARSE_FAIL -> NO_CHANGE, preventing revert_fn from
+    being invoked (which would raise NotImplementedError per B1).
+    """
+    base = StubAutoFixer()
+    if resolved.mode_hint == "non-git":
+        return _NonGitSafeAutoFixer(base)
+    return base
+
+
+class _NonGitSafeAutoFixer(AutoFixer):
+    """R2-M1 wrapper: convert PARSE_FAIL -> NO_CHANGE in non-git mode.
+
+    Prevents StateMachine from calling revert_fn (which raises
+    NotImplementedError per B1 in non-git mode). Behavior:
+      - PARSE_FAIL -> NO_CHANGE (consumes fix budget; no revert call)
+      - SUCCESS / NO_CHANGE / EXCEPTION pass through unchanged
+
+    R3-7: fix signature byte-equal to AutoFixer ABC.
+    """
+
+    def __init__(self, inner: AutoFixer):
+        super().__init__()
+        self._inner = inner
+
+    def fix(self, finding: StateFinding, mode_hint: str) -> FixOutcome:
+        """Wrap inner fix; convert PARSE_FAIL to NO_CHANGE."""
+        outcome = self._inner.fix(finding, mode_hint)
+        if outcome == FixOutcome.PARSE_FAIL:
+            return FixOutcome.NO_CHANGE
+        return outcome
+
+
+def build_revert_fn(
+    resolved: ResolvedReview, cwd: Path
+) -> Callable[[StateFinding], None]:
+    """Build revert_fn for StateMachine constructor.
+
+    Dispatches on resolved.mode_hint:
+      "git"     -> git restore <file>
+      "non-git" -> NotImplementedError (B1: v2.0 limitation)
+    """
+    if resolved.mode_hint == "git":
+        return _make_git_restore(cwd)
+    if resolved.mode_hint == "non-git":
+        return _make_snapshot_restore(cwd, resolved)
+    raise ValueError("unknown mode_hint: %r" % resolved.mode_hint)
+
+
+def _make_git_restore(
+    cwd: Path,
+) -> Callable[[StateFinding], None]:
+    """Git mode revert: restore file to index version."""
+    def _revert(finding: StateFinding) -> None:
+        subprocess.run(
+            ["git", "restore", "--", finding.file],
+            cwd=str(cwd), check=True,
+        )
+    return _revert
+
+
+def _make_snapshot_restore(
+    cwd: Path, resolved: ResolvedReview
+) -> Callable[[StateFinding], None]:
+    """B1: non-git revert NOT supported in v2.0.
+
+    02-03 Snapshot stores content_hash only, not raw content.
+    revert_fn raises NotImplementedError unconditionally.
+    """
+    def _revert(finding: StateFinding) -> None:
+        raise NotImplementedError(
+            "non-git autofix revert is not supported in v2.0 "
+            "(02-03 Snapshot stores content_hash, not raw content). "
+            "Use git mode for autofix, or configure autofixer to "
+            "avoid PARSE_FAIL outcomes in non-git mode. "
+            "Tracked as v2.x candidate."
+        )
+    return _revert
+
+
+def build_l2_runner() -> Callable:
+    """Build l2_runner (mutation testing) callable.
+
+    Returns a callable with signature:
+        (diff_files: list[str], baseline_cmd: list[str])
+        -> tuple[list[StateFinding], list[str]]
+
+    If mutmut is not on PATH, returns a no-op callable that produces
+    a single MUTATION_SKIPPED finding (soft dependency).
+
+    The returned callable delegates to run_mutation from the mutation
+    module when mutmut is available.
+    """
+    if shutil.which("mutmut") is None:
+        # mutmut not available, return no-op with MUTATION_SKIPPED
+        def _no_mutation(
+            diff_files: list[str],
+            baseline_cmd: list[str],
+        ) -> tuple[list[StateFinding], list[str]]:
+            findings = [
+                StateFinding(
+                    id="MUTATION_SKIPPED",
+                    fingerprint="mutation-unavailable",
+                    source="MUTANT",
+                    disposition=Disposition.DISMISSED,
+                    file="",
+                    line_range=[],
+                    description="mutmut not installed (soft dependency)",
+                )
+            ]
+            infra_errors = ["mutmut not found on PATH"]
+            return (findings, infra_errors)
+        return _no_mutation
+
+    # mutmut is available, delegate to run_mutation
+    return run_mutation
+
+
+def build_e2e_checker() -> Callable:
+    """Build e2e_checker callable for R3 coverage heuristic.
+
+    Returns a callable with signature:
+        (diff_text: str, repo_root: Path)
+        -> tuple[list[StateFinding], list[str]]
+
+    Unlike build_l2_runner, there is no external-binary availability check:
+    e2e_check has no soft dependency (unidiff is a hard dep already used by
+    diff.py). The factory returns run_e2e_check directly.
+
+    The factory exists for symmetry with build_l2_runner so plan 03-03 can
+    inject it into the state machine the same way as l2_runner, and a future
+    variant (e.g. with config loading) can be swapped without touching
+    machine.py.
+    """
+    return run_e2e_check

code_forge/falsify.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Abstract Falsifier interface + Stub implementation.
+
+Phase 4 will provide the real Falsifier. 02-01 stub allows state machine
+to be built and tested without Phase 4.
+
+This module imports StateFinding from code_forge.state (NOT the Phase 1
+forge.parsers.base.Finding). StateFinding is the persisted-in-state.json
+representation; parsers.base.Finding is the parser-emitted record.
+"""
+
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+from .disposition import Disposition
+from .state import StateFinding
+
+
+class Falsifier(ABC):
+    """Abstract base for falsification engines.
+
+    falsify() must NOT return Disposition.FIXED (FIXED is a state machine
+    transition after auto-fix, not a falsifier output).
+    """
+
+    @abstractmethod
+    def falsify(self, finding: StateFinding) -> Disposition:
+        """Classify a finding as CONFIRMED, DISMISSED, or UNCERTAIN.
+
+        Returning FIXED raises ValueError (state machine concern).
+        """
+        ...
+
+
+class StubFalsifier(Falsifier):
+    """Returns configurable Dispositions for tests.
+
+    Config format (JSON):
+      {
+        "default": "CONFIRMED",
+        "dispositions": {"fp-xxx": "DISMISSED", ...},
+        "errors":       {"fp-yyy": "timeout", ...}
+      }
+
+    Precedence: errors checked before dispositions/default.
+    FIXED in any disposition position is rejected at constructor AND
+    at falsify() time (defense in depth).
+    """
+
+    def __init__(self, fixture_path: Optional[Path] = None):
+        self._dispositions: dict[str, Disposition] = {}
+        self._errors: dict[str, str] = {}
+        self._default = Disposition.CONFIRMED
+        if fixture_path:
+            data = json.loads(fixture_path.read_text())
+            self._default = Disposition(data.get("default", "CONFIRMED"))
+            if self._default == Disposition.FIXED:
+                raise ValueError(
+                    "FIXED is not a valid falsifier output (default)"
+                )
+            self._dispositions = {}
+            for fp, d in data.get("dispositions", {}).items():
+                disp = Disposition(d)
+                if disp == Disposition.FIXED:
+                    raise ValueError(
+                        "FIXED is not a valid falsifier output "
+                        "(fingerprint %s)" % fp
+                    )
+                self._dispositions[fp] = disp
+            self._errors = dict(data.get("errors", {}))
+
+    def falsify(self, finding: StateFinding) -> Disposition:
+        """Return configured disposition or raise on error key."""
+        if finding.fingerprint in self._errors:
+            raise RuntimeError(
+                "stub-simulated falsification error: %s"
+                % self._errors[finding.fingerprint]
+            )
+        disp = self._dispositions.get(finding.fingerprint, self._default)
+        if disp == Disposition.FIXED:
+            raise ValueError("FIXED is not a valid falsifier output")
+        return disp