guard-cli 0.1.0__py3-none-any.whl

guard/cli.py

@@ -0,0 +1,320 @@
+"""Guard CLI.
+
+Commands:
+- `check`: Evaluate proposed changes and select tests.
+- `run`: Execute selected tests according to trust policy.
+- `hook`: Manage and run agent lifecycle hooks (e.g. Claude Code stop hook).
+- `covering-tests`: Show tests covering a function.
+- `callers`: Show multi-hop callers of a function.
+- `feedback`: Record an escape / missed fault for graph repair.
+- `ingest-static`: Ingest static AST call graph into FalkorDB.
+- `ingest-coverage`: Ingest pytest-cov execution traces into FalkorDB.
+- `stats`: Display graph node and relationship counts.
+"""
+from __future__ import annotations
+import argparse
+import json
+import sys
+
+from guard.ingest.static import analyze_repo
+
+
+def cmd_ingest_static(args) -> int:
+    res = analyze_repo(args.repo, include_tests=args.include_tests)
+    print(json.dumps(res.summary(), indent=2))
+    for err in res.parse_errors[:5]:
+        print("parse error:", err, file=sys.stderr)
+    if args.dry_run:
+        return 0
+    from guard import db
+
+    g = db.get_graph(args.graph)
+    db.reset_graph(g)
+    g = db.get_graph(args.graph)
+    db.ensure_schema(g)
+    db.write_static(g, res, commit_sha=args.commit_sha)
+    print(f"written to graph '{args.graph}'")
+    return 0
+
+
+def cmd_callers(args) -> int:
+    from guard import api
+
+    hops = int(args.hops)
+    callers = api.callers(
+        args.function,
+        hops=hops,
+        min_confidence=float(args.min_confidence),
+        graph_name=args.graph,
+        strict=getattr(args, "strict", False),
+    )
+    for c in callers:
+        print(f"{c['hops']}  {c['caller']}")
+    return 0
+
+
+def cmd_stats(args) -> int:
+    from guard import db
+
+    g = db.get_graph(args.graph)
+    counts = db.get_schema_counts(g)
+    print("=== Nodes ===")
+    for label in ("File", "Function", "Test", "Run"):
+        print(f"{label}: {counts.get(label, 0)}")
+    print("\n=== Edges ===")
+    for rel in ("CALLS", "IMPORTS", "DEFINED_IN", "COVERED_BY", "FAILED_IN"):
+        print(f"{rel}: {counts.get(rel, 0)}")
+    print(f"\nDynamic functions: {counts.get('dynamic_functions', 0)}")
+    return 0
+
+
+def cmd_covering_tests(args) -> int:
+    from guard import api
+
+    tests = api.covering_tests(
+        args.function,
+        min_confidence=float(args.min_confidence),
+        graph_name=args.graph,
+        strict=getattr(args, "strict", False),
+    )
+    for t in tests:
+        print(f"[{t['confidence']:.2f}] {t['test_id']} (source: {t['source']})")
+    return 0
+
+
+def cmd_ingest_coverage(args) -> int:
+    from guard.ingest.coverage import ingest_coverage
+
+    res = ingest_coverage(
+        repo_path=args.repo,
+        graph_name=args.graph,
+        commit_sha=args.commit_sha,
+        num_runs=args.runs,
+    )
+    print(json.dumps(res.summary(), indent=2))
+    return 0
+
+
+def cmd_check(args) -> int:
+    from guard import api
+
+    res = api.check(
+        diff_file=args.diff,
+        repo_path=args.repo,
+        graph_name=args.graph,
+        strict=getattr(args, "strict", False),
+    )
+    if args.json:
+        print(json.dumps(res, indent=2))
+    else:
+        print(f"Status: {res['status']}")
+        print(f"Policy: {res['policy']} (Trust: {res['trust']:.2f})")
+        print(f"Fallback: {res['is_fallback']}")
+        if res.get("fallback_reason"):
+            print(f"Reason: {res['fallback_reason']}")
+        if res.get("overrides_triggered"):
+            print(f"Overrides: {', '.join(res['overrides_triggered'])}")
+        print(f"Changed Functions ({len(res.get('changed_functions', []))}): {res.get('changed_functions', [])}")
+        print(f"Selected Tests ({len(res.get('selected_tests', []))}): {res.get('selected_tests', [])}")
+    return 0
+
+
+def cmd_feedback(args) -> int:
+    from guard import api
+
+    res = api.report_miss(
+        function_id=args.function,
+        test_id=args.test,
+        new_confidence=args.confidence,
+        graph_name=args.graph,
+        strict=getattr(args, "strict", False),
+    )
+    if args.json:
+        print(json.dumps(res, indent=2))
+    else:
+        print(f"Repaired: function='{res['function']}' -> test='{res['test']}'")
+        print(f"Confidence: {res.get('old_confidence', 0.0)} -> {res.get('new_confidence', 1.0)} (source: {res.get('source')})")
+    return 0
+
+
+def cmd_run(args) -> int:
+    from guard import api
+
+    report, exit_code = api.run(
+        diff_file=args.diff,
+        repo_path=args.repo,
+        graph_name=args.graph,
+        strict=getattr(args, "strict", False),
+    )
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"Status: {report['status']}")
+        print(f"Policy: {report['policy']} (Trust: {report['trust']:.2f})")
+        print(f"Forced Full Suite: {report.get('forced_full', False)}")
+        if report.get("fallback_reason"):
+            print(f"Fallback Reason: {report['fallback_reason']}")
+        print(f"Tests Run ({report.get('tests_run_count', 0)}): {report.get('tests_run', [])}")
+        print(f"Passed: {report.get('tests_passed', False)} in {report.get('duration_s', 0.0)}s")
+        if report.get("failures"):
+            print(f"Failures ({len(report['failures'])}): {report['failures']}")
+        if report.get("output_summary"):
+            print(f"Summary: {report['output_summary']}")
+    return exit_code
+
+
+def cmd_hook_stop(args) -> int:
+    from guard.hook import run_stop_hook
+    return run_stop_hook(
+        repo_override=args.repo,
+        strict=getattr(args, "strict", False),
+    )
+
+
+def cmd_hook_install(args) -> int:
+    from guard.integrations import claude
+    ok, msg = claude.install(repo_path=args.repo, shared=args.shared)
+    print(msg)
+    return 0 if ok else 1
+
+
+def cmd_hook_uninstall(args) -> int:
+    from guard.integrations import claude
+    ok, msg = claude.uninstall(repo_path=args.repo, shared=args.shared)
+    print(msg)
+    return 0 if ok else 1
+
+
+def cmd_hook_status(args) -> int:
+    from guard.integrations import claude
+    stat = claude.status(repo_path=args.repo, shared=args.shared)
+    print(json.dumps(stat, indent=2))
+    return 0
+
+
+def cmd_init(args) -> int:
+    from guard.init_cmd import run_init
+
+    return run_init(
+        repo_path=getattr(args, "repo", None),
+        backend_preference=getattr(args, "backend", None),
+        skip_coverage=getattr(args, "skip_coverage", False),
+        auto_yes=getattr(args, "yes", False),
+        agents=getattr(args, "agents", "claude,cursor,codex"),
+        runs=getattr(args, "runs", None),
+    )
+
+
+def cmd_doctor(args) -> int:
+    from guard.doctor_cmd import run_doctor
+
+    return run_doctor(
+        repo_path=getattr(args, "repo", None),
+        json_mode=getattr(args, "json", False),
+        fix_mode=getattr(args, "fix", False),
+    )
+
+
+def main(argv=None) -> int:
+    import guard
+
+    p = argparse.ArgumentParser(prog="guard")
+    p.add_argument("-v", "--version", action="version", version=f"guard {guard.__version__}")
+    p.add_argument("--graph", default="guard")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    ini = sub.add_parser("init", help="Initialize Guard for repository")
+    ini.add_argument("repo", nargs="?", default=None, help="target repository path (default: current directory)")
+    ini.add_argument("--backend", choices=["server", "docker", "embedded"], default=None, help="database backend")
+    ini.add_argument("--skip-coverage", action="store_true", help="skip per-test coverage ingestion")
+    ini.add_argument("-y", "--yes", action="store_true", help="non-interactive mode accepting all defaults")
+    ini.add_argument("--agents", default="claude,cursor,codex", help="comma-separated agents to configure")
+    ini.add_argument("--runs", type=int, default=None, help="number of baseline test runs (1 or 3)")
+    ini.set_defaults(fn=cmd_init)
+
+    doc = sub.add_parser("doctor", help="Check Guard system health and diagnostics")
+    doc.add_argument("repo", nargs="?", default=None, help="target repository path (default: current directory)")
+    doc.add_argument("--json", action="store_true", help="output structured JSON")
+    doc.add_argument("--fix", action="store_true", help="attempt automated repairs for warnings/failures")
+    doc.set_defaults(fn=cmd_doctor)
+
+    rn = sub.add_parser("run")
+    rn.add_argument("--diff", default=None, help="path to unified diff file")
+    rn.add_argument("--repo", default=None, help="path to target repo")
+    rn.add_argument("--json", action="store_true", help="output JSON")
+    rn.add_argument("--strict", action="store_true", help="fail closed on guard error")
+    rn.set_defaults(fn=cmd_run)
+
+    chk = sub.add_parser("check")
+    chk.add_argument("--diff", default=None, help="path to unified diff file")
+    chk.add_argument("--repo", default=None, help="path to repo to run git diff HEAD")
+    chk.add_argument("--json", action="store_true", help="output JSON")
+    chk.add_argument("--strict", action="store_true", help="fail closed on guard error")
+    chk.set_defaults(fn=cmd_check)
+
+    hk = sub.add_parser("hook", help="Agent hook management")
+    hk_sub = hk.add_subparsers(dest="hook_cmd", required=True)
+
+    hk_stop = hk_sub.add_parser("stop", help="Run Claude Code Stop hook adapter")
+    hk_stop.add_argument("--repo", default=None, help="path to repo root")
+    hk_stop.add_argument("--strict", action="store_true", help="fail closed on error")
+    hk_stop.set_defaults(fn=cmd_hook_stop)
+
+    hk_inst = hk_sub.add_parser("install", help="Install Stop hook into Claude Code settings")
+    hk_inst.add_argument("--repo", default=None, help="path to repo root")
+    hk_inst.add_argument("--shared", action="store_true", help="install to settings.json instead of settings.local.json")
+    hk_inst.set_defaults(fn=cmd_hook_install)
+
+    hk_uninst = hk_sub.add_parser("uninstall", help="Uninstall Stop hook from Claude Code settings")
+    hk_uninst.add_argument("--repo", default=None, help="path to repo root")
+    hk_uninst.add_argument("--shared", action="store_true", help="uninstall from settings.json instead of settings.local.json")
+    hk_uninst.set_defaults(fn=cmd_hook_uninstall)
+
+    hk_stat = hk_sub.add_parser("status", help="Check Claude Code hook installation status")
+    hk_stat.add_argument("--repo", default=None, help="path to repo root")
+    hk_stat.add_argument("--shared", action="store_true", help="check settings.json instead of settings.local.json")
+    hk_stat.set_defaults(fn=cmd_hook_status)
+
+    fb = sub.add_parser("feedback")
+    fb.add_argument("--function", required=True, help="Function ID where fault was missed")
+    fb.add_argument("--test", required=True, help="Test ID that failed and was missed")
+    fb.add_argument("--confidence", default=1.0, type=float, help="Confidence of repair edge (default: 1.0)")
+    fb.add_argument("--json", action="store_true", help="output JSON")
+    fb.add_argument("--strict", action="store_true", help="fail closed on guard error")
+    fb.set_defaults(fn=cmd_feedback)
+
+    s = sub.add_parser("ingest-static")
+    s.add_argument("repo")
+    s.add_argument("--dry-run", action="store_true", help="parse only, no database")
+    s.add_argument("--include-tests", action="store_true")
+    s.add_argument("--commit-sha", default=None, help="commit SHA to associate with edges")
+    s.set_defaults(fn=cmd_ingest_static)
+
+    ic = sub.add_parser("ingest-coverage")
+    ic.add_argument("repo")
+    ic.add_argument("--runs", default=3, type=int, help="number of test runs for flake measurement")
+    ic.add_argument("--commit-sha", default=None, help="commit SHA to associate with edges")
+    ic.set_defaults(fn=cmd_ingest_coverage)
+
+    c = sub.add_parser("callers")
+    c.add_argument("function", help="function id, e.g. pkg/mod.py::Class.method")
+    c.add_argument("--hops", default=4, type=int)
+    c.add_argument("--min-confidence", default=0.0, type=float)
+    c.add_argument("--strict", action="store_true", help="fail closed on error")
+    c.set_defaults(fn=cmd_callers)
+
+    st = sub.add_parser("stats")
+    st.set_defaults(fn=cmd_stats)
+
+    cov = sub.add_parser("covering-tests")
+    cov.add_argument("function", help="function id, e.g. pkg/mod.py::Class.method")
+    cov.add_argument("--min-confidence", default=0.0, type=float)
+    cov.add_argument("--strict", action="store_true", help="fail closed on error")
+    cov.set_defaults(fn=cmd_covering_tests)
+
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

guard/db.py

@@ -0,0 +1,271 @@
+"""FalkorDB connection, complete schema, and batched writers for Guard (Task T2)."""
+from __future__ import annotations
+import os
+from typing import Any, Iterable, Sequence
+from falkordb import FalkorDB
+
+GRAPH_NAME = os.getenv("GUARD_GRAPH", "guard")
+
+INDEXES = [
+    "CREATE INDEX FOR (f:Function) ON (f.id)",
+    "CREATE INDEX FOR (t:Test) ON (t.id)",
+    "CREATE INDEX FOR (x:File) ON (x.path)",
+    "CREATE INDEX FOR (r:Run) ON (r.id)",
+]
+
+
+_active_backend: Any = None
+
+
+def set_backend(backend: Any) -> None:
+    """Explicitly set active GraphBackend instance."""
+    global _active_backend
+    _active_backend = backend
+
+
+def get_backend(repo_path: Any = None) -> Any:
+    """Return active or resolved GraphBackend."""
+    global _active_backend
+    if _active_backend is not None:
+        return _active_backend
+    from guard.backend import resolve_backend, ServerBackend
+
+    if "FALKORDB_HOST" in os.environ or "FALKORDB_PORT" in os.environ:
+        host = os.getenv("FALKORDB_HOST", "localhost")
+        port = int(os.getenv("FALKORDB_PORT", "6379"))
+        return ServerBackend(host=host, port=port)
+    return resolve_backend(repo_path=repo_path)
+
+
+def get_graph(
+    name: str | None = None,
+    backend: Any = None,
+    repo_path: Any = None,
+):
+    """Retrieve FalkorDB graph using resolved backend and repository name."""
+    if backend is None:
+        backend = get_backend(repo_path=repo_path)
+    if name is None:
+        name = os.getenv("GUARD_GRAPH", GRAPH_NAME)
+    return backend.get_graph(name)
+
+
+def reset_graph(g) -> None:
+    try:
+        g.delete()
+    except Exception:
+        pass  # graph did not exist yet
+
+
+def ensure_schema(g) -> None:
+    for q in INDEXES:
+        try:
+            g.query(q)
+        except Exception:
+            pass  # index already exists
+
+
+def _batches(rows: Sequence[Any], size: int = 500) -> Iterable[Sequence[Any]]:
+    for i in range(0, len(rows), size):
+        yield rows[i : i + size]
+
+
+def write_static(g, result, commit_sha: str | None = None) -> None:
+    """Write StaticResult nodes and edges into FalkorDB with T2 schema requirements."""
+    # 1. File nodes
+    for b in _batches(result.file_rows()):
+        g.query("UNWIND $rows AS r MERGE (x:File {path: r.path})", {"rows": b})
+
+    # 2. Function nodes & DEFINED_IN edges
+    for b in _batches(result.function_rows()):
+        g.query(
+            """UNWIND $rows AS r
+               MERGE (f:Function {id: r.id})
+               SET f.file = r.file, f.name = r.name, f.qualname = r.qualname,
+                   f.start = r.start, f.end = r.end,
+                   f.has_dynamic_dispatch = r.dyn
+               WITH f, r
+               MATCH (x:File {path: r.file})
+               MERGE (f)-[:DEFINED_IN]->(x)""",
+            {"rows": b},
+        )
+
+    # 3. Test nodes & DEFINED_IN edges
+    if hasattr(result, "test_rows"):
+        test_rows = result.test_rows()
+    else:
+        test_rows = []
+
+    for b in _batches(test_rows):
+        g.query(
+            """UNWIND $rows AS r
+               MERGE (t:Test {id: r.id})
+               SET t.file = r.file, t.name = r.name, t.qualname = r.qualname,
+                   t.start = r.start, t.end = r.end
+               WITH t, r
+               MATCH (x:File {path: r.file})
+               MERGE (t)-[:DEFINED_IN]->(x)""",
+            {"rows": b},
+        )
+
+    # 4. CALLS edges (Function -> Function)
+    for b in _batches(result.call_rows()):
+        g.query(
+            """UNWIND $rows AS r
+               MATCH (a:Function {id: r.src}), (b:Function {id: r.dst})
+               MERGE (a)-[e:CALLS]->(b)
+               SET e.source = 'static',
+                   e.confidence = 0.6,
+                   e.evidence_count = coalesce(e.evidence_count, 0),
+                   e.last_verified_sha = $sha""",
+            {"rows": b, "sha": commit_sha},
+        )
+
+    # 5. IMPORTS edges (File -> File)
+    for b in _batches(result.import_rows()):
+        g.query(
+            """UNWIND $rows AS r
+               MATCH (a:File {path: r.src}), (b:File {path: r.dst})
+               MERGE (a)-[e:IMPORTS]->(b)
+               SET e.source = 'static',
+                   e.confidence = 0.6,
+                   e.last_verified_sha = $sha""",
+            {"rows": b, "sha": commit_sha},
+        )
+
+
+def write_coverage(
+    g,
+    test_to_funcs: dict[str, list[str]] | list[dict[str, str]],
+    commit_sha: str | None = None,
+    confidence: float = 0.9,
+) -> int:
+    """Write COVERED_BY edges from Function to Test nodes.
+
+    Args:
+        test_to_funcs: Mapping test_id -> list of function_ids, or list of {'test': id, 'func': id}
+        commit_sha: Commit SHA when coverage was verified
+        confidence: Confidence score (default 0.9 for dynamic coverage evidence)
+
+    Returns:
+        Number of coverage pairs written
+    """
+    if isinstance(test_to_funcs, dict):
+        pairs = [
+            {"test": t_id, "func": f_id}
+            for t_id, funcs in test_to_funcs.items()
+            for f_id in funcs
+        ]
+    else:
+        pairs = list(test_to_funcs)
+
+    for b in _batches(pairs):
+        g.query(
+            """UNWIND $rows AS r
+               MATCH (f:Function {id: r.func}), (t:Test {id: r.test})
+               MERGE (f)-[e:COVERED_BY]->(t)
+               SET e.source = 'coverage',
+                   e.confidence = $conf,
+                   e.evidence_count = coalesce(e.evidence_count, 0) + 1,
+                   e.last_verified_sha = $sha""",
+            {"rows": b, "conf": confidence, "sha": commit_sha},
+        )
+    return len(pairs)
+
+
+def write_run(
+    g,
+    run_data: dict[str, Any],
+    failures: list[dict[str, Any]] | None = None,
+) -> None:
+    """Write a Run node and optional FAILED_IN edges.
+
+    Args:
+        run_data: Dict with keys: id, timestamp, commit_sha, duration_ms, total_tests, passed, failed
+        failures: List of dicts: {'test_id': str, 'error': str}
+    """
+    g.query(
+        """MERGE (r:Run {id: $r.id})
+           SET r.timestamp = $r.timestamp,
+               r.commit_sha = $r.commit_sha,
+               r.duration_ms = $r.duration_ms,
+               r.total_tests = $r.total_tests,
+               r.passed = $r.passed,
+               r.failed = $r.failed""",
+        {"r": run_data},
+    )
+
+    if failures:
+        for b in _batches(failures):
+            g.query(
+                """UNWIND $rows AS f
+                   MATCH (t:Test {id: f.test_id}), (r:Run {id: $run_id})
+                   MERGE (t)-[e:FAILED_IN]->(r)
+                   SET e.source = 'test_run',
+                       e.error_message = f.error,
+                       e.commit_sha = $sha""",
+                {
+                    "rows": b,
+                    "run_id": run_data["id"],
+                    "sha": run_data.get("commit_sha"),
+                },
+            )
+
+
+def get_schema_counts(g) -> dict[str, int]:
+    """Return dictionary with counts of all nodes and relationships."""
+    counts = {}
+    for label in ("File", "Function", "Test", "Run"):
+        try:
+            res = g.query(f"MATCH (n:{label}) RETURN count(n)").result_set
+            counts[label] = res[0][0] if res else 0
+        except Exception:
+            counts[label] = 0
+
+    for rel in ("CALLS", "IMPORTS", "DEFINED_IN", "COVERED_BY", "FAILED_IN"):
+        try:
+            res = g.query(f"MATCH ()-[e:{rel}]->() RETURN count(e)").result_set
+            counts[rel] = res[0][0] if res else 0
+        except Exception:
+            counts[rel] = 0
+
+    try:
+        res = g.query(
+            "MATCH (f:Function {has_dynamic_dispatch: true}) RETURN count(f)"
+        ).result_set
+        counts["dynamic_functions"] = res[0][0] if res else 0
+    except Exception:
+        counts["dynamic_functions"] = 0
+
+    return counts
+
+
+def get_callers(
+    g, function_id: str, hops: int = 4, min_confidence: float = 0.0
+) -> list[dict[str, Any]]:
+    """Traverse inbound CALLS edges up to N hops filtered by min_confidence."""
+    q = (
+        f"MATCH p=(caller:Function)-[:CALLS*1..{hops}]->(target:Function {{id: $id}}) "
+        "WHERE all(e IN relationships(p) WHERE coalesce(e.confidence, 0.6) >= $min_conf) "
+        "RETURN caller.id AS caller, min(length(p)) AS hops "
+        "ORDER BY hops, caller"
+    )
+    res = g.query(q, {"id": function_id, "min_conf": min_confidence}).result_set
+    return [{"caller": row[0], "hops": row[1]} for row in res]
+
+
+def get_covering_tests(
+    g, function_id: str, min_confidence: float = 0.0
+) -> list[dict[str, Any]]:
+    """Find tests covering a given function, ordered by confidence."""
+    q = (
+        "MATCH (f:Function {id: $id})-[e:COVERED_BY]->(t:Test) "
+        "WHERE e.confidence >= $min_conf "
+        "RETURN t.id AS test_id, e.confidence AS confidence, e.source AS source "
+        "ORDER BY confidence DESC"
+    )
+    res = g.query(q, {"id": function_id, "min_conf": min_confidence}).result_set
+    return [
+        {"test_id": row[0], "confidence": row[1], "source": row[2]}
+        for row in res
+    ]