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

code_forge/delta.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Delta computation -- filter findings to changed lines only.
+
+This is the core of baseline mode (LAYER0-02).  The design doc says
+"Layer 0 flags only NEW violations introduced by the diff."  The
+delta filter determines "NEW" by checking if the finding's line
+range intersects lines that were added or modified in the diff.
+
+This module is a pure function with no I/O -- same inputs always
+produce same outputs, satisfying GATE-02 determinism.
+"""
+
+from code_forge.parsers.base import Finding, ToolError
+
+
+def filter_delta(
+    findings: list[Finding | ToolError],
+    changed_lines: dict[str, set[int]],
+) -> tuple[list[Finding | ToolError], list[Finding | ToolError]]:
+    """Filter findings to only those on changed lines.
+
+    Returns a 2-tuple:
+        delta_findings: findings whose line range intersects changed
+            lines, plus all ToolError items (not filtered by line).
+        all_findings: a copy of the input list (preserved for the
+            reporter to show "N pre-existing violation(s) in
+            unchanged code").
+
+    ToolError items are always included in delta_findings because
+    tool errors represent tool-level failures that must be reported
+    regardless of which lines changed.
+
+    For each Finding, a multi-line finding (line != end_line) is
+    kept if ANY line in range(finding.line, finding.end_line + 1)
+    intersects the changed lines set (RESEARCH.md Pitfall 2).
+
+    Args:
+        findings: list of Finding and/or ToolError items
+        changed_lines: {file_path: set_of_changed_line_numbers}
+            from extract_changed_lines()
+
+    Returns:
+        (delta_findings, all_findings)
+    """
+    all_findings = list(findings)
+    delta_findings: list[Finding | ToolError] = []
+
+    for item in findings:
+        # ToolError items always pass through
+        if isinstance(item, ToolError):
+            delta_findings.append(item)
+            continue
+
+        # Finding: check if file is in changed_lines
+        file_lines = changed_lines.get(item.file)
+        if file_lines is None:
+            continue
+
+        # Check if any line in the finding's range intersects
+        finding_range = range(item.line, item.end_line + 1)
+        if any(ln in file_lines for ln in finding_range):
+            delta_findings.append(item)
+
+    return (delta_findings, all_findings)

code_forge/diagnose.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""STATE-05 A/B/C/D non-convergence classifier.
+
+Pure function over round_history + infra_errors. Called when state machine
+exhausts MAX_TOTAL_ROUNDS without reaching fixpoint or HOLD.
+
+Categories:
+  A = FIXED -> CONFIRMED oscillation
+      (same fingerprint toggles disposition across consecutive rounds)
+  B = net CONFIRMED count not decreasing across rounds
+      (R1 H4 fix: expanded to cover both genuinely new fingerprints each
+      round AND stuck CONFIRMED count that auto-fix never reduces.
+      Threshold: net CONFIRMED non-decreasing over last 3 rounds.)
+  C = UNCERTAIN accumulation
+      (falsifier indecisive; UNCERTAIN count grows monotonically >= 3 rounds)
+  D = infrastructure failure
+      (ANY infra_errors entry: binary trigger per R3 MED2)
+
+Tie-breaker priority: D > A > B > C
+"""
+from typing import Literal
+
+
+def diagnose_non_convergence(
+    round_history: list[dict],
+    infra_errors: list[str],
+) -> Literal["A", "B", "C", "D"]:
+    """Classify why state machine failed to converge.
+
+    round_history: list of per-round dicts with keys:
+      - round: int
+      - l0_fingerprints: list[str]
+      - l1_fingerprints: list[str]
+      - dispositions: dict[str, str]  (fingerprint -> Disposition value)
+      - fixed_fingerprints: list[str] (this round)
+
+    infra_errors: list of error message strings.
+
+    Returns: "A" | "B" | "C" | "D"
+    """
+    # R3 MED2: ANY infra_errors entry -> D (binary trigger).
+    if infra_errors:
+        return "D"
+    if _has_fixed_to_confirmed_toggle(round_history):
+        return "A"
+    if _has_monotonic_new_confirmed(round_history):
+        return "B"
+    if _has_uncertain_growth(round_history):
+        return "C"
+    # Default fallback: oscillation-most-likely if no other signal.
+    return "A"
+
+
+def _has_fixed_to_confirmed_toggle(history: list[dict]) -> bool:
+    """Category A: same fingerprint FIXED in round N, CONFIRMED in N+1.
+
+    Detects fix-loop instability where auto-fix appears to succeed but
+    finding re-detects in next round.
+    """
+    for i in range(len(history) - 1):
+        current_disps = history[i].get("dispositions", {})
+        next_disps = history[i + 1].get("dispositions", {})
+        for fp, disp in current_disps.items():
+            if disp == "FIXED" and next_disps.get(fp) == "CONFIRMED":
+                return True
+    return False
+
+
+def _has_monotonic_new_confirmed(history: list[dict]) -> bool:
+    """Category B (R1 H4 expanded): net CONFIRMED count not decreasing.
+
+    Returns True iff over the last 3 rounds, the count of CONFIRMED
+    fingerprints did NOT strictly decrease across any consecutive pair.
+    Requires >= 3 rounds of history; returns False otherwise.
+    """
+    if len(history) < 3:
+        return False
+    window = history[-3:]
+    counts = []
+    for entry in window:
+        disps = entry.get("dispositions", {})
+        n = sum(1 for v in disps.values() if v == "CONFIRMED")
+        counts.append(n)
+    # Must have at least one CONFIRMED in the window to qualify as B
+    if max(counts) == 0:
+        return False
+    # Non-decreasing: every pair c[i] <= c[i+1]
+    for i in range(len(counts) - 1):
+        if counts[i] > counts[i + 1]:
+            return False
+    return True
+
+
+def _has_uncertain_growth(history: list[dict]) -> bool:
+    """Category C: UNCERTAIN count grows monotonically over >= 3 rounds."""
+    if len(history) < 3:
+        return False
+    window = history[-3:]
+    counts = []
+    for entry in window:
+        disps = entry.get("dispositions", {})
+        n = sum(1 for v in disps.values() if v == "UNCERTAIN")
+        counts.append(n)
+    # Strictly increasing: every pair c[i] < c[i+1]
+    for i in range(len(counts) - 1):
+        if counts[i] >= counts[i + 1]:
+            return False
+    return True

code_forge/diff.py

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Git diff parser with changed-line extraction.
+
+Uses unidiff library (RESEARCH.md Pattern 3) to parse unified diff
+text and extract changed line numbers per file.
+
+Line-number drift between tool output and diff is N/A: both reference
+the same working tree file state. Tools run on the actual files
+(post-patch), and git diff reports target-side line numbers for those
+same files. Addresses LAYER0-03 and review Consensus #2.
+"""
+
+import logging
+
+import unidiff
+
+logger = logging.getLogger(__name__)
+
+
+def extract_changed_lines(diff_text: str) -> dict[str, set[int]]:
+    """Parse unified diff, return {file: set_of_changed_line_numbers}.
+
+    Only added/modified lines. Deleted files excluded.
+
+    Line-number drift is N/A because both tools and diff reference
+    the working tree file state. Tools run on the actual files
+    (post-patch), and git diff -U0 HEAD reports target-side line
+    numbers for those same files. Addresses LAYER0-03 and review
+    Consensus #2.
+
+    Args:
+        diff_text: raw unified diff text (from git diff output)
+
+    Returns:
+        Dict mapping file paths to sets of added line numbers.
+        Empty dict for empty or unparseable diff.
+    """
+    if not diff_text or not diff_text.strip():
+        return {}
+
+    try:
+        patchset = unidiff.PatchSet(diff_text)
+    except unidiff.errors.UnidiffParseError:
+        logger.warning("Failed to parse diff text, returning empty dict")
+        return {}
+
+    result = {}
+    for patched_file in patchset:
+        # Skip deleted files
+        if patched_file.is_removed_file:
+            continue
+
+        # Use target path (handles renames correctly)
+        filepath = patched_file.path
+
+        changed_lines = set()
+        for hunk in patched_file:
+            for line in hunk:
+                if line.is_added and line.target_line_no is not None:
+                    changed_lines.add(line.target_line_no)
+
+        if changed_lines:
+            result[filepath] = changed_lines
+
+    return result
+
+
+def get_changed_files(diff_text: str) -> list[str]:
+    """Return sorted list of files with additions/modifications.
+
+    Uses extract_changed_lines internally. Only files with at least
+    one added line are included.
+
+    Args:
+        diff_text: raw unified diff text
+
+    Returns:
+        Sorted list of file paths with additions.
+    """
+    changed = extract_changed_lines(diff_text)
+    return sorted(changed.keys())

code_forge/disposition.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Disposition protocol for forge state machine.
+
+Owned by Phase 2 sub-plan 02-01. All other sub-plans + Phase 4 must conform.
+DO NOT add fields without bumping DISPOSITION_PROTOCOL_VERSION.
+"""
+
+from enum import Enum
+from typing import Final
+
+DISPOSITION_PROTOCOL_VERSION: Final[int] = 1
+MAX_FIX_ATTEMPTS_PER_FINGERPRINT: Final[int] = 3
+FEEDBACK_SCHEMA_VERSION: Final[int] = 1
+
+
+class Disposition(str, Enum):
+    """Finding disposition states.
+
+    State transitions (enforced by state machine, not by enum):
+    - (new) -> CONFIRMED | DISMISSED | UNCERTAIN  (set by falsify())
+    - CONFIRMED -> FIXED                          (after successful auto-fix)
+    - CONFIRMED -> UNCERTAIN                      (DISPO-05 promotion)
+    - FIXED -> (remove from active)               (next-round gone)
+    - FIXED -> CONFIRMED                          (next-round persists)
+    - UNCERTAIN -> CONFIRMED                      (human re-CONFIRM in HOLD)
+    - UNCERTAIN -> DISMISSED                      (human dismiss in HOLD)
+    """
+    CONFIRMED = "CONFIRMED"
+    DISMISSED = "DISMISSED"
+    UNCERTAIN = "UNCERTAIN"
+    FIXED = "FIXED"