guard-cli 0.1.0__py3-none-any.whl

guard/doctor_cmd.py

@@ -0,0 +1,475 @@
+"""Guard doctor command implementation (Work Package D).
+
+Performs diagnostic verification across 6 subsystems:
+1. Environment (Python version >= 3.10, Guard version, PATH check for hooks)
+2. Backend (reachability and query round-trip)
+3. Graph (nodes > 0, edges > 0)
+4. Freshness (ingest SHA vs git HEAD SHA, changed files count)
+5. Target repo (git root, target Python, pytest, pytest-cov, baseline status)
+6. Integrations (.claude/settings.json, AGENTS.md, .gitignore)
+
+Exit codes:
+0: All checks passed
+1: Warnings present, no failures
+2: At least one failure present
+"""
+from __future__ import annotations
+import json
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+import guard
+from guard import db
+from guard.backend import (
+    GraphBackend,
+    get_repo_graph_name,
+    resolve_backend,
+    DockerBackend,
+)
+from guard.init_cmd import (
+    find_repo_root,
+    find_test_environment,
+    write_integrations,
+    INTEGRATION_MARKER_START,
+)
+
+console = Console()
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: str  # "pass", "warn", "fail"
+    message: str
+    fix: str | None = None
+
+
+def check_environment() -> CheckResult:
+    """Check Python version, Guard version, and executable on PATH."""
+    py_ver = f"{sys.version_info[0]}.{sys.version_info[1]}.{sys.version_info[2]}"
+    if sys.version_info < (3, 10):
+        return CheckResult(
+            name="environment",
+            status="fail",
+            message=f"Python {py_ver} is unsupported. Python 3.10 or newer is required.",
+            fix="Upgrade to Python 3.10+ (recommended: Python 3.12).",
+        )
+
+    guard_bin = shutil.which("guard")
+    if not guard_bin:
+        return CheckResult(
+            name="environment",
+            status="warn",
+            message=f"Python {py_ver}, guard v{guard.__version__}. 'guard' is not found on PATH for subshells and agent hooks.",
+            fix="Add your Python/uv tool bin directory to PATH (e.g. run 'uv tool update-shell' or add ~/.local/bin to PATH).",
+        )
+
+    return CheckResult(
+        name="environment",
+        status="pass",
+        message=f"Python {py_ver}, guard v{guard.__version__} (binary: {guard_bin}).",
+    )
+
+
+def check_backend(repo_path: Path) -> tuple[CheckResult, GraphBackend | None]:
+    """Check if FalkorDB backend is reachable and round-trips a query."""
+    try:
+        backend = resolve_backend(repo_path=repo_path, autostart=False)
+        desc = backend.describe()
+        if not desc.get("healthy", False):
+            return (
+                CheckResult(
+                    name="backend",
+                    status="fail",
+                    message=f"Backend '{backend.name}' is unreachable or failed query round-trip.",
+                    fix="Start FalkorDB: 'docker start guard-falkordb' or run 'guard init --backend docker'.",
+                ),
+                backend,
+            )
+        return (
+            CheckResult(
+                name="backend",
+                status="pass",
+                message=f"Backend '{backend.name}' is healthy ({desc.get('connection_str') or desc.get('data_path') or desc.get('container')}).",
+            ),
+            backend,
+        )
+    except Exception as err:
+        return (
+            CheckResult(
+                name="backend",
+                status="fail",
+                message=f"Backend resolution error: {err}",
+                fix="Run 'guard init' to configure a valid backend.",
+            ),
+            None,
+        )
+
+
+def check_graph(repo_path: Path, backend: GraphBackend | None) -> CheckResult:
+    """Verify repository graph exists in FalkorDB with non-zero nodes and edges."""
+    if backend is None or not backend.is_healthy():
+        return CheckResult(
+            name="graph",
+            status="fail",
+            message="Cannot check graph: backend is offline.",
+            fix="Ensure backend is running and re-run doctor.",
+        )
+
+    graph_name = get_repo_graph_name(repo_path)
+    try:
+        g = backend.get_graph(graph_name)
+        counts = db.get_schema_counts(g)
+        nodes_total = sum(counts.get(k, 0) for k in ("File", "Function", "Test", "Run"))
+        edges_total = sum(counts.get(k, 0) for k in ("CALLS", "IMPORTS", "DEFINED_IN", "COVERED_BY", "FAILED_IN"))
+
+        if nodes_total == 0:
+            return CheckResult(
+                name="graph",
+                status="fail",
+                message=f"Graph '{graph_name}' exists but has 0 nodes and 0 edges.",
+                fix="Run 'guard init' to ingest repository structure.",
+            )
+
+        cov_count = counts.get("COVERED_BY", 0)
+        cov_info = f", {cov_count} coverage edges" if cov_count else " (no coverage edges yet)"
+        return CheckResult(
+            name="graph",
+            status="pass",
+            message=f"Graph '{graph_name}' has {counts.get('Function', 0)} functions, {counts.get('Test', 0)} tests{cov_info}.",
+        )
+    except Exception as err:
+        return CheckResult(
+            name="graph",
+            status="fail",
+            message=f"Error querying graph '{graph_name}': {err}",
+            fix="Run 'guard init' to rebuild graph schema.",
+        )
+
+
+def check_freshness(repo_path: Path) -> CheckResult:
+    """Compare recorded ingest commit SHA with current git HEAD SHA."""
+    state_file = repo_path / ".guard" / "state.json"
+    if not state_file.exists():
+        return CheckResult(
+            name="freshness",
+            status="warn",
+            message="No recorded ingestion state found in .guard/state.json.",
+            fix="Run 'guard init' to index repository and record baseline state.",
+        )
+
+    try:
+        data = json.loads(state_file.read_text(encoding="utf-8"))
+        ingest_sha = data.get("head_sha")
+    except Exception:
+        ingest_sha = None
+
+    if not ingest_sha or ingest_sha == "unknown":
+        return CheckResult(
+            name="freshness",
+            status="warn",
+            message="Ingestion state exists but recorded commit SHA is unknown.",
+            fix="Run 'guard init' to update state with current commit.",
+        )
+
+    # Get current git HEAD SHA
+    try:
+        res = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        current_sha = res.stdout.strip() if res.returncode == 0 else ""
+    except Exception:
+        current_sha = ""
+
+    if not current_sha:
+        return CheckResult(
+            name="freshness",
+            status="warn",
+            message="Could not determine current git HEAD SHA.",
+            fix="Ensure git is installed and repository has commits.",
+        )
+
+    if ingest_sha == current_sha:
+        return CheckResult(
+            name="freshness",
+            status="pass",
+            message=f"Graph is fresh at commit {current_sha[:7]}.",
+        )
+
+    # Check changed files since ingest SHA
+    try:
+        diff_res = subprocess.run(
+            ["git", "diff", "--name-only", ingest_sha, "HEAD"],
+            cwd=str(repo_path),
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        changed_files = [f for f in diff_res.stdout.splitlines() if f.strip()]
+        if changed_files:
+            return CheckResult(
+                name="freshness",
+                status="warn",
+                message=f"{len(changed_files)} file(s) changed since ingest at {ingest_sha[:7]} (HEAD is {current_sha[:7]}).",
+                fix="Run 'guard ingest-static .' to refresh static call graph.",
+            )
+        return CheckResult(
+            name="freshness",
+            status="pass",
+            message=f"Graph is up to date (no files changed between {ingest_sha[:7]} and {current_sha[:7]}).",
+        )
+    except Exception:
+        return CheckResult(
+            name="freshness",
+            status="warn",
+            message=f"HEAD has diverged from ingest commit {ingest_sha[:7]}.",
+            fix="Run 'guard ingest-static .' to refresh call graph.",
+        )
+
+
+def check_target_repo(repo_path: Path) -> CheckResult:
+    """Verify target repo Python environment, pytest, and pytest-cov."""
+    try:
+        test_py = find_test_environment(repo_path)
+    except Exception as err:
+        return CheckResult(
+            name="target_repo",
+            status="fail",
+            message=f"Failed detecting test environment: {err}",
+            fix="Ensure virtualenv exists or pytest is installed.",
+        )
+
+    # Check pytest
+    try:
+        res = subprocess.run(
+            [str(test_py), "-m", "pytest", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if res.returncode != 0:
+            return CheckResult(
+                name="target_repo",
+                status="fail",
+                message=f"pytest is not installed in target environment ({test_py}).",
+                fix=f"Run: {test_py} -m pip install pytest",
+            )
+    except Exception:
+        return CheckResult(
+            name="target_repo",
+            status="fail",
+            message=f"pytest is not functional in target environment ({test_py}).",
+            fix=f"Run: {test_py} -m pip install pytest",
+        )
+
+    # Check pytest-cov
+    try:
+        res_cov = subprocess.run(
+            [str(test_py), "-c", "import pytest_cov"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        has_cov = (res_cov.returncode == 0)
+    except Exception:
+        has_cov = False
+
+    if not has_cov:
+        return CheckResult(
+            name="target_repo",
+            status="warn",
+            message=f"pytest present ({test_py.name}), but pytest-cov is not installed in target environment.",
+            fix=f"Run: {test_py} -m pip install pytest-cov",
+        )
+
+    return CheckResult(
+        name="target_repo",
+        status="pass",
+        message=f"Target environment verified with pytest and pytest-cov ({test_py}).",
+    )
+
+
+def check_integrations(repo_path: Path) -> CheckResult:
+    """Verify .claude/settings.json, AGENTS.md, and .gitignore integrations."""
+    missing: list[str] = []
+
+    # 1. Check .gitignore
+    gi = repo_path / ".gitignore"
+    if not gi.exists() or (".guard/" not in gi.read_text(encoding="utf-8") and ".guard" not in gi.read_text(encoding="utf-8")):
+        missing.append(".guard/ in .gitignore")
+
+    # 2. Check Claude Code Stop hook in settings.local.json or settings.json
+    from guard.integrations import claude
+    claude_info = claude.check_all_settings(repo_path)
+    if not claude_info["installed"]:
+        missing.append("hook in .claude/settings.local.json or .claude/settings.json")
+
+    # 3. Check AGENTS.md or CLAUDE.md marked block
+    agents_doc = repo_path / "AGENTS.md"
+    claude_doc = repo_path / "CLAUDE.md"
+    has_marker = False
+    for doc in (agents_doc, claude_doc):
+        if doc.exists() and INTEGRATION_MARKER_START in doc.read_text(encoding="utf-8"):
+            has_marker = True
+            break
+    if not has_marker:
+        missing.append("marked instruction block in AGENTS.md/CLAUDE.md")
+
+    if missing:
+        return CheckResult(
+            name="integrations",
+            status="warn",
+            message=f"Missing integration settings: {', '.join(missing)}.",
+            fix="Run 'guard doctor --fix' or 'guard init' to write integration files.",
+        )
+
+    return CheckResult(
+        name="integrations",
+        status="pass",
+        message="Integrations verified in .claude/settings.json, AGENTS.md, and .gitignore.",
+    )
+
+
+def apply_fixes(repo_path: Path, backend: GraphBackend | None, checks: list[CheckResult]) -> list[str]:
+    """Execute safe automated repairs for warnings/failures."""
+    applied: list[str] = []
+
+    for c in checks:
+        if c.name == "backend" and isinstance(backend, DockerBackend):
+            # Attempt to start stopped docker container
+            if backend.start_container():
+                applied.append(f"Started docker container '{backend.container_name}'.")
+
+        elif c.name == "integrations":
+            write_integrations(repo_path, agents=["claude", "cursor", "codex"])
+            applied.append("Wrote integrations to .gitignore, .claude/settings.json, AGENTS.md, and CLAUDE.md.")
+
+    return applied
+
+
+def run_doctor(
+    repo_path: str | Path | None = None,
+    json_mode: bool = False,
+    fix_mode: bool = False,
+) -> int:
+    """Run full Guard doctor diagnostic check."""
+    try:
+        root = find_repo_root(repo_path)
+    except Exception as err:
+        if json_mode:
+            print(json.dumps({
+                "status": "fail",
+                "exit_code": 2,
+                "error": str(err),
+            }, indent=2))
+        else:
+            console.print(f"[bold red]Error finding repository:[/bold red] {err}")
+        return 2
+
+    # Run checks
+    check_env_res = check_environment()
+    check_b_res, backend = check_backend(root)
+    check_g_res = check_graph(root, backend)
+    check_f_res = check_freshness(root)
+    check_t_res = check_target_repo(root)
+    check_i_res = check_integrations(root)
+
+    checks = [
+        check_env_res,
+        check_b_res,
+        check_g_res,
+        check_f_res,
+        check_t_res,
+        check_i_res,
+    ]
+
+    applied_fixes: list[str] = []
+    if fix_mode:
+        applied_fixes = apply_fixes(root, backend, checks)
+        # Re-run checks if fixes were applied
+        if applied_fixes:
+            check_b_res, backend = check_backend(root)
+            check_g_res = check_graph(root, backend)
+            check_i_res = check_integrations(root)
+            checks = [
+                check_env_res,
+                check_b_res,
+                check_g_res,
+                check_f_res,
+                check_t_res,
+                check_i_res,
+            ]
+
+    # Compute status and exit code
+    has_fail = any(c.status == "fail" for c in checks)
+    has_warn = any(c.status == "warn" for c in checks)
+
+    if has_fail:
+        overall_status = "fail"
+        exit_code = 2
+    elif has_warn:
+        overall_status = "warn"
+        exit_code = 1
+    else:
+        overall_status = "pass"
+        exit_code = 0
+
+    if json_mode:
+        payload = {
+            "status": overall_status,
+            "exit_code": exit_code,
+            "applied_fixes": applied_fixes,
+            "checks": [asdict(c) for c in checks],
+        }
+        print(json.dumps(payload, indent=2))
+        return exit_code
+
+    # Rich terminal formatting
+    console.rule("[bold cyan]Guard Doctor Diagnostic Report[/bold cyan]")
+    if applied_fixes:
+        console.print("[bold green]Automated Repairs Applied (--fix):[/bold green]")
+        for fix_msg in applied_fixes:
+            console.print(f"  [green]✔[/green] {fix_msg}")
+        console.print()
+
+    table = Table(title="Subsystem Checks", show_header=True, header_style="bold magenta")
+    table.add_column("Subsystem", style="cyan", width=15)
+    table.add_column("Status", width=10)
+    table.add_column("Details", style="white")
+
+    for c in checks:
+        if c.status == "pass":
+            status_badge = "[bold green]PASS[/bold green]"
+        elif c.status == "warn":
+            status_badge = "[bold yellow]WARN[/bold yellow]"
+        else:
+            status_badge = "[bold red]FAIL[/bold red]"
+
+        details = c.message
+        if c.fix and c.status in ("warn", "fail"):
+            details += f"\n[dim italic]Fix: {c.fix}[/dim italic]"
+
+        table.add_row(c.name, status_badge, details)
+
+    console.print(table)
+
+    pass_count = sum(1 for c in checks if c.status == "pass")
+    warn_count = sum(1 for c in checks if c.status == "warn")
+    fail_count = sum(1 for c in checks if c.status == "fail")
+
+    summary_color = "green" if exit_code == 0 else ("yellow" if exit_code == 1 else "red")
+    console.rule(f"[bold {summary_color}]Result: {pass_count} passed, {warn_count} warnings, {fail_count} failures[/bold {summary_color}]")
+
+    return exit_code

guard/events.py

@@ -0,0 +1,77 @@
+"""Append-only local event log for Guard.
+
+Records lifecycle events (hook fired, blocked, passed, handed back, fail-open)
+into `.guard/events.jsonl` in the repository root.
+"""
+from __future__ import annotations
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def get_guard_dir(repo_path: str | Path | None = None) -> Path:
+    """Returns the .guard directory path for a repo, ensuring it exists."""
+    base = Path(repo_path).resolve() if repo_path else Path.cwd()
+    guard_dir = base / ".guard"
+    guard_dir.mkdir(parents=True, exist_ok=True)
+    return guard_dir
+
+
+def log_event(
+    event: str,
+    session_id: str | None = None,
+    repo_path: str | Path | None = None,
+    details: dict[str, Any] | None = None,
+) -> Path | None:
+    """Appends an event entry to `.guard/events.jsonl`.
+    
+    Guaranteed fail-safe: never raises an exception.
+    
+    Args:
+        event: Event name (e.g. 'hook_fired', 'blocked', 'passed', 'handed_back', 'fail_open')
+        session_id: Claude Code or agent session identifier
+        repo_path: Working directory / repository root
+        details: Additional context (selected tests, failures, policy, exit code, etc.)
+        
+    Returns:
+        Path to the events.jsonl file if written, or None on failure.
+    """
+    try:
+        guard_dir = get_guard_dir(repo_path)
+        events_file = guard_dir / "events.jsonl"
+        
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "event": event,
+            "session_id": session_id or "unknown",
+            "details": details or {},
+        }
+        
+        with open(events_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry) + "\n")
+            
+        return events_file
+    except Exception:
+        # Event logging must never crash the tool
+        return None
+
+
+def read_events(repo_path: str | Path | None = None) -> list[dict[str, Any]]:
+    """Reads all recorded events from `.guard/events.jsonl`."""
+    try:
+        base = Path(repo_path).resolve() if repo_path else Path.cwd()
+        events_file = base / ".guard" / "events.jsonl"
+        if not events_file.exists():
+            return []
+            
+        events = []
+        with open(events_file, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    events.append(json.loads(line))
+        return events
+    except Exception:
+        return []

guard/feedback.py

@@ -0,0 +1,86 @@
+"""Feedback loop and repair edge mechanism for Guard (Task T6).
+
+When a test failure is missed by Guard (an escape), this module repairs
+the graph by inserting a high-confidence COVERED_BY edge with source='miss_repair',
+logging the old and new confidence values, and unsetting no_evidence flags so that
+future decisions widen to include the missed test.
+"""
+from __future__ import annotations
+import time
+from typing import Any
+from guard import db
+
+
+def record_miss(
+    g,
+    function_id: str,
+    test_id: str,
+    new_confidence: float = 1.0,
+) -> dict[str, Any]:
+    """Records a missed failure by repairing the graph with a miss_repair edge.
+
+    Args:
+        g: FalkorDB graph instance
+        function_id: ID of the function where the fault/change occurred
+        test_id: ID of the test that failed and was missed
+        new_confidence: Confidence score for the repair edge (default: 1.0)
+
+    Returns:
+        Dict reporting the repair event including old and new confidence.
+    """
+    # 1. Query existing edge if present
+    q_existing = (
+        "MATCH (f:Function {id: $fid})-[e:COVERED_BY]->(t:Test {id: $tid}) "
+        "RETURN e.confidence, e.source"
+    )
+    existing_res = g.query(q_existing, {"fid": function_id, "tid": test_id}).result_set
+    if existing_res:
+        old_confidence = float(existing_res[0][0])
+        prev_source = existing_res[0][1]
+    else:
+        old_confidence = 0.0
+        prev_source = None
+
+    ts = time.time()
+
+    # 2. Ensure Test node exists and has basic defined properties if new
+    file_part = test_id.split("::")[0] if "::" in test_id else "tests/unknown.py"
+    g.query(
+        "MERGE (t:Test {id: $tid}) "
+        "ON CREATE SET t.file = $file, t.flake_rate = 0.0",
+        {"tid": test_id, "file": file_part},
+    )
+
+    # 3. Create or update COVERED_BY edge with source='miss_repair'
+    q_repair = (
+        """MATCH (f:Function {id: $fid}), (t:Test {id: $tid})
+           MERGE (f)-[e:COVERED_BY]->(t)
+           SET e.source = 'miss_repair',
+               e.old_confidence = $old_conf,
+               e.confidence = $new_conf,
+               e.evidence_count = coalesce(e.evidence_count, 0) + 1,
+               e.last_repaired_at = $ts
+           WITH f
+           SET f.no_evidence = false"""
+    )
+    g.query(
+        q_repair,
+        {
+            "fid": function_id,
+            "tid": test_id,
+            "old_conf": old_confidence,
+            "new_conf": new_confidence,
+            "ts": ts,
+        },
+    )
+
+    return {
+        "status": "repaired",
+        "function": function_id,
+        "test": test_id,
+        "old_confidence": old_confidence,
+        "new_confidence": new_confidence,
+        "source": "miss_repair",
+        "previous_source": prev_source,
+        "timestamp": ts,
+    }