guard-cli 0.1.0rc1__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,119 @@
+"""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) -> bool:
+    """Applies patch to target repo."""
+    proc = subprocess.run(["git", "apply", str(diff_file)], cwd=str(REPO_ROOT), capture_output=True, text=True)
+    if proc.returncode != 0:
+        patch_proc = subprocess.run(["patch", "-p1", "-i", str(diff_file)], cwd=str(REPO_ROOT), capture_output=True)
+        return patch_proc.returncode == 0
+    return True
+
+
+def reset_repo():
+    """Restores target repo to clean state."""
+    subprocess.run(["git", "checkout", "--", "."], cwd=str(REPO_ROOT), capture_output=True)
+    subprocess.run(["git", "clean", "-fdx"], cwd=str(REPO_ROOT), capture_output=True)
+
+
+def count_collected_tests(test_targets: list[str]) -> int:
+    """Counts how many test items are collected for the targets."""
+    cmd = [sys.executable, "-m", "pytest", "--collect-only", "-q"] + test_targets
+    proc = subprocess.run(cmd, cwd=str(REPO_ROOT), 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/cli.py

@@ -0,0 +1,194 @@
+"""Guard CLI. Commands: ingest-static, callers, stats, covering-tests."""
+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 db
+
+    g = db.get_graph(args.graph)
+    hops = int(args.hops)
+    callers = db.get_callers(g, args.function, hops=hops, min_confidence=float(args.min_confidence))
+    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 db
+
+    g = db.get_graph(args.graph)
+    tests = db.get_covering_tests(g, args.function, min_confidence=float(args.min_confidence))
+    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.thin_slice import guard_check
+
+    res = guard_check(
+        diff_file=args.diff,
+        repo_path=args.repo,
+        graph_name=args.graph,
+    )
+    if args.json:
+        print(json.dumps(res.to_dict(), indent=2))
+    else:
+        print(f"Status: {res.status}")
+        print(f"Fallback: {res.is_fallback}")
+        if res.fallback_reason:
+            print(f"Reason: {res.fallback_reason}")
+        print(f"Changed Functions ({len(res.changed_functions)}): {res.changed_functions}")
+        print(f"Selected Tests ({len(res.selected_tests)}): {res.selected_tests}")
+    return 0
+
+
+def cmd_feedback(args) -> int:
+    from guard import db
+    from guard.feedback import record_miss
+
+    g = db.get_graph(args.graph)
+    res = record_miss(
+        g,
+        function_id=args.function,
+        test_id=args.test,
+        new_confidence=args.confidence,
+    )
+    if args.json:
+        print(json.dumps(res, indent=2))
+    else:
+        print(f"Repaired: function='{res['function']}' -> test='{res['test']}'")
+        print(f"Confidence: {res['old_confidence']} -> {res['new_confidence']} (source: {res['source']})")
+    return 0
+
+
+def cmd_run(args) -> int:
+    from guard.agent_integration import run_agent_guard
+
+    report, exit_code = run_agent_guard(
+        diff_file=args.diff,
+        repo_path=args.repo,
+        graph_name=args.graph,
+    )
+    if args.json:
+        print(json.dumps(report, indent=2))
+    else:
+        print(f"Status: {report['status']}")
+        print(f"Forced Full Suite: {report['forced_full']}")
+        if report['fallback_reason']:
+            print(f"Fallback Reason: {report['fallback_reason']}")
+        print(f"Tests Run ({report['tests_run_count']}): {report['tests_run']}")
+        print(f"Passed: {report['tests_passed']} in {report['duration_s']}s")
+        if report['output_summary']:
+            print(f"Summary: {report['output_summary']}")
+    return exit_code
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="guard")
+    p.add_argument("--graph", default="guard")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    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.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.set_defaults(fn=cmd_check)
+
+    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.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.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.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,243 @@
+"""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)",
+]
+
+
+def get_graph(name: str = GRAPH_NAME):
+    db = FalkorDB(
+        host=os.getenv("FALKORDB_HOST", "localhost"),
+        port=int(os.getenv("FALKORDB_PORT", "6379")),
+    )
+    return db.select_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
+    ]