guard-cli 0.1.0__py3-none-any.whl

guard/init_cmd.py

@@ -0,0 +1,437 @@
+"""Guard init command implementation (Work Package C).
+
+Steps:
+1. Find the repo (git root + test configuration)
+2. Find the test environment (target repo's own virtualenv / python)
+3. Check pytest-cov (offer to install if missing, never silent)
+4. Start/resolve backend (Server, Docker, or Embedded)
+5. Static ingest (fast static parsing with rich progress summary)
+6. Baseline run (time 1 pytest run, estimate 3x cost, exclude failing tests)
+7. Coverage ingest (per-test coverage using target environment)
+8. Record state (HEAD SHA + timestamp in graph and .guard/state.json)
+9. Write integrations (.claude/settings.json, AGENTS.md, CLAUDE.md, .gitignore)
+"""
+from __future__ import annotations
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+from guard.backend import (
+    GraphBackend,
+    get_repo_graph_name,
+    resolve_backend,
+    save_config,
+)
+
+console = Console()
+
+INTEGRATION_MARKER_START = "<!-- BEGIN GUARD INTEGRATION -->"
+INTEGRATION_MARKER_END = "<!-- END GUARD INTEGRATION -->"
+
+GUARD_INSTRUCTIONS_BLOCK = f"""{INTEGRATION_MARKER_START}
+## Guard Safety Layer
+
+Before declaring any code edits or refactoring complete, run:
+```bash
+guard run
+```
+
+If Guard flags low trust, unverified call paths, or uncovered changes, it enforces a full test suite run. Do not bypass or suppress Guard failures.
+{INTEGRATION_MARKER_END}"""
+
+
+def find_repo_root(start_path: str | Path | None = None) -> Path:
+    """Locate the git root and verify test configuration exists."""
+    p = Path(start_path).resolve() if start_path else Path.cwd()
+
+    # Try git rev-parse --show-toplevel
+    try:
+        res = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(p),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if res.returncode == 0 and res.stdout.strip():
+            root = Path(res.stdout.strip()).resolve()
+        else:
+            root = p
+    except Exception:
+        root = p
+
+    # Find test configs or test directory
+    test_markers = [
+        "pyproject.toml",
+        "pytest.ini",
+        "setup.cfg",
+        "tox.ini",
+        "tests",
+        "test",
+    ]
+    has_test_config = any((root / m).exists() for m in test_markers)
+    if not has_test_config and not (root / ".git").exists():
+        raise ValueError(
+            f"Directory '{root}' does not appear to be a Python git repository with tests. "
+            "Could not find pyproject.toml, pytest.ini, setup.cfg, tox.ini, or tests/."
+        )
+
+    return root
+
+
+def find_test_environment(repo_path: Path) -> Path:
+    """Find the target repo's own virtualenv or Python executable."""
+    candidates = [
+        repo_path / ".venv",
+        repo_path / "venv",
+        repo_path / "env",
+        repo_path / ".env",
+    ]
+    if "VIRTUAL_ENV" in os.environ:
+        candidates.insert(0, Path(os.environ["VIRTUAL_ENV"]))
+
+    for c in candidates:
+        if c.is_dir():
+            # Check bin/python (Unix) or Scripts/python.exe (Windows)
+            py_unix = c / "bin" / "python"
+            py_win = c / "Scripts" / "python.exe"
+            py = py_unix if py_unix.exists() else py_win
+            if py.exists():
+                try:
+                    res = subprocess.run(
+                        [str(py), "-m", "pytest", "--version"],
+                        capture_output=True,
+                        text=True,
+                        timeout=5,
+                    )
+                    if res.returncode == 0:
+                        return py
+                except Exception:
+                    pass
+
+    # Fallback to current sys.executable
+    return Path(sys.executable)
+
+
+def check_pytest_cov(test_python: Path, auto_yes: bool = False) -> bool:
+    """Check if pytest-cov is installed in the target environment; offer to install if missing."""
+    try:
+        res = subprocess.run(
+            [str(test_python), "-c", "import pytest_cov"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if res.returncode == 0:
+            return True
+    except Exception:
+        pass
+
+    console.print("[yellow]pytest-cov is not installed in the target environment.[/yellow]")
+    install = False
+    if auto_yes:
+        install = True
+    else:
+        # Ask interactively if running in a TTY
+        if sys.stdin.isatty():
+            ans = input("pytest-cov is required for test coverage tracking. Install it into target environment? [Y/n]: ")
+            if ans.strip().lower() in ("y", "yes", ""):
+                install = True
+        else:
+            console.print("[dim]Non-interactive environment and --yes not specified; skipping pytest-cov install.[/dim]")
+
+    if install:
+        console.print(f"[cyan]Installing pytest-cov using {test_python}...[/cyan]")
+        try:
+            res = subprocess.run(
+                [str(test_python), "-m", "pip", "install", "pytest-cov"],
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if res.returncode == 0:
+                console.print("[green]pytest-cov installed successfully.[/green]")
+                return True
+            else:
+                console.print(f"[red]Failed to install pytest-cov:[/red] {res.stderr}")
+        except Exception as err:
+            console.print(f"[red]Error installing pytest-cov:[/red] {err}")
+
+    return False
+
+
+def setup_backend(
+    repo_path: Path,
+    preference: str | None = None,
+) -> tuple[GraphBackend, str]:
+    """Start and configure backend for repository."""
+    graph_name = get_repo_graph_name(repo_path)
+    backend = resolve_backend(preference=preference, repo_path=repo_path, autostart=True)
+
+    desc = backend.describe()
+    console.print(f"[bold green]Backend selected:[/bold green] [cyan]{backend.name}[/cyan] ({desc.get('status') or desc.get('connection_str') or desc.get('data_path')})")
+
+    # Store in .guard/config.toml
+    cfg = {
+        "backend": {
+            "type": backend.name,
+            "host": desc.get("host", "localhost"),
+            "port": desc.get("port", 6379),
+            "graph_name": graph_name,
+        }
+    }
+    save_config(repo_path, cfg)
+    return backend, graph_name
+
+
+def run_static_ingest(
+    repo_path: Path,
+    graph_name: str,
+    backend: GraphBackend,
+    commit_sha: str | None = None,
+) -> Any:
+    """Analyze static repository structure and ingest into FalkorDB."""
+    from guard.ingest.static import analyze_repo
+    from guard import db
+
+    console.print(f"[cyan]Parsing static call graph for repository '{repo_path.name}'...[/cyan]")
+    res = analyze_repo(repo_path, include_tests=True)
+
+    g = backend.get_graph(graph_name)
+    db.reset_graph(g)
+    g = backend.get_graph(graph_name)
+    db.ensure_schema(g)
+    db.write_static(g, res, commit_sha=commit_sha)
+
+    counts = db.get_schema_counts(g)
+    console.print(
+        f"[green]Static graph ingested:[/green] "
+        f"{counts.get('File', 0)} files, {counts.get('Function', 0)} functions, "
+        f"{counts.get('Test', 0)} tests, {counts.get('CALLS', 0)} calls."
+    )
+    return res
+
+
+def run_baseline_and_coverage(
+    repo_path: Path,
+    graph_name: str,
+    test_python: Path,
+    skip_coverage: bool = False,
+    runs_requested: int | None = None,
+    auto_yes: bool = False,
+    commit_sha: str | None = None,
+) -> None:
+    """Execute baseline suite and per-test coverage ingestion."""
+    if skip_coverage:
+        console.print("[dim]Skipping coverage ingestion as requested (--skip-coverage).[/dim]")
+        return
+
+    # 1. Baseline timing run
+    console.print(f"[cyan]Running single baseline test run with {test_python.name}...[/cyan]")
+    start = time.time()
+    proc = subprocess.run(
+        [str(test_python), "-m", "pytest", "-q"],
+        cwd=str(repo_path),
+        capture_output=True,
+        text=True,
+        timeout=180,
+    )
+    baseline_dur = time.time() - start
+
+    failing_tests: list[str] = []
+    if proc.returncode != 0:
+        for line in proc.stdout.splitlines():
+            if line.startswith("FAILED "):
+                t_name = line.split()[1]
+                failing_tests.append(t_name)
+        if failing_tests:
+            console.print(
+                f"[yellow]Warning: {len(failing_tests)} tests failed during baseline run. "
+                "These will be excluded from coverage evidence to avoid poisoning the graph.[/yellow]"
+            )
+
+    # Determine num_runs
+    if runs_requested is not None:
+        runs = runs_requested
+    elif auto_yes:
+        runs = 3 if baseline_dur < 10.0 else 1
+    else:
+        if sys.stdin.isatty():
+            est_3 = baseline_dur * 3
+            ans = input(f"Baseline run took {baseline_dur:.1f}s. A 3-run flake baseline will take ~{est_3:.1f}s. Run 3 runs? [y/N]: ")
+            runs = 3 if ans.strip().lower() in ("y", "yes") else 1
+        else:
+            runs = 1
+
+    console.print(f"[cyan]Ingesting per-test coverage ({runs} run(s))...[/cyan]")
+    from guard.ingest.coverage import ingest_coverage
+
+    ingest_coverage(
+        repo_path=repo_path,
+        graph_name=graph_name,
+        commit_sha=commit_sha,
+        num_runs=runs,
+        python_exe=str(test_python),
+    )
+    console.print("[green]Per-test coverage successfully ingested into graph.[/green]")
+
+
+def record_state(
+    repo_path: Path,
+    graph_name: str,
+    backend: GraphBackend,
+    commit_sha: str | None = None,
+) -> dict[str, Any]:
+    """Record current git HEAD SHA and ingestion timestamp in graph and .guard/state.json."""
+    if commit_sha is None:
+        try:
+            res = subprocess.run(
+                ["git", "rev-parse", "HEAD"],
+                cwd=str(repo_path),
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            commit_sha = res.stdout.strip() if res.returncode == 0 else "unknown"
+        except Exception:
+            commit_sha = "unknown"
+
+    ts = datetime.now(timezone.utc).isoformat()
+
+    # Record in graph
+    try:
+        g = backend.get_graph(graph_name)
+        g.query(
+            """MERGE (s:RepoState {graph: $graph})
+               SET s.head_sha = $sha, s.ingested_at = $ts""",
+            {"graph": graph_name, "sha": commit_sha, "ts": ts},
+        )
+    except Exception:
+        pass
+
+    state_data = {
+        "head_sha": commit_sha,
+        "ingested_at": ts,
+        "graph_name": graph_name,
+        "repo_path": str(repo_path),
+    }
+
+    guard_dir = repo_path / ".guard"
+    guard_dir.mkdir(parents=True, exist_ok=True)
+    state_file = guard_dir / "state.json"
+    state_file.write_text(json.dumps(state_data, indent=2) + "\n", encoding="utf-8")
+    return state_data
+
+
+def write_integrations(repo_path: Path, agents: list[str]) -> list[Path]:
+    """Safely update .gitignore, .claude/settings.json, AGENTS.md, and CLAUDE.md."""
+    modified_files: list[Path] = []
+
+    # 1. Update .gitignore
+    gitignore = repo_path / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text(encoding="utf-8")
+        if ".guard/" not in content and ".guard" not in content:
+            new_content = content.rstrip() + "\n.guard/\n"
+            gitignore.write_text(new_content, encoding="utf-8")
+            modified_files.append(gitignore)
+    else:
+        gitignore.write_text(".guard/\n", encoding="utf-8")
+        modified_files.append(gitignore)
+
+    # 2. Install Claude Code Stop hook and settings via claude integration
+    if "claude" in agents:
+        from guard.integrations import claude
+        ok, msg = claude.install(repo_path=repo_path, shared=False)
+        settings_file = claude.get_settings_path(repo_path=repo_path, shared=False)
+        if settings_file.exists() and settings_file not in modified_files:
+            modified_files.append(settings_file)
+
+    # 3. Update AGENTS.md and CLAUDE.md idempotently
+    doc_targets = ["AGENTS.md"]
+    if "claude" in agents:
+        doc_targets.append("CLAUDE.md")
+
+    for doc_name in doc_targets:
+        doc_path = repo_path / doc_name
+        if doc_path.exists():
+            text = doc_path.read_text(encoding="utf-8")
+            if INTEGRATION_MARKER_START in text and INTEGRATION_MARKER_END in text:
+                # Replace marked block in-place
+                prefix = text.split(INTEGRATION_MARKER_START)[0]
+                suffix = text.split(INTEGRATION_MARKER_END)[1]
+                updated = prefix.rstrip() + "\n\n" + GUARD_INSTRUCTIONS_BLOCK + "\n" + suffix.lstrip()
+            else:
+                updated = text.rstrip() + "\n\n" + GUARD_INSTRUCTIONS_BLOCK + "\n"
+        else:
+            updated = f"# {repo_path.name}\n\n{GUARD_INSTRUCTIONS_BLOCK}\n"
+
+        doc_path.write_text(updated, encoding="utf-8")
+        modified_files.append(doc_path)
+
+    return modified_files
+
+
+def run_init(
+    repo_path: str | Path | None = None,
+    backend_preference: str | None = None,
+    skip_coverage: bool = False,
+    auto_yes: bool = False,
+    agents: str = "claude,cursor,codex",
+    runs: int | None = None,
+) -> int:
+    """Execute complete guard init workflow."""
+    console.rule("[bold cyan]Guard Repository Initialization[/bold cyan]")
+
+    # Step 1: Find repo
+    root = find_repo_root(repo_path)
+    console.print(f"[bold]Target Repository:[/bold] {root}")
+
+    # Step 2: Find test environment
+    test_python = find_test_environment(root)
+    console.print(f"[bold]Target Python Environment:[/bold] {test_python}")
+
+    # Step 3: Check pytest-cov
+    cov_available = check_pytest_cov(test_python, auto_yes=auto_yes)
+    if not cov_available:
+        skip_coverage = True
+
+    # Step 4: Backend setup
+    backend, graph_name = setup_backend(root, preference=backend_preference)
+
+    # Step 5: Static ingest
+    run_static_ingest(root, graph_name, backend)
+
+    # Step 6 & 7: Baseline and coverage ingest
+    run_baseline_and_coverage(
+        root,
+        graph_name,
+        test_python,
+        skip_coverage=skip_coverage,
+        runs_requested=runs,
+        auto_yes=auto_yes,
+    )
+
+    # Step 8: Record state
+    state = record_state(root, graph_name, backend)
+    console.print(f"[green]Recorded state:[/green] commit [bold]{state['head_sha'][:7]}[/bold] at {state['ingested_at']}")
+
+    # Step 9: Write integrations
+    agent_list = [a.strip().lower() for a in agents.split(",") if a.strip()]
+    modified = write_integrations(root, agent_list)
+    console.print(f"[green]Configured integrations for:[/green] {', '.join(agent_list)}")
+    for m in modified:
+        console.print(f"  - Updated: [dim]{m.relative_to(root)}[/dim]")
+
+    console.rule("[bold green]Initialization Complete[/bold green]")
+    console.print("Run [bold cyan]guard doctor[/bold cyan] to verify system health.")
+    return 0

guard/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integration writers for coding assistants and editors."""

guard/integrations/claude.py

@@ -0,0 +1,195 @@
+"""Claude Code Stop Hook Integration Writer.
+
+Installs, uninstalls, and checks status of Guard's Stop hook in Claude Code settings.
+- By default writes to `.claude/settings.local.json` (uncommitted local settings).
+- Supports `--shared` for `.claude/settings.json` (team committed settings).
+- Merges into existing `hooks.Stop` array, preserving all other configuration.
+- Creates `.bak` backups before modifying existing files.
+"""
+from __future__ import annotations
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+HOOK_COMMAND = "guard hook stop"
+DEFAULT_HOOK_TIMEOUT = 180
+
+
+def get_settings_path(repo_path: str | Path | None = None, shared: bool = False) -> Path:
+    """Returns the path to Claude Code settings file."""
+    base = Path(repo_path).resolve() if repo_path else Path.cwd()
+    if shared:
+        return base / ".claude" / "settings.json"
+    local_file = base / ".claude" / "settings.local.json"
+    shared_file = base / ".claude" / "settings.json"
+    if not local_file.exists() and shared_file.exists():
+        return shared_file
+    return local_file
+
+
+def _contains_guard_hook(item: Any) -> bool:
+    if isinstance(item, dict):
+        if item.get("command") == HOOK_COMMAND:
+            return True
+        inner = item.get("hooks", [])
+        if isinstance(inner, list):
+            return any(isinstance(h, dict) and h.get("command") == HOOK_COMMAND for h in inner)
+    return False
+
+
+def status(repo_path: str | Path | None = None, shared: bool = False) -> dict[str, Any]:
+    """Checks whether Guard Stop hook is installed in Claude settings."""
+    settings_file = get_settings_path(repo_path, shared=shared)
+    if not settings_file.exists():
+        return {
+            "installed": False,
+            "target_file": str(settings_file),
+            "exists": False,
+            "shared": shared,
+        }
+
+    try:
+        with open(settings_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        
+        hooks = data.get("hooks", {})
+        stop_hooks = hooks.get("Stop", [])
+        
+        installed = any(_contains_guard_hook(h) for h in stop_hooks)
+        return {
+            "installed": installed,
+            "target_file": str(settings_file),
+            "exists": True,
+            "shared": shared,
+            "stop_hooks_count": len(stop_hooks),
+        }
+    except Exception as exc:
+        return {
+            "installed": False,
+            "target_file": str(settings_file),
+            "exists": True,
+            "shared": shared,
+            "error": str(exc),
+        }
+
+
+def check_all_settings(repo_path: str | Path | None = None) -> dict[str, Any]:
+    """Checks whether Guard Stop hook is installed in either local or shared settings."""
+    local_stat = status(repo_path=repo_path, shared=False)
+    shared_stat = status(repo_path=repo_path, shared=True)
+    installed = local_stat["installed"] or shared_stat["installed"]
+    active_target = local_stat["target_file"] if local_stat["installed"] else (
+        shared_stat["target_file"] if shared_stat["installed"] else local_stat["target_file"]
+    )
+    return {
+        "installed": installed,
+        "local": local_stat,
+        "shared": shared_stat,
+        "active_target": active_target,
+    }
+
+
+def install(repo_path: str | Path | None = None, shared: bool = False) -> tuple[bool, str]:
+    """Installs the Guard Stop hook into Claude Code settings.
+    
+    Returns:
+        (success: bool, message: str)
+    """
+    settings_file = get_settings_path(repo_path, shared=shared)
+    settings_file.parent.mkdir(parents=True, exist_ok=True)
+
+    data: dict[str, Any] = {}
+    if settings_file.exists():
+        # Backup original
+        bak_file = settings_file.with_suffix(settings_file.suffix + ".bak")
+        shutil.copy2(settings_file, bak_file)
+        try:
+            with open(settings_file, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                if not isinstance(data, dict):
+                    data = {}
+        except Exception as exc:
+            return False, f"Failed to parse existing {settings_file}: {exc}"
+
+    hooks = data.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        hooks = {}
+        data["hooks"] = hooks
+
+    stop_hooks = hooks.setdefault("Stop", [])
+    if not isinstance(stop_hooks, list):
+        stop_hooks = []
+        hooks["Stop"] = stop_hooks
+
+    # Configure command alias
+    commands = data.setdefault("commands", {})
+    if isinstance(commands, dict):
+        commands["guard"] = "guard run"
+
+    # Check if already present
+    for h in stop_hooks:
+        if _contains_guard_hook(h):
+            return True, f"Guard Stop hook is already installed in {settings_file}"
+
+    # Claude Code expects matcher objects with a 'hooks' list
+    stop_hooks.append({
+        "command": HOOK_COMMAND,
+        "hooks": [
+            {
+                "type": "command",
+                "command": HOOK_COMMAND,
+                "timeout": DEFAULT_HOOK_TIMEOUT,
+            }
+        ]
+    })
+
+    with open(settings_file, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+    return True, f"Successfully installed Guard Stop hook into {settings_file}"
+
+
+def uninstall(repo_path: str | Path | None = None, shared: bool = False) -> tuple[bool, str]:
+    """Uninstalls Guard Stop hook from Claude Code settings.
+    
+    Returns:
+        (success: bool, message: str)
+    """
+    settings_file = get_settings_path(repo_path, shared=shared)
+    if not settings_file.exists():
+        return True, f"Settings file {settings_file} does not exist, nothing to uninstall"
+
+    try:
+        with open(settings_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            if not isinstance(data, dict):
+                return True, "No valid settings found"
+    except Exception as exc:
+        return False, f"Failed to read {settings_file}: {exc}"
+
+    hooks = data.get("hooks", {})
+    if not isinstance(hooks, dict) or "Stop" not in hooks:
+        return True, "No Stop hooks found"
+
+    stop_hooks = hooks["Stop"]
+    if not isinstance(stop_hooks, list):
+        return True, "No Stop hook array found"
+
+    # Backup before modification
+    bak_file = settings_file.with_suffix(settings_file.suffix + ".bak")
+    shutil.copy2(settings_file, bak_file)
+
+    initial_len = len(stop_hooks)
+    hooks["Stop"] = [
+        h for h in stop_hooks
+        if not _contains_guard_hook(h)
+    ]
+
+    if len(hooks["Stop"]) == initial_len:
+        return True, f"Guard Stop hook was not found in {settings_file}"
+
+    with open(settings_file, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+    return True, f"Successfully removed Guard Stop hook from {settings_file}"