guard-cli 0.1.0__py3-none-any.whl

guard/__init__.py

@@ -0,0 +1,2 @@
+"""Guard: Graph-powered safety layer for AI coding agents."""
+__version__ = "0.1.0rc1"

guard/agent_integration.py

@@ -0,0 +1,122 @@
+"""Agent integration and test execution runner (Task T7).
+
+Provides `guard run`: an agent calls this command before declaring work complete.
+- Calls `guard check` on proposed changes.
+- If trust is low or changes are uncovered (fallback), forces a full test suite run.
+- If trust is high, runs only the selected test subset.
+- Blocks task completion if any test fails.
+"""
+from __future__ import annotations
+import os
+import sys
+import time
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from guard.thin_slice import guard_check
+
+REPO_ROOT = Path("target_repos/flask").resolve()
+
+
+def apply_patch(diff_file: Path, repo_path: Path | None = None) -> bool:
+    """Applies patch to target repo."""
+    target = repo_path or REPO_ROOT
+    proc = subprocess.run(["git", "apply", str(diff_file)], cwd=str(target), capture_output=True, text=True)
+    if proc.returncode != 0:
+        patch_proc = subprocess.run(["patch", "-p1", "-i", str(diff_file)], cwd=str(target), capture_output=True)
+        return patch_proc.returncode == 0
+    return True
+
+
+def reset_repo(repo_path: Path | None = None):
+    """Restores target repo to clean state."""
+    target = repo_path or REPO_ROOT
+    subprocess.run(["git", "checkout", "--", "."], cwd=str(target), capture_output=True)
+    subprocess.run(["git", "clean", "-fdx"], cwd=str(target), capture_output=True)
+
+
+def count_collected_tests(test_targets: list[str], repo_path: Path | None = None) -> int:
+    """Counts how many test items are collected for the targets."""
+    target = repo_path or REPO_ROOT
+    cmd = [sys.executable, "-m", "pytest", "--collect-only", "-q"] + test_targets
+    proc = subprocess.run(cmd, cwd=str(target), capture_output=True, text=True)
+    lines = proc.stdout.strip().splitlines()
+    for line in reversed(lines):
+        if "test" in line:
+            parts = line.split()
+            for p in parts:
+                if p.isdigit():
+                    return int(p)
+    return len(test_targets)
+
+
+def run_agent_guard(
+    diff_file: str | Path | None = None,
+    repo_path: str | Path | None = None,
+    graph_name: str = "guard",
+) -> tuple[dict[str, Any], int]:
+    """Runs Guard check and executes tests according to trust level.
+    
+    Returns:
+        (report_dict, exit_code)
+    """
+    repo = Path(repo_path).resolve() if repo_path else REPO_ROOT
+    diff_path = Path(diff_file).resolve() if diff_file else None
+
+    # 1. Run guard check
+    check_res = guard_check(
+        diff_file=diff_path,
+        repo_path=repo,
+        graph_name=graph_name,
+    )
+
+    forced_full = check_res.is_fallback or (check_res.status == "run-all")
+    tests_to_run = ["tests"] if forced_full else check_res.selected_tests
+
+    # 2. If a patch file was passed, apply it temporarily for test execution
+    applied = False
+    if diff_path and diff_path.exists():
+        reset_repo()
+        applied = apply_patch(diff_path)
+        if not applied:
+            return {
+                "status": "error",
+                "forced_full": True,
+                "fallback_reason": "Failed to apply patch diff",
+                "changed_functions": [],
+                "tests_run": [],
+                "tests_run_count": 0,
+                "duration_s": 0.0,
+                "tests_passed": False,
+                "exit_code": 1,
+                "output_summary": "Error: Failed to apply patch cleanly to target repo.",
+            }, 1
+
+    try:
+        # Count collected tests
+        test_count = count_collected_tests(tests_to_run)
+
+        # 3. Execute pytest
+        cmd = [sys.executable, "-m", "pytest", "-q", "--tb=short"] + tests_to_run
+        start = time.time()
+        proc = subprocess.run(cmd, cwd=str(repo), capture_output=True, text=True)
+        duration_s = time.time() - start
+
+        passed = (proc.returncode == 0)
+        report = {
+            "status": check_res.status,
+            "forced_full": forced_full,
+            "fallback_reason": check_res.fallback_reason,
+            "changed_functions": check_res.changed_functions,
+            "tests_run": tests_to_run,
+            "tests_run_count": test_count,
+            "duration_s": round(duration_s, 3),
+            "tests_passed": passed,
+            "exit_code": proc.returncode,
+            "output_summary": proc.stdout.strip().splitlines()[-1] if proc.stdout.strip() else "",
+        }
+        return report, proc.returncode
+    finally:
+        if applied:
+            reset_repo()

guard/api.py

@@ -0,0 +1,397 @@
+"""Guard Public API and Stable Contract (Phase 0).
+
+Provides the unified contract used across the CLI, Claude Code hook,
+MCP server, and external agent loops:
+- `check()`: Evaluates diff, returns test selection decision + versioned schema.
+- `run()`: Executes the selected test subset according to trust policy.
+- `covering_tests()`: Queries graph for tests covering a function.
+- `callers()`: Queries multi-hop callers of a function.
+- `report_miss()`: Feedback loop repairing graph with a miss_repair edge.
+
+Fail-open by default: If database or graph is unavailable and strict=False,
+Guard emits a warning to stderr and fails open instead of blocking the agent.
+"""
+from __future__ import annotations
+import re
+import sys
+import time
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from guard import db
+from guard import feedback
+from guard.events import log_event
+from guard.thin_slice import (
+    guard_check,
+    parse_unified_diff,
+    resolve_changed_functions,
+    thin_slice_decision,
+    CheckResult,
+)
+from guard.agent_integration import (
+    REPO_ROOT,
+    apply_patch,
+    reset_repo,
+    count_collected_tests,
+)
+
+SCHEMA_VERSION = "1.0"
+
+
+def _extract_failures(stdout: str, stderr: str) -> list[str]:
+    """Parses failing pytest test identifiers from output."""
+    failures = []
+    # pytest output lines typically look like:
+    # FAILED tests/test_config.py::test_config_class - AssertionError...
+    fail_regex = re.compile(r"^FAILED\s+([^\s]+)", re.MULTILINE)
+    for match in fail_regex.finditer(stdout):
+        failures.append(match.group(1))
+    for match in fail_regex.finditer(stderr):
+        failures.append(match.group(1))
+    return sorted(list(set(failures)))
+
+
+def _format_reasons(check_res: CheckResult) -> dict[str, str]:
+    """Generates a reasons map for selected tests."""
+    reasons: dict[str, str] = {}
+    if check_res.is_fallback:
+        reason_text = check_res.fallback_reason or "Fallback triggered"
+        for t in check_res.selected_tests:
+            reasons[t] = f"selected: full suite required ({reason_text})"
+    else:
+        for t in check_res.selected_tests:
+            reasons[t] = "selected: covering edge from changed function"
+    return reasons
+
+
+def normalize_test_target_for_pytest(target: str) -> str:
+    """Normalizes graph test identifiers into valid pytest CLI invocation targets."""
+    if "::" not in target:
+        return target
+    file_part, func_part = target.split("::", 1)
+    if "." in func_part:
+        cls_name, method_name = func_part.split(".", 1)
+        if method_name.startswith("test"):
+            return f"{file_part}::{cls_name}::{method_name}"
+        else:
+            return f"{file_part}::{cls_name}"
+    else:
+        if func_part.startswith("test") or func_part.startswith("Test"):
+            return target
+        else:
+            return file_part
+
+
+def check(
+    diff_text: str | None = None,
+    diff_file: str | Path | None = None,
+    repo_path: str | Path | None = None,
+    graph_name: str = "guard",
+    strict: bool = False,
+    no_confidence_filter: bool = False,
+    no_dynamic_widening: bool = False,
+) -> dict[str, Any]:
+    """Evaluates proposed changes and returns test selection decision.
+    
+    Returns a versioned JSON dictionary conforming to schema v1.0.
+    """
+    repo = Path(repo_path).resolve() if repo_path else Path.cwd()
+    diff_path = Path(diff_file).resolve() if diff_file else None
+
+    try:
+        res = guard_check(
+            diff_text=diff_text,
+            diff_file=diff_path,
+            repo_path=repo,
+            graph_name=graph_name,
+            no_confidence_filter=no_confidence_filter,
+            no_dynamic_widening=no_dynamic_widening,
+        )
+
+        is_fallback = res.is_fallback
+        policy = "subset" if not is_fallback else "run_all"
+        trust = 0.9 if not is_fallback else 0.0
+
+        overrides = []
+        if is_fallback:
+            if res.fallback_reason:
+                if "Test files" in res.fallback_reason:
+                    overrides.append("test_file_touched")
+                elif "no_evidence" in res.fallback_reason or "No covering tests" in res.fallback_reason or "No parsed" in res.fallback_reason:
+                    overrides.append("no_evidence")
+                else:
+                    overrides.append("fallback_override")
+
+        reasons = _format_reasons(res)
+
+        return {
+            "version": SCHEMA_VERSION,
+            "status": res.status,
+            "policy": policy,
+            "trust": trust,
+            "overrides_triggered": overrides,
+            "selected_tests": res.selected_tests,
+            "selected_tests_count": len(res.selected_tests),
+            "failures": [],
+            "reasons": reasons,
+            "changed_functions": res.changed_functions,
+            "is_fallback": res.is_fallback,
+            "fallback_reason": res.fallback_reason,
+            "execution_time_ms": res.execution_time_ms,
+        }
+    except Exception as exc:
+        if strict:
+            raise
+        sys.stderr.write(f"Guard warning (fail-open): check failed with {exc}\n")
+        log_event(
+            event="fail_open",
+            repo_path=repo,
+            details={"op": "check", "error": str(exc)},
+        )
+        return {
+            "version": SCHEMA_VERSION,
+            "status": "run-all",
+            "policy": "fail_open",
+            "trust": 0.0,
+            "overrides_triggered": ["fail_open_error"],
+            "selected_tests": ["tests"],
+            "selected_tests_count": 1,
+            "failures": [],
+            "reasons": {"error": f"Guard check error: {exc}"},
+            "changed_functions": [],
+            "is_fallback": True,
+            "fallback_reason": f"Guard database/internal error: {exc}",
+            "execution_time_ms": 0.0,
+            "fail_open": True,
+            "error": str(exc),
+        }
+
+
+def run(
+    diff_file: str | Path | None = None,
+    diff_text: str | None = None,
+    repo_path: str | Path | None = None,
+    graph_name: str = "guard",
+    strict: bool = False,
+    session_id: str | None = None,
+) -> tuple[dict[str, Any], int]:
+    """Runs Guard check and executes the selected tests.
+    
+    Returns:
+        (report_dict, exit_code)
+    """
+    repo = Path(repo_path).resolve() if repo_path else Path.cwd()
+    diff_path = Path(diff_file).resolve() if diff_file else None
+
+    # 1. Run check
+    try:
+        check_dict = check(
+            diff_text=diff_text,
+            diff_file=diff_path,
+            repo_path=repo,
+            graph_name=graph_name,
+            strict=strict,
+        )
+    except Exception as exc:
+        if strict:
+            raise
+        sys.stderr.write(f"Guard warning (fail-open): check failed with {exc}\n")
+        log_event(
+            event="fail_open",
+            session_id=session_id,
+            repo_path=repo,
+            details={"op": "run", "error": str(exc)},
+        )
+        return {
+            "version": SCHEMA_VERSION,
+            "status": "passed",
+            "policy": "fail_open",
+            "trust": 0.0,
+            "overrides_triggered": ["fail_open_error"],
+            "selected_tests": [],
+            "failures": [],
+            "reasons": {},
+            "tests_run": [],
+            "tests_run_count": 0,
+            "tests_passed": True,
+            "forced_full": False,
+            "fallback_reason": str(exc),
+            "duration_s": 0.0,
+            "exit_code": 0,
+            "output_summary": f"Guard bypassed fail-open: {exc}",
+            "fail_open": True,
+        }, 0
+
+    forced_full = check_dict.get("is_fallback", False) or (check_dict.get("status") == "run-all")
+    if forced_full:
+        tests_to_run = ["tests"]
+    else:
+        raw_selected = check_dict.get("selected_tests", ["tests"])
+        tests_to_run = list(dict.fromkeys(normalize_test_target_for_pytest(t) for t in raw_selected))
+
+    # 2. Apply patch if explicit diff_file was provided
+    applied = False
+    if diff_path and diff_path.exists():
+        reset_repo(repo)
+        applied = apply_patch(diff_path, repo)
+        if not applied:
+            err_dict = {
+                "version": SCHEMA_VERSION,
+                "status": "error",
+                "policy": check_dict.get("policy", "run_all"),
+                "trust": check_dict.get("trust", 0.0),
+                "overrides_triggered": check_dict.get("overrides_triggered", []),
+                "selected_tests": tests_to_run,
+                "failures": ["patch_apply_failure"],
+                "reasons": check_dict.get("reasons", {}),
+                "forced_full": True,
+                "fallback_reason": "Failed to apply patch diff",
+                "changed_functions": check_dict.get("changed_functions", []),
+                "tests_run": [],
+                "tests_run_count": 0,
+                "duration_s": 0.0,
+                "tests_passed": False,
+                "exit_code": 1,
+                "output_summary": "Error: Failed to apply patch cleanly to target repo.",
+            }
+            log_event(
+                event="failed",
+                session_id=session_id,
+                repo_path=repo,
+                details=err_dict,
+            )
+            return err_dict, 1
+
+    try:
+        # Count collected tests
+        test_count = count_collected_tests(tests_to_run, repo)
+
+        # Resolve target repo python interpreter
+        py_bin = sys.executable
+        if repo:
+            try:
+                from guard.init_cmd import find_test_environment
+                py_bin = str(find_test_environment(repo))
+            except Exception:
+                pass
+
+        # 3. Execute pytest (180s timeout for worst-case run-all test suites)
+        cmd = [py_bin, "-m", "pytest", "-q", "--tb=short"] + tests_to_run
+        start = time.time()
+        try:
+            proc = subprocess.run(cmd, cwd=str(repo), capture_output=True, text=True, timeout=180)
+            duration_s = round(time.time() - start, 3)
+            passed = (proc.returncode == 0)
+            failures = _extract_failures(proc.stdout, proc.stderr)
+            summary_line = proc.stdout.strip().splitlines()[-1] if proc.stdout.strip() else ""
+            proc_exit_code = proc.returncode
+        except subprocess.TimeoutExpired:
+            duration_s = round(time.time() - start, 3)
+            passed = False
+            failures = ["test_suite_timeout_expired_180s"]
+            summary_line = f"Test execution timed out after {duration_s:.1f}s."
+            proc_exit_code = 124
+
+        report = {
+            "version": SCHEMA_VERSION,
+            "status": "passed" if passed else "failed",
+            "policy": check_dict.get("policy", "subset"),
+            "trust": check_dict.get("trust", 0.9 if passed else 0.0),
+            "overrides_triggered": check_dict.get("overrides_triggered", []),
+            "selected_tests": check_dict.get("selected_tests", []),
+            "failures": failures,
+            "reasons": check_dict.get("reasons", {}),
+            "forced_full": forced_full,
+            "fallback_reason": check_dict.get("fallback_reason"),
+            "changed_functions": check_dict.get("changed_functions", []),
+            "tests_run": tests_to_run,
+            "tests_run_count": test_count,
+            "duration_s": duration_s,
+            "tests_passed": passed,
+            "exit_code": proc_exit_code,
+            "output_summary": summary_line,
+        }
+
+        # Log event
+        log_event(
+            event="passed" if passed else "blocked",
+            session_id=session_id,
+            repo_path=repo,
+            details={
+                "exit_code": proc_exit_code,
+                "tests_passed": passed,
+                "tests_run_count": test_count,
+                "failures": failures,
+                "policy": report["policy"],
+            },
+        )
+
+        return report, proc_exit_code
+    finally:
+        if applied:
+            reset_repo()
+
+
+def covering_tests(
+    function_id: str,
+    min_confidence: float = 0.0,
+    graph_name: str = "guard",
+    strict: bool = False,
+) -> list[dict[str, Any]]:
+    """Find tests covering a given function, ordered by confidence."""
+    try:
+        g = db.get_graph(graph_name)
+        return db.get_covering_tests(g, function_id, min_confidence=min_confidence)
+    except Exception as exc:
+        if strict:
+            raise
+        sys.stderr.write(f"Guard warning (fail-open): covering_tests failed with {exc}\n")
+        return []
+
+
+def callers(
+    function_id: str,
+    hops: int = 4,
+    min_confidence: float = 0.0,
+    graph_name: str = "guard",
+    strict: bool = False,
+) -> list[dict[str, Any]]:
+    """Traverse inbound CALLS edges up to N hops filtered by min_confidence."""
+    try:
+        g = db.get_graph(graph_name)
+        return db.get_callers(g, function_id, hops=hops, min_confidence=min_confidence)
+    except Exception as exc:
+        if strict:
+            raise
+        sys.stderr.write(f"Guard warning (fail-open): callers failed with {exc}\n")
+        return []
+
+
+def report_miss(
+    function_id: str,
+    test_id: str,
+    new_confidence: float = 1.0,
+    graph_name: str = "guard",
+    strict: bool = False,
+) -> dict[str, Any]:
+    """Records a missed failure by repairing the graph with a miss_repair edge."""
+    try:
+        g = db.get_graph(graph_name)
+        return feedback.record_miss(
+            g,
+            function_id=function_id,
+            test_id=test_id,
+            new_confidence=new_confidence,
+        )
+    except Exception as exc:
+        if strict:
+            raise
+        sys.stderr.write(f"Guard warning (fail-open): report_miss failed with {exc}\n")
+        return {
+            "status": "error",
+            "error": str(exc),
+            "function": function_id,
+            "test": test_id,
+            "fail_open": True,
+        }