guard-cli 0.1.0rc1__tar.gz → 0.1.2__tar.gz

guard_cli-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guard Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{guard_cli-0.1.0rc1/guard_cli.egg-info → guard_cli-0.1.2}/PKG-INFO

@@ -1,37 +1,67 @@
 Metadata-Version: 2.4
 Name: guard-cli
-Version: 0.1.0rc1
+Version: 0.1.2
 Summary: Graph-powered safety layer for AI coding agents built on FalkorDB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thisisvaishnav/guard
+Project-URL: Repository, https://github.com/thisisvaishnav/guard
+Project-URL: Bug Tracker, https://github.com/thisisvaishnav/guard/issues
+Project-URL: Changelog, https://github.com/thisisvaishnav/guard/blob/main/CHANGELOG.md
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: falkordb>=1.0.0
+Requires-Dist: rich>=12.0.0
+Requires-Dist: coverage>=7.0.0
+Provides-Extra: embedded
+Requires-Dist: falkordblite>=0.10.0; python_version >= "3.12" and extra == "embedded"
+Provides-Extra: mcp
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
 Requires-Dist: coverage>=7.0.0; extra == "dev"
+Requires-Dist: rich>=12.0.0; extra == "dev"
+Dynamic: license-file
 
 # Guard: Graph-Powered Safety Layer for AI Coding Agents
 
+[![PyPI version](https://img.shields.io/pypi/v/guard-cli.svg)](https://pypi.org/project/guard-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![FalkorDB](https://img.shields.io/badge/Graph-FalkorDB-red.svg)](https://falkordb.com/)
+
 > **A high-velocity, graph-native regression prevention engine built on FalkorDB.**  
 > Guard selects the exact minimal subset of tests to run after an AI coding agent modifies code, measures a multi-factor **Trust Score**, and deterministically triggers hard fallbacks to full test suites when graph confidence drops.
 
 ---
 
-## 1. Problem Statement & Motivation
+## Quickstart
 
-When AI coding agents (Claude Code, Cursor, Codex, OpenCode) modify complex codebases, running the entire test suite on every step slows iteration cycles to a crawl. Conversely, naive heuristics used by developers or agents to speed things up introduce catastrophic silent escapes:
+### 1. Install Guard
+```bash
+uv tool install guard-cli
+# Or with embedded FalkorDB support on Python 3.12+:
+# uv tool install "guard-cli[embedded]"
+```
 
-- **Same-File Heuristic (`same-file`)**: Only runs tests in the matching test file (e.g., changes in `src/flask/helpers.py` $\to$ run `tests/test_helpers.py`). In real production architectures, foundational helpers, middleware, and lifecycle hooks are heavily exercised across disparate modules (`test_basic.py`, `test_blueprints.py`, `test_templating.py`). On the held-out benchmark, **`same-file` suffered a 17.6% Escape Rate** (3 missed failures).
-- **Agent Guessing (`naive-guess`)**: LLMs predicting test paths based on file names or semantic similarity produce identical blind spots and hallucinate coverage.
-- **Run-All Suite (`run-all`)**: 100% safe, but destroys developer velocity and agent autonomy on non-trivial suites.
+### 2. Initialize in your Repository
+```bash
+cd /path/to/your/repo
+guard init
+```
+`guard init` auto-detects your Python environment, sets up FalkorDB (server, docker, or embedded), ingests static call graphs & dynamic test coverage, and configures agent integrations (Claude Code Stop hook, AGENTS.md, .gitignore).
 
-**Guard's Core Thesis**: Code relationships and test executions form a graph topology. By indexing static AST relationships and per-test dynamic coverage contexts inside **FalkorDB**, Guard computes exact dependency subgraphs, measures empirical test confidence, dynamically widens around ambiguous dynamic dispatch, and enforces hard overrides when evidence is absent.
+### 3. Check System Health
+```bash
+guard doctor
+```
+Verifies backend connectivity, graph integrity, git freshness, and integration settings.
 
 ---
 
-## 2. Verified Benchmark Results (Held-Out Evaluation)
+## Verified Benchmark Results (Held-Out Evaluation)
 
-Guard was evaluated against **`pallets/flask`** (494 tests) across 24 held-out mutants under a frozen protocol (`evals/split.json`, `PLAN.md`). 
+Evaluated against **`pallets/flask`** (494 tests) across 24 held-out mutants under a frozen protocol (`evals/split.json`, `PLAN.md`).
 
 All metrics are evaluated and reported as **Paired Metrics** (Escape Rate $\leftrightarrow$ Fallback Rate $\leftrightarrow$ Savings Ratio):
 
@@ -44,16 +74,28 @@ All metrics are evaluated and reported as **Paired Metrics** (Escape Rate $\left
 | *Ablation 1: `guard-no-confidence`* | 0.0% (0/17) | 77.1% | 20.8% (5/24) | 17 | None |
 | *Ablation 2: `guard-no-widening`* | 0.0% (0/17) | 73.3% | 25.0% (6/24) | 17 | None |
 
-> **Key Result**: Guard achieved a **0.0% Escape Rate** while delivering **67.3% Test-Time Savings** compared to `run-all`, completely eliminating the 17.6% escape rate of `same-file`.
+> **Key Result**: Guard achieved a **0.0% Escape Rate** while delivering **67.3% Test-Time Savings** compared to `run-all`, completely eliminating the 17.6% escape rate of naive heuristics.
 
 ### Case Study: Root Cause of `m08` Escape Under `same-file`
-- **Mutant `m08`** inverted an `if not` statement in `src/flask/helpers.py:45`.
-- `same-file` and `naive-guess` selected `tests/test_helpers.py` (30 tests) $\to$ **0 failures reported (Escape)**.
-- `guard` traversed FalkorDB `COVERED_BY` edges and detected dependent execution paths in `tests/test_basic.py`, `tests/test_blueprints.py`, and `tests/test_templating.py` (26 tests) $\to$ **Caught failure immediately (0.0% escape)**.
+- **Mutant `m08`** inverted an `if not` condition in `src/flask/helpers.py:45`.
+- `same-file` and `naive-guess` selected only `tests/test_helpers.py` (30 tests) $\to$ **0 failures reported (Escape)**.
+- `guard` traversed FalkorDB `COVERED_BY` edges and detected dependent execution paths in `tests/test_basic.py`, `tests/test_blueprints.py`, and `tests/test_templating.py` (26 tests) $\to$ **Caught failure in 0.13s (0.0% escape)**.
 
 ---
 
-## 3. Architecture & System Design
+## Problem Statement & Motivation
+
+When AI coding agents (Claude Code, Cursor, Codex, OpenCode) modify complex codebases, running the entire test suite on every step slows iteration cycles to a crawl. Conversely, naive heuristics introduce catastrophic silent escapes:
+
+- **Same-File Heuristic (`same-file`)**: Only runs tests in the matching test file (e.g., changes in `src/flask/helpers.py` $\to$ run `tests/test_helpers.py`). Foundational helpers, middleware, and lifecycle hooks are heavily exercised across disparate modules (`test_basic.py`, `test_blueprints.py`, `test_templating.py`). On the held-out benchmark, **`same-file` suffered a 17.6% Escape Rate** (3 missed failures).
+- **Agent Guessing (`naive-guess`)**: LLMs predicting test paths based on file names or semantic similarity produce identical blind spots and hallucinate coverage.
+- **Run-All Suite (`run-all`)**: 100% safe, but destroys developer velocity and agent autonomy on non-trivial suites.
+
+**Guard's Core Thesis**: Code relationships and test executions form a graph topology. By indexing static AST relationships and per-test dynamic coverage contexts inside **FalkorDB**, Guard computes exact dependency subgraphs, measures empirical test confidence, dynamically widens around ambiguous dynamic dispatch, and enforces hard overrides when evidence is absent.
+
+---
+
+## Architecture & System Design
 
 Guard operates as a deterministic, graph-native verification pipeline connecting static code structure, dynamic coverage telemetry, and autonomous agent loops:
 
@@ -62,10 +104,37 @@ Guard operates as a deterministic, graph-native verification pipeline connecting
 3. **Decision Engine (`guard.decision`)**: Pre-emptively checks hard safety overrides (uncovered functions, dynamic dispatch, touched tests), computes the multi-factor Trust Score, and routes execution to the appropriate policy level.
 4. **Self-Healing Feedback Loop (`guard.feedback`)**: Injects high-confidence `miss_repair` edges whenever a missed failure is detected, continuously hardening the graph against future escapes.
 
+```
+       +-----------------------+
+       |   AI Agent Git Diff   |
+       +-----------+-----------+
+                   |
+                   v
+       +-----------------------+
+       |   AST Diff Analyzer   | -> Identifies modified functions & test files
+       +-----------+-----------+
+                   |
+                   v
+       +-----------------------+
+       |  FalkorDB Graph Engine| -> Queries COVERED_BY edges, call paths,
+       +-----------+-----------+    and dynamic dispatch topology
+                   |
+                   v
+       +-----------------------+
+       |    Decision Engine    | -> Evaluates hard overrides & Trust Score
+       +-----------+-----------+
+                   |
+         +---------+---------+
+         |                   |
+    Trust >= 0.8        Trust < 0.8 / Override
+         |                   |
+         v                   v
++-----------------+ +-----------------+
+| Targeted Subset | | Full Test Suite |
++-----------------+ +-----------------+
+```
 
-### 3.1. FalkorDB Graph Schema
-
-The graph layer leverages FalkorDB for low-latency Cypher queries and multi-hop graph traversals:
+### FalkorDB Graph Schema
 
 #### Nodes
 - `(:File {path})`: Source files and test files in the repository.
@@ -83,17 +152,17 @@ The graph layer leverages FalkorDB for low-latency Cypher queries and multi-hop
 
 ---
 
-## 4. Decision Engine & Trust Model
+## Decision Engine & Trust Model
 
 Guard evaluates code changes using a strict two-stage process: **Hard Safety Overrides** followed by the **Empirical Trust Score Policy**.
 
-### 4.1. Hard Safety Overrides (Pre-Emptive Gating)
+### 1. Hard Safety Overrides (Pre-Emptive Gating)
 Before computing continuous scores, Guard enforces three non-bypassable guardrails:
-1. **Test Files Touched**: If any test file is modified or added, Guard forces `run-all` with a safety warning (modifying assertions could invalidate test isolation).
+1. **Test Files Touched**: If any test file is modified or added, Guard forces `run-all` with a safety warning.
 2. **Missing Evidence (`no_evidence`)**: If any modified function lacks dynamic coverage evidence in FalkorDB, Guard automatically falls back to `run-all` (never guess when unmapped).
 3. **Dynamic Dispatch Flagged**: If AST analysis flags dynamic dispatch (`getattr`, `setattr`, `eval`, `**kwargs` dispatch), Guard automatically triggers **Dynamic Widening**, expanding the candidate test set to include all module tests.
 
-### 4.2. Trust Score Formula
+### 2. Trust Score Formula
 When no hard overrides force `run-all`, Guard computes the composite trust metric:
 
 $$\text{Trust} = 0.5 \cdot \text{EvidenceRatio} + 0.3 \cdot \text{Freshness} + 0.2 \cdot (1 - \text{UncertainRatio})$$
@@ -102,109 +171,97 @@ $$\text{Trust} = 0.5 \cdot \text{EvidenceRatio} + 0.3 \cdot \text{Freshness} + 0
 - $\text{Freshness}$: Proportion of evidence edges whose `last_verified_sha` matches the current commit SHA.
 - $\text{UncertainRatio}$: Proportion of modified functions flagged with dynamic dispatch patterns.
 
-### 4.3. Three-Level Execution Policy
+### 3. Three-Level Execution Policy
 - **$\text{Trust} \ge 0.8$ (`subset`)**: Execute only the directly covering tests mapped via high-confidence `COVERED_BY` edges.
 - **$0.5 \le \text{Trust} < 0.8$ (`medium`)**: Execute the covering subset plus all tests associated with the modified modules.
 - **$\text{Trust} < 0.5$ (`run-all`)**: Enforce full test suite fallback.
 
 ---
 
-## 5. Self-Healing Feedback Loop
+## Claude Code & Agent Integration
 
-When an unexpected regression or missed test failure occurs:
-1. The failure event is captured via `guard feedback --function <func_id> --test <test_id>`.
-2. Guard writes a synthetic repair edge `(:Function)-[:COVERED_BY {source: 'miss_repair', confidence: 1.0}]->(:Test)`.
-3. The `no_evidence` flag on the function is cleared.
-4. Future decisions for this function or its callers automatically select the repaired test, preventing recurring escapes.
+> **Experimental**: Both the Claude Code Stop hook and the Antigravity integration are
+> labeled **experimental**. The Antigravity `hooks.json` schema was verified against
+> [Antigravity's official hook documentation](https://antigravity.google/docs/hooks), but
+> both integrations have only been validated with simulated stdin/stdout input. A real
+> live session (Claude Code, Antigravity) has not yet confirmed end-to-end behavior.
 
----
+Guard integrates into autonomous coding workflows:
 
-## 6. Installation & Quickstart
+- **Claude Code Stop Hook**: Installed via `guard hook install` into `.claude/settings.local.json`. Whenever Claude attempts to conclude a task, the Stop hook evaluates the diff. If tests fail, it blocks completion (Exit 2) and injects a concise $\le$ 30 line failure report.
+- **Idle-Turn Optimization**: Caches working-tree SHA-256 fingerprints and skips unchanged turns and non-Python diffs.
+- **Loop Guard**: Caps consecutive failures at 3 attempts, handing control back to the user before burning tokens.
+- **Audit Log**: Appends all hook executions, test results, and decisions to `.guard/events.jsonl`.
 
-### Prerequisites
-- Python 3.10+
-- Docker & Docker Compose (for FalkorDB)
+---
 
-### 1. Start FalkorDB
-```bash
-docker compose up -d
-# FalkorDB is live on localhost:6379
-# Web UI is accessible on http://localhost:3000
-```
+## CLI Reference
 
-### 2. Install Guard
+### `guard init`
+Initializes Guard in a repository, detects backends, and configures integrations:
 ```bash
-pip install -e .
-# Or install with dev dependencies:
-pip install -e ".[dev]"
+guard init [--backend server|docker|embedded] [--skip-coverage]
 ```
 
-### 3. Ingest Target Repository
+#### Backends & Platform Support
+
+Guard supports three FalkorDB backend topologies:
+1. **Server (`--backend server`)**: Connects to an existing FalkorDB instance (default: `localhost:6379`). Works across all platforms.
+2. **Docker (`--backend docker`)**: Automatically launches and manages a dedicated `guard-falkordb` container on port 6390. Works on any platform with Docker installed.
+3. **Embedded (`--backend embedded`)**: Zero-configuration, in-process FalkorDBLite instance.
+   - **Supported OS & Platform Requirements**:
+     - **Python**: 3.12 or newer
+     - **Linux**: `glibc` 2.39 or newer (e.g., Ubuntu 24.04+, Fedora 40+)
+     - **macOS**: macOS 15 (Sequoia) or newer
+   - **Platform Fallback**: On unsupported platforms (such as Linux with glibc < 2.39 or macOS < 15), Guard prints a clear message:
+     ```text
+     no embedded build for this platform, use Docker or a server
+     ```
+     and guides you to use `--backend docker` or `--backend server` instead of failing with a build error.
+
+### `guard doctor`
+Verifies system health, backend reachability, graph counts, and settings:
 ```bash
-# 1. Ingest static AST topology into FalkorDB
-guard ingest-static /path/to/target/repo --include-tests
-
-# 2. Ingest per-test coverage contexts (runs pytest with --cov-context=test)
-guard ingest-coverage /path/to/target/repo --runs 3
-
-# 3. View database statistics
-guard stats
+guard doctor [--fix]
 ```
 
----
-
-## 7. CLI Reference
-
 ### `guard run`
 Executes agent pre-completion test verification on the current working tree diff:
 ```bash
-guard run --repo /path/to/target/repo
+guard run [--repo /path/to/repo]
 ```
-*Exits with code 0 on success, or code 1 if tests fail or trust is breached, blocking autonomous agents from committing broken code.*
 
 ### `guard check`
-Computes the test selection decision without executing tests (outputs JSON or human-readable format):
+Computes the test selection decision without executing tests (outputs JSON schema v1.0 or text):
 ```bash
-guard check --repo /path/to/target/repo --json
+guard check [--repo /path/to/repo] [--json]
 ```
 
-### `guard callers`
-Traverses multi-hop static call graph in FalkorDB up to $N$ hops:
+### `guard hook`
+Manages Claude Code and agent hook configurations (experimental — see note above):
 ```bash
-guard callers "src/flask/app.py::Flask.dispatch_request" --hops 4 --min-confidence 0.6
-```
-
-### `guard covering-tests`
-Queries all tests covering a specific function ordered by edge confidence:
-```bash
-guard covering-tests "src/flask/helpers.py::url_for"
+guard hook install [--shared] [--antigravity]
+guard hook status
+guard hook uninstall [--antigravity]
 ```
 
 ### `guard feedback`
-Repairs the graph after a missed failure:
+Repairs the graph after an unexpected failure:
 ```bash
 guard feedback --function "src/flask/helpers.py::url_for" --test "tests/test_helpers.py::test_url_for"
 ```
 
 ---
 
-## 8. Architectural Trade-offs & Limits
-
-### What Graph-Native Architecture Enables
-- **Deterministic Traceability**: Every skipped test has an explicit, queryable reason (`guard check --json` outputs edge justifications for all known tests).
-- **Cross-Module Awareness**: Identifies deep, non-obvious test linkages across package boundaries that escape keyword search or lexical matching.
-- **Fail-Safe Convergence**: Combines static structure with empirical dynamic execution contexts so that gaps trigger defensive full runs rather than silent failures.
+## Documentation & Visualizations
 
-### Known Limits and Edge Cases
-1. **Dynamic Python Metaprogramming**: Heavy dynamic dispatch (`getattr(module, var)()`, custom metaclasses, dynamic decorators) cannot be completely resolved via static AST. *Mitigation*: Guard detects dynamic syntax patterns and triggers dynamic widening or full fallbacks.
-2. **Initial Ingestion Cost**: Generating fine-grained per-test coverage contexts requires an initial baseline run (`pytest --cov-context=test`), which can incur a 1.5x–2.0x slowdown during graph ingestion.
-3. **Ecosystem Scope**: Currently tuned for Python repositories using `pytest`.
+Additional architectural diagrams, interactive visualizations, and test reports are available in the [`docs/`](docs/) directory:
+- [Interactive 3D Flow Architecture](docs/project_flow_3d.html)
+- [Safety Layer Overview](docs/falkordb-safety-layer.html)
+- [Verification Reports](reports/)
 
 ---
 
-## 9. Verification & Quality Invariants
+## License
 
-Guard development adheres to strict engineering rules (`PLAN.md` R1–R9):
-- **Frozen Benchmarks**: Acceptance claims and split files are immutable and verified through independent verifier runs (`reports/verify_t*.md`).
-- **Zero Flake Tolerance**: Flaky tests are detected during ingest runs and excluded from dynamic evidence edges.
-- **Complete Test Coverage**: Pure decision logic, parsers, and graph writers are covered with unit and integration tests under `tests/`.
+MIT License. See [LICENSE](LICENSE) for details.