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

code_forge/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Forge -- 3-state quality gate for code review."""
+
+__version__ = "2.0.0a1"
+
+# Exit code constants re-exported from exit_codes module (H5 + R3-L3).
+from .exit_codes import (
+    EXIT_BUSY,
+    EXIT_CLI_ERROR,
+    EXIT_ESCALATED,
+    EXIT_FAIL,
+    EXIT_PASS,
+)

code_forge/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Enable ``python3 -m forge`` invocation (R5-M1)."""
+
+from code_forge.cli import main
+
+if __name__ == "__main__":
+    main()

code_forge/autofix.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""AutoFixer abstract interface + Stub implementation.
+
+Parallel to forge.falsify -- Phase 4 will plug in real AI auto-fix; 02-02
+ships stub for DISPO-04/05/06 behavior tests.
+
+Design per R1 B2: AutoFixer is pure (returns FixOutcome only, no I/O,
+no revert). StateMachine.revert_fn handles the revert side-effect.
+"""
+from abc import ABC, abstractmethod
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+import json
+
+from .state import StateFinding
+
+
+class FixOutcome(str, Enum):
+    """Auto-fix result.
+
+    State machine consumes to drive DISPO-04/05/06 transitions:
+      SUCCESS    - fix applied, no parse errors; finding -> FIXED
+      PARSE_FAIL - fix produced syntax error; revert + fix_attempts++
+      NO_CHANGE  - autofixer refused; fix_attempts++ (no revert needed)
+      EXCEPTION  - autofixer raised; infra_errors + fix_attempts++
+    """
+    SUCCESS = "SUCCESS"
+    PARSE_FAIL = "PARSE_FAIL"
+    NO_CHANGE = "NO_CHANGE"
+    EXCEPTION = "EXCEPTION"
+
+
+class AutoFixer(ABC):
+    """Abstract base for auto-fix engines."""
+
+    @abstractmethod
+    def fix(self, finding: StateFinding, mode_hint: str) -> FixOutcome:
+        """Attempt to fix a CONFIRMED finding.
+
+        mode_hint: "git" | "non-git" -- passed through; consumed by the
+        state machine's revert_fn (NOT by AutoFixer) per R1 B2 design:
+          - AutoFixer is pure (returns FixOutcome, no I/O, no revert).
+          - StateMachine.revert_fn handles the revert side-effect:
+            * mode_hint=="git" -> git restore
+            * mode_hint=="non-git" -> snapshot restore via 02-03 Snapshot
+
+        MUST NOT mutate finding. Outcome only; caller drives transitions.
+        """
+        ...
+
+
+class StubAutoFixer(AutoFixer):
+    """Returns configured FixOutcomes for tests.
+
+    Config format (JSON):
+      {
+        "default": "SUCCESS",
+        "outcomes": {"fp-xxx": "PARSE_FAIL", "fp-yyy": "SUCCESS", ...}
+      }
+    """
+
+    def __init__(self, fixture_path: Optional[Path] = None):
+        self._outcomes: dict[str, FixOutcome] = {}
+        self._default = FixOutcome.SUCCESS
+        if fixture_path:
+            data = json.loads(fixture_path.read_text())
+            self._default = FixOutcome(data.get("default", "SUCCESS"))
+            self._outcomes = {
+                fp: FixOutcome(o)
+                for fp, o in data.get("outcomes", {}).items()
+            }
+
+    def fix(self, finding: StateFinding, mode_hint: str) -> FixOutcome:
+        """Return configured outcome for this finding's fingerprint."""
+        return self._outcomes.get(finding.fingerprint, self._default)

code_forge/baseline.py

@@ -0,0 +1,216 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""BaselineSpec discriminated union + resolver.
+
+Owned by 02-03. 02-05 CLI parser emits BaselineSpec from string args;
+this module dispatches to the right resolution path.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+from .errors import BaselineResolutionError
+from .git import (
+    INDEX,
+    WORKING,
+    cached_diff,
+    git_diff,
+    is_git_repo,
+    is_pseudo_ref,
+    resolve_git_ref,
+    working_tree_diff,
+)
+from .snapshot import load_snapshot
+
+
+@dataclass(frozen=True)
+class GitRefBaseline:
+    """Baseline = git ref (HEAD, branch, commit sha, WORKING, INDEX)."""
+
+    ref: str
+
+
+@dataclass(frozen=True)
+class SnapshotBaseline:
+    """Baseline = stored .code-forge/snapshots/<source-hash>.json."""
+
+    path: Path
+
+
+@dataclass(frozen=True)
+class EmptyBaseline:
+    """Baseline = nothing. All current source content is new."""
+
+    pass
+
+
+BaselineSpec = Union[GitRefBaseline, SnapshotBaseline, EmptyBaseline]
+
+
+@dataclass(frozen=True)
+class ResolvedReview:
+    """Concrete review subject + baseline content after resolution.
+
+    Consumed by state machine (02-02) and source_hash (STATE-07).
+    """
+
+    source_files: list[Path]
+    baseline_content: Optional[dict]
+    git_diff: Optional[str]
+    mode_hint: str  # "git" | "non-git"
+
+
+def resolve_baseline(
+    baseline_spec: BaselineSpec,
+    head_spec: Optional["GitRefBaseline"],
+    paths: list[Path],
+    cwd: Path,
+) -> ResolvedReview:
+    """Resolve (baseline, head, paths) to concrete review subject.
+
+    Raises:
+        BaselineResolutionError: invalid combination.
+    """
+    if isinstance(baseline_spec, GitRefBaseline):
+        return _resolve_git(baseline_spec, head_spec, paths, cwd)
+    if isinstance(baseline_spec, SnapshotBaseline):
+        if head_spec is not None:
+            raise BaselineResolutionError(
+                "SnapshotBaseline does not accept head_spec "
+                "(got: %r); snapshot is its own implicit head"
+                % (head_spec,)
+            )
+        return _resolve_snapshot(baseline_spec, paths, cwd)
+    if isinstance(baseline_spec, EmptyBaseline):
+        if head_spec is not None and not is_git_repo(cwd):
+            raise BaselineResolutionError(
+                "EmptyBaseline + head_spec is only valid in a git repo; "
+                "cwd=%s" % cwd
+            )
+        return _resolve_empty(head_spec, paths, cwd)
+    raise BaselineResolutionError(
+        "unknown baseline spec type: %s" % type(baseline_spec)
+    )
+
+
+def _resolve_git(
+    baseline_spec: GitRefBaseline,
+    head_spec: Optional[GitRefBaseline],
+    paths: list[Path],
+    cwd: Path,
+) -> ResolvedReview:
+    """B3 resolution -- git mode.
+
+    1. Reject if cwd is not in a git repo.
+    2. Reject pseudo-ref as baseline (WORKING/INDEX are head-only).
+    3. Validate baseline ref via resolve_git_ref.
+    4. Default head = GitRefBaseline(WORKING) if head_spec is None.
+    5. Dispatch by head ref kind.
+    6. Return ResolvedReview with diff, mode_hint="git".
+    """
+    if not is_git_repo(cwd):
+        raise BaselineResolutionError(
+            "GitRefBaseline used outside git repo (cwd=%s)" % cwd
+        )
+    if is_pseudo_ref(baseline_spec.ref):
+        raise BaselineResolutionError(
+            "baseline cannot be a pseudo-ref (%s); "
+            "pseudo-refs are head-only" % baseline_spec.ref
+        )
+    resolve_git_ref(baseline_spec.ref, cwd)  # raises if ref unknown
+
+    head = head_spec if head_spec is not None else GitRefBaseline(WORKING)
+    if head.ref == WORKING:
+        diff = working_tree_diff(baseline_spec.ref, paths, cwd)
+    elif head.ref == INDEX:
+        diff = cached_diff(baseline_spec.ref, paths, cwd)
+    else:
+        resolve_git_ref(head.ref, cwd)
+        diff = git_diff(baseline_spec.ref, head.ref, paths, cwd)
+
+    return ResolvedReview(
+        source_files=paths,
+        baseline_content=None,
+        git_diff=diff,
+        mode_hint="git",
+    )
+
+
+def _resolve_snapshot(
+    baseline_spec: SnapshotBaseline,
+    paths: list[Path],
+    cwd: Path,
+) -> ResolvedReview:
+    """B3 resolution -- stored snapshot.
+
+    1. load_snapshot(path); returns None on missing file (BASELINE-03).
+    2. If None: fall back to EmptyBaseline resolution silently.
+    3. Else: pack snapshot dict into baseline_content.
+    """
+    snap = load_snapshot(baseline_spec.path)
+    if snap is None:
+        return _resolve_empty(None, paths, cwd)
+    return ResolvedReview(
+        source_files=paths,
+        baseline_content={"snapshot": asdict(snap)},
+        git_diff=None,
+        mode_hint="non-git",
+    )
+
+
+def _resolve_empty(
+    head_spec: Optional[GitRefBaseline],
+    paths: list[Path],
+    cwd: Path,
+) -> ResolvedReview:
+    """B3 resolution -- empty baseline (all source is new).
+
+    1. mode_hint = "git" if cwd is in a git repo else "non-git".
+    2. If git repo AND head_spec provided: diff from empty tree to head
+       (git empty tree sha 4b825dc642cb6eb9a060e54bf8d69288fbee4904).
+    3. Otherwise: no diff.
+    """
+    if is_git_repo(cwd) and head_spec is not None:
+        # Git's universal empty-tree sha (constant, not computed)
+        empty_tree_sha = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
+        if head_spec.ref == WORKING:
+            diff = working_tree_diff(empty_tree_sha, paths, cwd)
+        elif head_spec.ref == INDEX:
+            diff = cached_diff(empty_tree_sha, paths, cwd)
+        else:
+            resolve_git_ref(head_spec.ref, cwd)
+            diff = git_diff(empty_tree_sha, head_spec.ref, paths, cwd)
+        return ResolvedReview(
+            source_files=paths,
+            baseline_content=None,
+            git_diff=diff,
+            mode_hint="git",
+        )
+    mode = "git" if is_git_repo(cwd) else "non-git"
+    return ResolvedReview(
+        source_files=paths,
+        baseline_content=None,
+        git_diff=None,
+        mode_hint=mode,
+    )
+
+
+def serialize_baseline_spec(spec: BaselineSpec) -> str:
+    """OQ1 fix: produce single-line repr for state.json.
+
+    Formats:
+      GitRefBaseline(ref="HEAD")        -> "git:HEAD"
+      SnapshotBaseline(path=...)        -> "snapshot:<posix-path>"
+      EmptyBaseline()                   -> "empty"
+    """
+    if isinstance(spec, GitRefBaseline):
+        return "git:%s" % spec.ref
+    if isinstance(spec, SnapshotBaseline):
+        return "snapshot:%s" % spec.path.as_posix()
+    if isinstance(spec, EmptyBaseline):
+        return "empty"
+    raise BaselineResolutionError(
+        "cannot serialize unknown spec type: %s" % type(spec)
+    )