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

code_forge/runner.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""Tool execution engine with subprocess orchestration.
+
+Resolves tool binaries (PATH and relative paths), captures tool
+versions for GATE-02 reproducibility, runs tools with timeout, and
+handles missing/failed tools gracefully.
+
+Security: subprocess.run is ALWAYS called with a list argument,
+never a string.  shell=True is never used.  See T-01-07.
+
+Phase 1 scope note (Kimi H2): checkpatch.pl requires stdin input,
+not file arguments.  The current runner only supports file-argument
+tools.  stdin-input mode is deferred to Phase 2.
+
+Phase 1 scope note (DeepSeek H-2): cargo_root detection (walking
+parent directories to find Cargo.toml) is deferred to Phase 2.
+When working_dir="cargo_root", the runner skips appending files to
+the command but does NOT change the working directory.
+"""
+
+import logging
+import os
+import shutil
+import subprocess
+
+from code_forge.registry import ToolConfig, match_tools
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_command(command: str) -> str | None:
+    """Resolve a tool command to an executable path.
+
+    First tries shutil.which (PATH-based resolution).  If that fails
+    and the command contains os.sep (e.g. "scripts/checkpatch.pl"),
+    checks whether the path exists and is executable.
+
+    This addresses DeepSeek's finding: checkpatch.pl is a relative
+    path, not on PATH.  shutil.which alone misses it.
+
+    Args:
+        command: tool command string from ToolConfig.command
+
+    Returns:
+        Resolved path string, or None if not found.
+    """
+    resolved = shutil.which(command)
+    if resolved is not None:
+        return resolved
+
+    # Try relative path resolution (e.g. scripts/checkpatch.pl)
+    if os.sep in command:
+        if os.path.isfile(command) and os.access(command, os.X_OK):
+            return command
+
+    return None
+
+
+def capture_tool_version(command: str) -> str:
+    """Capture a tool's version string for GATE-02 reproducibility.
+
+    Runs "<resolved_cmd> --version" and returns the first line of
+    stdout.  Called once per tool at pipeline startup, NOT per file.
+
+    Args:
+        command: tool command string (will be resolved via PATH)
+
+    Returns:
+        Version string (first line of stdout), "not_installed" if
+        the command cannot be found, or "unknown" on any error.
+    """
+    resolved = _resolve_command(command)
+    if resolved is None:
+        return "not_installed"
+
+    try:
+        result = subprocess.run(
+            [resolved, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+        )
+        first_line = result.stdout.strip().split("\n")[0]
+        return first_line if first_line else "unknown"
+    except (subprocess.TimeoutExpired, OSError):
+        return "unknown"
+
+
+def run_tool(
+    tool_config: ToolConfig,
+    files: list[str],
+) -> tuple[str, int, str] | None:
+    """Execute a single tool via subprocess.
+
+    Returns (stdout, returncode, stderr) 3-tuple on success, or
+    None if the tool is missing (optional), timed out, or hit an
+    OS error.
+
+    The stderr field is captured and propagated so that downstream
+    code can populate ToolError.stderr with the tool's actual error
+    output (Round 5 Kimi R5-M3).
+
+    Args:
+        tool_config: tool configuration from registry
+        files: list of file paths to lint
+
+    Returns:
+        (stdout, returncode, stderr) or None
+
+    Raises:
+        RuntimeError: if tool is required but not found
+    """
+    resolved = _resolve_command(tool_config.command)
+
+    if resolved is None:
+        if tool_config.required:
+            raise RuntimeError(
+                "Required tool not found: %s" % tool_config.command
+            )
+        logger.info(
+            "Optional tool '%s' not found, skipping", tool_config.name
+        )
+        return None
+
+    # Build command: [resolved_cmd] + args + files
+    # Exception: cargo_root mode skips file args (clippy operates on crate)
+    cmd = [resolved] + tool_config.args
+    if tool_config.working_dir != "cargo_root":
+        cmd = cmd + files
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=tool_config.timeout,
+            check=False,
+        )
+        return (result.stdout, result.returncode, result.stderr)
+    except subprocess.TimeoutExpired:
+        logger.warning(
+            "Tool '%s' timed out after %ds",
+            tool_config.name,
+            tool_config.timeout,
+        )
+        return None
+    except OSError as exc:
+        logger.warning(
+            "Tool '%s' failed with OS error: %s",
+            tool_config.name,
+            exc,
+        )
+        return None
+
+
+def run_tools(
+    registry: dict[str, ToolConfig],
+    files: list[str],
+) -> tuple[dict[str, tuple[str, int, str]], dict[str, str], list[str]]:
+    """Execute all matching tools from the registry.
+
+    Returns a 3-tuple:
+        tool_results: {tool_name: (stdout, returncode, stderr)}
+        tool_versions: {tool_name: version_string}
+        tools_skipped: [tool_name, ...]
+
+    Iterates sorted(registry.keys()) for GATE-02 determinism
+    (Round 3 item 11).  Calls match_tools once before the per-tool
+    loop (Mimo F-04).
+
+    Args:
+        registry: {name: ToolConfig} from load_registry
+        files: list of changed file paths
+
+    Returns:
+        (tool_results, tool_versions, tools_skipped)
+    """
+    tool_results: dict[str, tuple[str, int, str]] = {}
+    tool_versions: dict[str, str] = {}
+    tools_skipped: list[str] = []
+
+    # Call match_tools once (Mimo F-04)
+    matched = match_tools(registry, files)
+
+    for tool_name in sorted(registry.keys()):
+        tool_config = registry[tool_name]
+
+        # Capture version (Consensus #3)
+        tool_versions[tool_name] = capture_tool_version(tool_config.command)
+
+        # Check for matching files
+        matching_files = matched.get(tool_name, [])
+        if not matching_files:
+            tools_skipped.append(tool_name)
+            continue
+
+        result = run_tool(tool_config, matching_files)
+        if result is None:
+            tools_skipped.append(tool_name)
+        else:
+            tool_results[tool_name] = result
+
+    return (tool_results, tool_versions, tools_skipped)

code_forge/sarif.py

@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2026, Minxi Hou <houminxi@gmail.com>
+"""LAYER0-07: SARIF 2.1.0 emission for CI mode.
+
+Pure data transformation: State + tool_versions -> SARIF log dict.
+Caller (cli.py CI path) handles I/O.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .disposition import Disposition
+from .state import State, StateFinding, Verdict
+
+
+SARIF_VERSION = "2.1.0"
+SARIF_SCHEMA_URI = "https://json.schemastore.org/sarif-2.1.0.json"
+
+
+# Disposition -> SARIF level. DISMISSED + FIXED use "note" (lowest severity)
+# because they are emitted-but-suppressed per LAYER0-07; the suppressions
+# array does the actual non-blocking signaling.
+DISPOSITION_TO_LEVEL: dict[Disposition, str] = {
+    Disposition.CONFIRMED: "error",
+    Disposition.UNCERTAIN: "warning",
+    Disposition.DISMISSED: "note",
+    Disposition.FIXED: "note",
+}
+
+
+def _suppressions_for(disposition: Disposition) -> Optional[list[dict[str, Any]]]:
+    """Return suppressions array or None to omit.
+
+    Disposition -> suppressions array. CONFIRMED + UNCERTAIN have no
+    suppressions (raw, blocking-relevant signal). DISMISSED + FIXED carry
+    kind=external + kind=inSource respectively per LAYER0-07.
+    Explicit dispatch on all 4 known states + ValueError default.
+    Silent None on unknown disposition (e.g., enum gained 5th state) would
+    emit wrong SARIF; loud raise surfaces the issue at deploy time.
+    """
+    if disposition in (Disposition.CONFIRMED, Disposition.UNCERTAIN):
+        return None
+    if disposition == Disposition.DISMISSED:
+        return [{"kind": "external"}]
+    if disposition == Disposition.FIXED:
+        return [{
+            "kind": "inSource",
+            "properties": {"fix_commit": None},
+        }]
+    raise ValueError(
+        "unknown Disposition %r; sarif.py mapping table needs update"
+        % disposition
+    )
+
+
+def build_sarif_log(
+    state: State,
+    tool_versions: dict[str, str],
+    forge_version: str,
+) -> dict[str, Any]:
+    """Build SARIF 2.1.0 log dict.
+
+    Raises:
+        ValueError: state.verdict is PENDING. CI never PENDINGs (no HOLD
+            in CI per GATE-01b); reaching this is a caller bug.
+    """
+    if state.verdict == Verdict.PENDING:
+        raise ValueError(
+            "build_sarif_log called with PENDING verdict; CI mode does "
+            "not enter HOLD (GATE-01b). Caller bug."
+        )
+    return {
+        "$schema": SARIF_SCHEMA_URI,
+        "version": SARIF_VERSION,
+        "runs": [_build_run(state, tool_versions, forge_version)],
+    }
+
+
+def _build_run(
+    state: State,
+    tool_versions: dict[str, str],
+    forge_version: str,
+) -> dict[str, Any]:
+    """Build SARIF run dict.
+
+    tool.driver.rules is intentionally NOT populated in v2.0.
+    Rationale: v2.0 fingerprints are sha256(tool:file:line:rule_id)[:16]
+    placeholders (Phase 3 replaces with semantic_hash). Generating rule
+    definitions from opaque hashes adds JSON noise without integrator
+    value. Integrators that need rule[] can construct from results;
+    v2.x adds rules[] when fingerprint generation evolves (Phase 3).
+    Documented as known v2.0 limitation in Out of Scope.
+    """
+    return {
+        "tool": {
+            "driver": {
+                "name": "code-forge",
+                "semanticVersion": _build_semantic_version(
+                    forge_version, tool_versions
+                ),
+                "informationUri": "https://github.com/HouMinXi/code-forge",
+            },
+        },
+        "results": [_finding_to_result(f) for f in state.findings],
+    }
+
+
+def _build_semantic_version(
+    forge_version: str,
+    tool_versions: dict[str, str],
+) -> str:
+    """LAYER0-07: 'code-forge <version> [<tool>=<ver> ...]' for reproducibility.
+
+    Sorted tool list -> deterministic output for byte-equality testing.
+
+    Tool names MUST be alphanumeric + dash/underscore (matches Phase 1
+    registry.py validation regex). Names containing `=` or `]` would
+    corrupt the format string -- pre-validated upstream by registry
+    loader; this builder trusts the input.
+    """
+    tools_str = " ".join(
+        "%s=%s" % (t, v) for t, v in sorted(tool_versions.items())
+    )
+    if tools_str:
+        return "code-forge %s [%s]" % (forge_version, tools_str)
+    return "code-forge %s []" % forge_version
+
+
+def _finding_to_result(finding: StateFinding) -> dict[str, Any]:
+    """Convert StateFinding -> SARIF result dict."""
+    result: dict[str, Any] = {
+        "ruleId": finding.fingerprint,
+        "level": DISPOSITION_TO_LEVEL[finding.disposition],
+        "message": {"text": finding.description},
+        "locations": [_build_location(finding)],
+    }
+    suppressions = _suppressions_for(finding.disposition)
+    if suppressions is not None:
+        result["suppressions"] = suppressions
+    result["properties"] = _build_properties(finding)
+    return result
+
+
+def _build_location(finding: StateFinding) -> dict[str, Any]:
+    """Build SARIF physicalLocation.
+
+    Bounds-check line_range. Production line_range is always a 2-element
+    list (02-02 _default_l0_runner sets [f.line, f.end_line]; snapshot
+    reload preserves list[int]). line_range values are 1-based (per
+    parsers/base.py Finding.line definition). SARIF spec uses 1-based
+    (region.startLine >= 1), so values pass through directly.
+
+    Defensive guard handles malformed state.json (corrupted file, partial
+    write, future schema change): empty -> startLine=1 endLine=1;
+    single-element -> endLine mirrors startLine; >2 elements -> first
+    two used, extras silently ignored (upstream schema drift case).
+    """
+    line_range = finding.line_range
+    if not line_range:
+        start = end = 1
+    elif len(line_range) == 1:
+        start = end = line_range[0]
+    else:
+        start = line_range[0]
+        end = line_range[1]
+    return {
+        "physicalLocation": {
+            "artifactLocation": {"uri": finding.file},
+            "region": {
+                "startLine": start,
+                "endLine": end,
+            },
+        },
+    }
+
+
+def _build_properties(finding: StateFinding) -> dict[str, Any]:
+    """Optional fields (anchor, evidence_files, error) -> properties dict.
+
+    Absent fields are OMITTED, not emitted as null. Keeps SARIF compact
+    for integrators that pretty-print.
+    """
+    props: dict[str, Any] = {}
+    if finding.anchor is not None:
+        props["anchor"] = finding.anchor
+    if finding.evidence_files is not None:
+        props["evidence_files"] = finding.evidence_files
+    if finding.error is not None:
+        props["error"] = finding.error
+    props["source"] = finding.source
+    return props
+
+
+def format_summary(state: State) -> str:
+    """One-line stderr summary per LAYER0-07.
+
+    Format matches regex:
+      ^code-forge: (PASS|FAIL|ESCALATED) findings=\\d+ confirmed=\\d+
+      uncertain=\\d+ dismissed=\\d+ fixed=\\d+$
+
+    Verdict.PENDING is rejected (CI never PENDINGs; caller guards).
+    """
+    if state.verdict == Verdict.PENDING:
+        raise ValueError(
+            "format_summary called with PENDING verdict; CI mode does "
+            "not enter HOLD (GATE-01b). Caller bug."
+        )
+    counts = {
+        Disposition.CONFIRMED: 0,
+        Disposition.UNCERTAIN: 0,
+        Disposition.DISMISSED: 0,
+        Disposition.FIXED: 0,
+    }
+    for f in state.findings:
+        counts[f.disposition] += 1
+    total = len(state.findings)
+    return (
+        "code-forge: %s findings=%d confirmed=%d uncertain=%d "
+        "dismissed=%d fixed=%d" % (
+            state.verdict.value, total,
+            counts[Disposition.CONFIRMED],
+            counts[Disposition.UNCERTAIN],
+            counts[Disposition.DISMISSED],
+            counts[Disposition.FIXED],
+        )
+    )