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

code_forge/git.py

@@ -0,0 +1,351 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Git subprocess wrapper with diff-spec validation.
+
+This module is THE single owner of git diff subprocess calls in the
+codebase. All other modules call these functions -- they do not call
+git directly. Addresses Consensus #1 (git diff execution unowned).
+
+02-03 additions: repo detection, ref validation, pseudo-ref resolution.
+Existing Phase 1 API unchanged. New surface (B1 + H2 fixes):
+  - is_git_repo(cwd)             -> bool                   (B1)
+  - resolve_git_ref(ref, cwd)    -> str (resolved sha)     (B1)
+  - is_pseudo_ref(name)          -> bool
+  - working_tree_diff(...)       -> str                    (H2)
+  - cached_diff(...)             -> str
+  - git_diff(baseline, head, ...) -> str
+"""
+
+import re
+import shutil
+import subprocess
+import warnings
+from pathlib import Path
+
+# Safe known flags that are allowed despite starting with --
+_SAFE_FLAGS = frozenset({"--staged", "--cached"})
+
+# Allowlist regex for diff-spec values.
+# Permits: branch names (feature/foo), tags (v1.2.3), commit hashes
+# (abc123), HEAD references (HEAD, HEAD~1, HEAD^), remote refs
+# (origin/main), commit ranges (abc..def, HEAD~3..HEAD), and the @
+# character (for refs like HEAD@).
+#
+# Round 7 R7-L5 (DeepSeek): ^ and - placement inside the character
+# class is fragile. Both are now explicitly escaped (\^, \-) so
+# reordering the class will not silently change semantics.
+#
+# Curly braces ({}) are NOT permitted -- users should use explicit
+# ref names instead of @{u} / @{upstream} syntax.
+_DIFF_SPEC_RE = re.compile(
+    r"^[A-Za-z0-9_./~@\^\-]+(?:\.\.[A-Za-z0-9_./~@\^\-]+)?$"
+)
+
+
+def validate_diff_spec(diff_spec: str) -> str:
+    """Validate diff_spec against flag injection.
+
+    Returns sanitized spec unchanged.
+
+    Raises:
+        ValueError: on empty string, unsafe flags, or characters
+            outside the allowlist.
+    """
+    if not diff_spec:
+        raise ValueError("diff_spec must not be empty")
+
+    # Allow safe known flags
+    if diff_spec in _SAFE_FLAGS:
+        return diff_spec
+
+    # Reject other leading dashes (flag injection)
+    if diff_spec.startswith("-"):
+        raise ValueError(
+            "Invalid diff_spec: '%s' looks like a flag" % diff_spec
+        )
+
+    # Allowlist check -- reject everything not matching
+    if not _DIFF_SPEC_RE.match(diff_spec):
+        raise ValueError(
+            "Invalid diff_spec: '%s' contains disallowed characters"
+            % diff_spec
+        )
+
+    return diff_spec
+
+
+def run_git_diff(
+    diff_spec: str = "HEAD",
+    extra_args: list[str] | None = None,
+) -> str:
+    """Execute git diff and return raw diff text.
+
+    Validates diff_spec before use. Default: git diff -U0 HEAD
+    (working tree vs HEAD).
+
+    Supports: HEAD, --staged, commit..commit, commit ranges.
+
+    Note (Round 3 item 12): extra_args exists for future extensibility
+    (e.g. --name-only). Currently unused by any caller in Phase 1.
+
+    Git diff exit code semantics (CRITICAL):
+        Exit 0: no differences (return stdout, typically empty)
+        Exit 1: differences found (NORMAL -- return stdout with diff)
+        Exit 128+: fatal git error (raise RuntimeError with stderr)
+
+    This addresses Mimo F-03: git diff returns 1 when differences
+    exist, NOT an error condition.
+
+    Raises:
+        RuntimeError: if git is not found or git returns exit 128+
+        ValueError: if diff_spec is invalid (from validate_diff_spec)
+    """
+    diff_spec = validate_diff_spec(diff_spec)
+
+    if shutil.which("git") is None:
+        raise RuntimeError("git not found")
+
+    cmd = ["git", "diff", "-U0", diff_spec] + (extra_args or [])
+
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    if result.returncode not in (0, 1):
+        raise RuntimeError(
+            result.stderr or f"git diff failed (exit {result.returncode})"
+        )
+
+    return result.stdout
+
+
+# --- 02-03 additions: pseudo-refs, repo detection, ref validation ---
+
+WORKING = "WORKING"
+INDEX = "INDEX"
+PSEUDO_REFS = {WORKING, INDEX}
+
+
+def is_pseudo_ref(name: str) -> bool:
+    """Check whether name is a forge pseudo-ref (WORKING or INDEX)."""
+    return name in PSEUDO_REFS
+
+
+def is_git_repo(cwd: Path) -> bool:
+    """B1 fix: check whether cwd is inside a git repo.
+
+    Uses `git rev-parse --git-dir` (non-zero outside a repo).
+    """
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, OSError):
+        return False
+
+
+def resolve_git_ref(ref: str, cwd: Path) -> str:
+    """B1 fix: validate that a git ref exists; return its resolved sha.
+
+    Raises:
+        BaselineResolutionError: ref does not exist.
+    """
+    from .errors import BaselineResolutionError
+
+    result = subprocess.run(
+        ["git", "rev-parse", "--verify", ref + "^{commit}"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise BaselineResolutionError(
+            "git ref %r does not resolve in %s: %s"
+            % (ref, cwd, result.stderr.strip())
+        )
+    return result.stdout.strip()
+
+
+def _is_likely_binary(path: Path) -> bool:
+    """H2 fix: heuristic binary detection via null-byte in first 8KB.
+
+    Matches git's own diff-detection behavior (loosely). Used to skip
+    binary untracked files in working_tree_diff.
+    """
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(8192)
+        return b"\0" in chunk
+    except OSError:
+        return False
+
+
+def git_diff(
+    baseline_ref: str,
+    head_ref: str,
+    paths: list[Path],
+    repo_root: Path,
+) -> str:
+    """Standard `git diff <baseline_ref> <head_ref> -- <paths>`.
+
+    Exit code semantics (R3-1 fix; matches Phase 1 run_git_diff per
+    Mimo F-03 in src/forge/git.py:80-86):
+      0 = no differences (return empty stdout)
+      1 = differences found (NORMAL -- return stdout with diff)
+      2+ = real git error (raise BaselineResolutionError)
+    """
+    from .errors import BaselineResolutionError
+
+    cmd = (
+        ["git", "diff", baseline_ref, head_ref, "--"]
+        + [str(p) for p in paths]
+    )
+    result = subprocess.run(
+        cmd, cwd=repo_root, capture_output=True, text=True, check=False
+    )
+    if result.returncode not in (0, 1):
+        raise BaselineResolutionError(
+            "git diff %s..%s failed (exit %d): %s"
+            % (
+                baseline_ref,
+                head_ref,
+                result.returncode,
+                result.stderr.strip(),
+            )
+        )
+    return result.stdout
+
+
+def cached_diff(
+    baseline_ref: str,
+    paths: list[Path],
+    repo_root: Path,
+) -> str:
+    """`git diff --cached <baseline_ref> -- <paths>` (staged vs baseline).
+
+    Exit code semantics (R3-1 fix): accept 0/1, raise on 2+.
+    """
+    from .errors import BaselineResolutionError
+
+    cmd = (
+        ["git", "diff", "--cached", baseline_ref, "--"]
+        + [str(p) for p in paths]
+    )
+    result = subprocess.run(
+        cmd, cwd=repo_root, capture_output=True, text=True, check=False
+    )
+    if result.returncode not in (0, 1):
+        raise BaselineResolutionError(
+            "git diff --cached %s failed (exit %d): %s"
+            % (baseline_ref, result.returncode, result.stderr.strip())
+        )
+    return result.stdout
+
+
+def working_tree_diff(
+    baseline_ref: str,
+    paths: list[Path],
+    repo_root: Path,
+) -> str:
+    """Diff baseline..working_tree, including non-binary untracked files.
+
+    Tracked diff: `git diff <baseline_ref> -- <paths>`.
+    Untracked: enumerate via `git ls-files --others --exclude-standard`,
+    synthesize as full-add via `git diff --no-index /dev/null <file>`.
+    H2 fix: binary untracked files are SKIPPED with warnings.warn.
+
+    Exit code handling (R2-1 + R3-1): all git diff calls accept exit 0/1,
+    raise BaselineResolutionError on exit 2+. Follows Phase 1 run_git_diff
+    convention (Mimo F-03).
+    """
+    from .errors import BaselineResolutionError
+
+    # Tracked diff (R3-1: must NOT use check=True)
+    tracked_cmd = (
+        ["git", "diff", baseline_ref, "--"]
+        + [str(p) for p in paths]
+    )
+    tracked_result = subprocess.run(
+        tracked_cmd,
+        cwd=repo_root,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if tracked_result.returncode not in (0, 1):
+        raise BaselineResolutionError(
+            "git diff %s (tracked, working_tree_diff) failed (exit %d): %s"
+            % (
+                baseline_ref,
+                tracked_result.returncode,
+                tracked_result.stderr.strip(),
+            )
+        )
+    tracked = tracked_result.stdout
+
+    # Untracked files (ls-files has no exit-1-normal semantics)
+    ls_cmd = (
+        ["git", "ls-files", "--others", "--exclude-standard", "--"]
+        + [str(p) for p in paths]
+    )
+    untracked_paths = [
+        line
+        for line in subprocess.run(
+            ls_cmd,
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        ).stdout.splitlines()
+        if line.strip()
+    ]
+
+    untracked_diffs: list[str] = []
+    skipped_binary: list[str] = []
+    for rel_path in sorted(untracked_paths):
+        full = repo_root / rel_path
+        if _is_likely_binary(full):
+            skipped_binary.append(rel_path)
+            continue
+        # R2-1: git diff --no-index exit codes:
+        #   0 = files identical (impossible vs /dev/null with content)
+        #   1 = files differ (THE expected case)
+        #   2+ = real error
+        cmd = ["git", "diff", "--no-index", "/dev/null", str(full)]
+        result = subprocess.run(
+            cmd,
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode not in (0, 1):
+            raise BaselineResolutionError(
+                "git diff --no-index failed for untracked file %s "
+                "(exit %d): %s"
+                % (rel_path, result.returncode, result.stderr.strip())
+            )
+        untracked_diffs.append(result.stdout)
+
+    if skipped_binary:
+        warnings.warn(
+            "forge: skipped %d binary untracked file(s) from "
+            "working-tree diff: %s%s"
+            % (
+                len(skipped_binary),
+                skipped_binary[:3],
+                "..." if len(skipped_binary) > 3 else "",
+            ),
+            stacklevel=2,
+        )
+
+    return tracked + "\n".join(untracked_diffs)

code_forge/hold.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""HOLD UX + ESCALATED-frozen predicate.
+
+run_hold_ui prompts human for UNCERTAIN dispositions. check_escalated_frozen
+implements DISPO-05(c) deferred from 02-02.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from .disposition import Disposition, MAX_FIX_ATTEMPTS_PER_FINGERPRINT
+from .state import State, StateFinding, save_state
+
+
+VALID_INPUTS = {"c": Disposition.CONFIRMED, "d": Disposition.DISMISSED}
+QUIT_INPUTS = {"q"}
+
+
+class HoldAborted(Exception):
+    """Raised when human aborts HOLD UX (Ctrl+D / EOF / "q" input).
+
+    Message is generic ("HOLD UX aborted by user"), not stdin-specific.
+    """
+
+
+def run_hold_ui(
+    state: State,
+    state_path: Path,
+    input_fn: Callable[[str], str] = input,
+    output_fn: Callable[[str], None] = print,
+) -> None:
+    """Prompt human for each UNCERTAIN finding.
+
+    For each finding with disposition == UNCERTAIN:
+      - Print summary (id, file:line, description).
+      - Prompt: "[c]onfirm / [d]ismiss / [s]kip / [q]uit: "
+      - "c" -> set disposition CONFIRMED
+      - "d" -> set disposition DISMISSED
+      - "s" -> leave UNCERTAIN, move on
+      - "q" -> raise HoldAborted
+      - invalid -> reprompt
+      - EOF -> raise HoldAborted
+
+    After loop: clear hold_reason, rebuild dispositions cache, persist.
+
+    Idempotent: if zero UNCERTAIN findings, returns immediately with
+    no I/O (caller may invoke unconditionally after PENDING return).
+    """
+    uncertain = [
+        f for f in state.findings if f.disposition == Disposition.UNCERTAIN
+    ]
+    if not uncertain:
+        state.hold_reason = None
+        save_state(state, state_path)
+        return
+
+    output_fn(
+        "HOLD: %d UNCERTAIN finding(s) need human disposition."
+        % len(uncertain)
+    )
+    for finding in uncertain:
+        _prompt_one(finding, input_fn, output_fn)
+
+    state.hold_reason = None
+    state.dispositions = {f.id: f.disposition for f in state.findings}
+    save_state(state, state_path)
+
+
+def _prompt_one(
+    finding: StateFinding,
+    input_fn: Callable[[str], str],
+    output_fn: Callable[[str], None],
+) -> None:
+    """Inner per-finding prompt loop (reprompts on invalid input)."""
+    output_fn(
+        "  [%s] %s:%d-%d  %s"
+        % (
+            finding.id,
+            finding.file,
+            finding.line_range[0],
+            finding.line_range[1],
+            finding.description,
+        )
+    )
+    while True:
+        try:
+            choice = input_fn(
+                "    [c]onfirm / [d]ismiss / [s]kip / [q]uit: "
+            ).strip().lower()
+        except EOFError:
+            raise HoldAborted("HOLD UX aborted by user")
+        if choice in QUIT_INPUTS:
+            raise HoldAborted("HOLD UX aborted by user")
+        if choice == "s":
+            return
+        if choice in VALID_INPUTS:
+            finding.disposition = VALID_INPUTS[choice]
+            return
+        output_fn("    (invalid input %r; expected c/d/s/q)" % choice)
+
+
+def check_escalated_frozen(state: State) -> bool:
+    """DISPO-05(c) predicate: re-CONFIRM of promoted finding -> ESCALATED.
+
+    Returns True iff ALL of:
+      - state.hold_reason is None (not currently in HOLD entry)
+      - state.promoted_fingerprints is non-empty
+      - at least one finding has: disposition == CONFIRMED AND
+        fingerprint in promoted_fingerprints AND
+        fix_attempts[fp] >= MAX_FIX_ATTEMPTS_PER_FINGERPRINT
+    """
+    if state.hold_reason is not None:
+        return False
+    if not state.promoted_fingerprints:
+        return False
+    for finding in state.findings:
+        if (
+            finding.disposition == Disposition.CONFIRMED
+            and finding.fingerprint in state.promoted_fingerprints
+            and state.fix_attempts.get(finding.fingerprint, 0)
+            >= MAX_FIX_ATTEMPTS_PER_FINGERPRINT
+        ):
+            return True
+    return False