honestcode 0.5.0__py3-none-any.whl

honestcode/graph/graph_store.py

@@ -0,0 +1,276 @@
+"""Persistent call-graph and full-text search index backed by SQLite.
+
+``GraphCache`` persists the project-wide call graph (definitions + references)
+to a SQLite database keyed by a stable hash of the project root. Freshness is
+decided by comparing stored ``(mtime_ns, size)`` metadata for every ``.py``
+file against the current tree, so graph queries (``explore_call_graph``,
+``find_dead_code``, ``impact``, ``affected``) read from disk instead of
+re-parsing the project on every call. Metadata rather than content hashing:
+hashing the whole tree on every query made the read-only graph tools pay a
+full-tree read, and the same-file-rewritten-within-one-mtime-tick case it would
+catch is not worth that cost.
+
+The same database hosts a FTS5 virtual table (trigram tokenizer) over file
+contents. ``search_code`` uses it to shrink a regex scan to a *superset* of
+candidate files: it extracts a literal substring the pattern requires and
+matches it as a substring, so even matches inside longer tokens are found —
+a plain token-prefix index would have missed those. When no required literal
+can be derived (or FTS5 is unavailable), the caller falls back to a full scan,
+keeping results identical to an unindexed search in all cases.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from honestcode.structure.utils import iter_python_files, prune_cache_files, read_python_source
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["CallGraph", "GraphCache"]
+
+# v2 replaced whole-tree content hashes with (mtime_ns, size) metadata.
+_DB_VERSION = 2
+
+# ``<root name>_<16 hex chars>.graph.db`` — narrow on purpose so pruning a
+# user-supplied cache directory cannot delete unrelated SQLite files.
+_GRAPH_CACHE_GLOB = "*_" + "[0-9a-f]" * 16 + ".graph.db"
+
+
+@dataclass
+class CallGraph:
+    """Project-wide definition/reference graph.
+
+    ``definitions`` maps a symbol name to ``(file, line, end_line, kind)``.
+    ``references``  maps a symbol name to ``(file, line, kind, context)`` where
+    ``context`` is the callee when the reference is a call site (else ``None``).
+    """
+
+    definitions: dict[str, list[tuple[Path, int, int, str]]] = field(default_factory=dict)
+    references: dict[str, list[tuple[Path, int, str, str | None]]] = field(default_factory=dict)
+
+
+def _python_files(root: Path) -> list[Path]:
+    return list(iter_python_files(root))
+
+
+def _file_stats(root: Path) -> dict[str, list[int]]:
+    """Map each relative .py path to ``[mtime_ns, size]``."""
+    stats: dict[str, list[int]] = {}
+    for p in _python_files(root):
+        try:
+            st = p.stat()
+        except OSError:
+            continue
+        stats[p.relative_to(root).as_posix()] = [st.st_mtime_ns, st.st_size]
+    return stats
+
+
+def _stable_hash(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()[:16]
+
+
+class GraphCache:
+    """SQLite-backed cache of a project's call graph + FTS5 file index."""
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    @classmethod
+    def for_root(cls, root: Path, cache_dir: Path) -> GraphCache:
+        resolved = root.resolve()
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        return cls(cache_dir / f"{resolved.name}_{_stable_hash(str(resolved))}.graph.db")
+
+    # -- freshness ---------------------------------------------------------
+
+    def is_fresh(self, root: Path) -> bool:
+        """True when the cached graph covers exactly the current file tree."""
+        if not self.path.exists():
+            return False
+        conn = None
+        try:
+            conn = sqlite3.connect(str(self.path))
+            cur = conn.cursor()
+            row = cur.execute("SELECT value FROM meta WHERE key='stats'").fetchone()
+            root_row = cur.execute("SELECT value FROM meta WHERE key='root'").fetchone()
+            version_row = cur.execute("SELECT value FROM meta WHERE key='version'").fetchone()
+        except sqlite3.Error:
+            return False
+        finally:
+            if conn is not None:
+                conn.close()
+        if row is None or root_row is None or version_row is None:
+            return False
+        if version_row[0] != str(_DB_VERSION):
+            return False
+        if root_row[0] != str(root.resolve()):
+            return False
+        try:
+            stored = json.loads(row[0])
+        except (json.JSONDecodeError, TypeError):
+            return False
+        return stored == _file_stats(root)
+
+    # -- persistence -------------------------------------------------------
+
+    def save(self, graph: CallGraph, root: Path) -> None:
+        """Persist the graph plus a FTS5 index of the current file tree."""
+        root = root.resolve()
+        stats = _file_stats(root)
+        files = sorted(stats.keys())
+        conn = sqlite3.connect(str(self.path))
+        try:
+            conn.execute("DROP TABLE IF EXISTS definitions")
+            conn.execute("DROP TABLE IF EXISTS refs")
+            conn.execute("DROP TABLE IF EXISTS meta")
+            conn.execute(
+                "CREATE TABLE definitions ("
+                "symbol TEXT NOT NULL, file TEXT NOT NULL, "
+                "line INTEGER NOT NULL, end_line INTEGER NOT NULL, kind TEXT NOT NULL)"
+            )
+            conn.execute(
+                "CREATE TABLE refs ("
+                "caller TEXT NOT NULL, file TEXT NOT NULL, "
+                "line INTEGER NOT NULL, kind TEXT NOT NULL, context TEXT)"
+            )
+            conn.executemany(
+                "INSERT INTO definitions VALUES (?, ?, ?, ?, ?)",
+                [
+                    (name, str(p), line, end_line, kind)
+                    for name, locs in graph.definitions.items()
+                    for p, line, end_line, kind in locs
+                ],
+            )
+            conn.executemany(
+                "INSERT INTO refs VALUES (?, ?, ?, ?, ?)",
+                [
+                    (name, str(p), line, kind, context)
+                    for name, locs in graph.references.items()
+                    for p, line, kind, context in locs
+                ],
+            )
+            conn.execute("CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT)")
+            conn.executemany(
+                "INSERT INTO meta VALUES (?, ?)",
+                [
+                    ("version", str(_DB_VERSION)),
+                    ("root", str(root)),
+                    ("files", json.dumps(files)),
+                    ("stats", json.dumps(stats)),
+                ],
+            )
+            conn.commit()
+            self._rebuild_fts(conn, root, files)
+        finally:
+            conn.close()
+        prune_cache_files(self.path.parent, (_GRAPH_CACHE_GLOB,))
+
+    def load(self) -> CallGraph | None:
+        """Load the graph from disk, or ``None`` if missing/corrupt."""
+        if not self.path.exists():
+            return None
+        try:
+            conn = sqlite3.connect(str(self.path))
+            cur = conn.cursor()
+            definitions: dict[str, list[tuple[Path, int, int, str]]] = {}
+            for name, f, line, end_line, kind in cur.execute(
+                "SELECT symbol, file, line, end_line, kind FROM definitions"
+            ):
+                definitions.setdefault(name, []).append((Path(f), line, end_line, kind))
+            references: dict[str, list[tuple[Path, int, str, str | None]]] = {}
+            for name, f, line, kind, context in cur.execute(
+                "SELECT caller, file, line, kind, context FROM refs"
+            ):
+                references.setdefault(name, []).append((Path(f), line, kind, context))
+            conn.close()
+            return CallGraph(definitions=definitions, references=references)
+        except sqlite3.Error as exc:
+            logger.warning("Failed to load graph cache %s: %s", self.path, exc)
+            return None
+
+    # -- FTS5 full-text search --------------------------------------------
+
+    def _rebuild_fts(self, conn: sqlite3.Connection, root: Path, files: list[str]) -> None:
+        try:
+            conn.execute("DROP TABLE IF EXISTS fts_files")
+            conn.execute(
+                "CREATE VIRTUAL TABLE fts_files USING fts5("
+                "path UNINDEXED, content, tokenize='trigram')"
+            )
+        except sqlite3.Error:
+            logger.debug("FTS5 unavailable; search_code will fall back to regex scans")
+            return
+        for rel in files:
+            content = read_python_source(root / rel)
+            if content is None:
+                continue
+            conn.execute("INSERT INTO fts_files (path, content) VALUES (?, ?)", (rel, content))
+        conn.commit()
+
+    @staticmethod
+    def _required_literal(pattern: str) -> str | None:
+        """Return a literal substring every match of *pattern* must contain.
+
+        Conservative by design: a maximal ``[A-Za-z0-9_]+`` run counts only
+        when both neighbours are plain literal characters (alphanumeric,
+        underscore, space, or a string boundary). Anything else — a quantifier
+        after the run (``foo*`` can match ``fo``), an alternation, an escaped
+        metachar before it — disqualifies the run, because guessing wrong here
+        would silently drop real matches.
+
+        Returns ``None`` when no run of >= 3 characters qualifies (the trigram
+        index cannot help below three characters).
+        """
+        literal_chars = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ ")
+        best = ""
+        n = len(pattern)
+        i = 0
+        while i < n:
+            if pattern[i] not in literal_chars or pattern[i] == " ":
+                i += 1
+                continue
+            j = i
+            while j < n and pattern[j] in literal_chars and pattern[j] != " ":
+                j += 1
+            before_ok = i == 0 or pattern[i - 1] in (" ",)
+            after_ok = j == n or pattern[j] in (" ",)
+            if before_ok and after_ok and (j - i) > len(best):
+                best = pattern[i:j]
+            i = j
+        return best if len(best) >= 3 else None
+
+    def search_candidate_files(self, pattern: str) -> list[str] | None:
+        """Return files that *may* match ``pattern`` using FTS5 substring search.
+
+        Uses the trigram index to find files containing the literal substring
+        that :meth:`_required_literal` proved the pattern requires. Because the
+        match is substring-based (not token-prefix), occurrences inside longer
+        tokens are still found and the candidate set is a true superset; when
+        no required literal can be derived, ``None`` tells the caller to fall
+        back to a full scan. Returns an empty list when the required literal
+        occurs nowhere (short-circuit to no results).
+        """
+        literal = self._required_literal(pattern)
+        if literal is None:
+            return None
+        try:
+            conn = sqlite3.connect(str(self.path))
+            try:
+                cur = conn.cursor()
+                paths: list[str] = []
+                for (path,) in cur.execute(
+                    "SELECT path FROM fts_files WHERE fts_files MATCH ?",
+                    (f'"{literal}"',),
+                ):
+                    paths.append(path)
+            finally:
+                conn.close()
+        except sqlite3.Error:
+            return None
+        return sorted(set(paths))

honestcode/graph/watcher.py

@@ -0,0 +1,116 @@
+"""Zero-dependency file watcher for automatic re-indexing.
+
+Polls the source tree's ``.py`` file mtimes on a background thread and fires
+an ``on_change`` callback once files have stayed unchanged for ``debounce``
+seconds. A poll-based design keeps the project dependency-free (pure stdlib),
+cross-platform, and good enough for local dev machines — a single project of a
+few thousand files is fully rescanned in well under a second.
+
+Usage::
+
+    watcher = ProjectWatcher(root, on_change=lambda changed: ...)
+    watcher.start()
+    ...
+    watcher.stop()
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from pathlib import Path
+
+from honestcode.structure.utils import iter_python_files
+
+logger = logging.getLogger(__name__)
+
+
+def _take_snapshot(root: Path) -> dict[Path, float]:
+    """Map each .py file to its mtime (ns), for change detection."""
+    snap: dict[Path, float] = {}
+    for p in iter_python_files(root):
+        try:
+            snap[p] = p.stat().st_mtime_ns
+        except OSError:
+            continue
+    return snap
+
+
+class ProjectWatcher:
+    """Watch a project for source changes and fire a debounced callback.
+
+    ``on_change(changed: list[Path])`` is invoked on the watcher thread once
+    the tree is quiescent for ``debounce`` seconds. The callback must be quick
+    or move heavy work to its own thread.
+    """
+
+    def __init__(
+        self,
+        root: Path,
+        on_change,
+        debounce: float = 2.0,
+        poll_interval: float = 0.5,
+        name: str = "honestcode-watcher",
+    ) -> None:
+        self.root = Path(root)
+        self.on_change = on_change
+        self.debounce = debounce
+        self.poll_interval = poll_interval
+        self._snapshot = _take_snapshot(self.root)
+        self._pending: list[Path] = []
+        self._last_change: float | None = None
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name=name, daemon=True)
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def start(self) -> ProjectWatcher:
+        self._thread.start()
+        logger.info("Watcher started for %s (debounce %.1fs)", self.root, self.debounce)
+        return self
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=5)
+        if self._thread.is_alive():
+            logger.warning("Watcher thread for %s did not stop within 5s", self.root)
+        else:
+            logger.info("Watcher stopped for %s", self.root)
+
+    # -- internals ---------------------------------------------------------
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self._stop.wait(self.poll_interval)
+            self._scan_once()
+
+    def _scan_once(self) -> None:
+        now = _take_snapshot(self.root)
+        changed: list[Path] = []
+        old = self._snapshot
+        for p in old:
+            if p not in now:
+                changed.append(p)
+        for p, mtime in now.items():
+            if old.get(p) != mtime:
+                changed.append(p)
+        self._snapshot = now
+
+        if changed:
+            self._pending.extend(changed)
+            self._last_change = time.monotonic()
+            logger.debug("Detected %d changed files", len(changed))
+            return
+
+        if (
+            self._pending
+            and self._last_change is not None
+            and (time.monotonic() - self._last_change) >= self.debounce
+        ):
+            pending, self._pending = self._pending, []
+            self._last_change = None
+            try:
+                self.on_change(pending)
+            except Exception:  # noqa: BLE001
+                logger.exception("on_change callback failed")

honestcode/guards/__init__.py

@@ -0,0 +1,104 @@
+"""Crash-safe wrappers for agent side effects.
+
+An agent that retries a tool call after a crash can charge a card twice, send a
+message twice, or deploy twice. Durable-execution engines do not solve this for
+you — Temporal and Restate both guarantee deterministic *replay of
+orchestration* and leave exactly-once external effects to the application. This
+package is that piece: classify the effect, key it, persist the key, and refuse
+to run it again.
+
+::
+
+    from honestcode.guards import EffectStore, SideEffectGuard
+
+    guard = SideEffectGuard(session_id="sess-1", store_path=".agent/effects.db")
+
+    outcome = guard.run(
+        "send_invoice",
+        target="cus_123",
+        payload={"amount_cents": 4200},
+        execute=lambda: billing.send_invoice("cus_123", 4200),
+        approve_irreversible=True,
+    )
+
+    outcome.executed     # False on the second call — a receipt, not a charge
+    outcome.effect_id    # stable across restarts, because the key is on disk
+
+Every effect class is treated as irreversible until classified otherwise, which
+is why ``send_invoice`` needs the explicit approval above.
+
+Isolation
+---------
+
+This subpackage is deliberately self-contained and is expected to be extracted
+into its own distribution:
+
+* It imports **only the standard library** plus its own siblings. It must never
+  import ``honestcode.*`` outside ``honestcode.guards.*``, because the rest of
+  HonestCode answers questions about code while this package wraps code that
+  changes the world — different lifecycle, different blast radius.
+* It is **not registered as an MCP tool**. HonestCode's MCP surface is reached
+  through client configuration files; a guard belongs in the caller's own
+  process, on its own tool-call path.
+* It has **no dependency on HonestCode's protocols** — findings, reports, and
+  the ``Finding`` shape are all absent here. A guard returns receipts.
+"""
+
+from honestcode.guards.guard import (
+    EffectNotRunnable,
+    ExecutionOutcome,
+    GuardError,
+    Precondition,
+    PreconditionFailed,
+    RecoveryDecision,
+    SideEffectGuard,
+    durable_scope,
+    precondition,
+    strategy_for,
+)
+from honestcode.guards.store import (
+    ACTIVE_STATUSES,
+    COMMITTED,
+    COMPENSATED,
+    EXECUTING,
+    FAILED,
+    PENDING,
+    EffectRecord,
+    EffectStatus,
+    EffectStore,
+    StoreError,
+)
+from honestcode.guards.taxonomy import (
+    EffectClass,
+    RecoveryStrategy,
+    classify,
+)
+
+__all__ = [
+    # taxonomy
+    "EffectClass",
+    "RecoveryStrategy",
+    "classify",
+    # store
+    "EffectRecord",
+    "EffectStatus",
+    "EffectStore",
+    "StoreError",
+    "ACTIVE_STATUSES",
+    "PENDING",
+    "EXECUTING",
+    "COMMITTED",
+    "FAILED",
+    "COMPENSATED",
+    # guard
+    "ExecutionOutcome",
+    "GuardError",
+    "Precondition",
+    "PreconditionFailed",
+    "EffectNotRunnable",
+    "RecoveryDecision",
+    "SideEffectGuard",
+    "durable_scope",
+    "precondition",
+    "strategy_for",
+]