honestcode 0.2.0__py3-none-any.whl

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
+
+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 root.rglob("*.py"):
+        if "__pycache__" in p.parts or p.name.startswith("."):
+            continue
+        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/honest/__init__.py

@@ -0,0 +1,19 @@
+"""Honest core: symbol indexing, routing and hallucination checks."""
+
+from honestcode.honest.router import HonestRouter, RouteChoice, ToolIntent
+from honestcode.honest.symbol_index import (
+    ProjectIndex,
+    SymbolIndex,
+    SymbolInfo,
+    get_project_index,
+)
+
+__all__ = [
+    "HonestRouter",
+    "ProjectIndex",
+    "RouteChoice",
+    "SymbolIndex",
+    "SymbolInfo",
+    "ToolIntent",
+    "get_project_index",
+]

honestcode/honest/project_binding.py

@@ -0,0 +1,157 @@
+"""Project-level binding (``.honestcode/``) and MCP client auto-configuration.
+
+``init`` creates a ``.honestcode/config.json`` marker next to the project root so
+CLI commands can discover the project without being told the path every time —
+the same idea as CodeGraph's ``.codegraph/`` binding directory. ``install``
+probes well-known MCP client config files and registers the server for you.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+BINDING_DIR = ".honestcode"
+CONFIG_NAME = "config.json"
+
+# MCP client config locations, probed in this order.
+_CLIENT_TARGETS = [
+    ("cursor", lambda root: root / ".cursor" / "mcp.json", ".cursor/mcp.json"),
+    ("vscode", lambda root: root / ".vscode" / "mcp.json", ".vscode/mcp.json"),
+    (
+        "claude",
+        lambda root: Path.home() / ".claude.json",
+        "~/.claude.json",
+    ),
+]
+
+
+@dataclass
+class Binding:
+    root: Path
+    config_path: Path
+
+
+def _server_command() -> list[str]:
+    """Command to launch the MCP server from this installation."""
+    if shutil.which("honestcode-mcp"):
+        return ["honestcode-mcp"]
+    return [sys.executable, "-m", "honestcode.mcp.server"]
+
+
+def init_project(path: str | None = None, force: bool = False) -> dict:
+    """Create a ``.honestcode/`` binding for *path* (default: cwd)."""
+    root = Path(path or os.getcwd()).resolve()
+    if not root.is_dir():
+        return {"success": False, "error": f"Not a directory: {root}"}
+    binding_dir = root / BINDING_DIR
+    config_path = binding_dir / CONFIG_NAME
+    if config_path.exists() and not force:
+        return {
+            "success": True,
+            "bound": True,
+            "root": str(root),
+            "config": str(config_path),
+            "message": "Already bound (use --force to re-bind)",
+        }
+    binding_dir.mkdir(parents=True, exist_ok=True)
+    config = {
+        "root": str(root),
+        "created_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "version": 1,
+    }
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return {
+        "success": True,
+        "bound": True,
+        "root": str(root),
+        "config": str(config_path),
+    }
+
+
+def uninit_project(path: str | None = None) -> dict:
+    """Remove the ``.honestcode/`` binding for *path* (default: cwd)."""
+    root = Path(path or os.getcwd()).resolve()
+    binding_dir = root / BINDING_DIR
+    config_path = binding_dir / CONFIG_NAME
+    if not config_path.exists():
+        return {"success": False, "error": f"No binding found at {root / BINDING_DIR}"}
+    shutil.rmtree(binding_dir)
+    return {"success": True, "root": str(root), "unbound": True}
+
+
+def find_project_root(start: str | None = None) -> Path | None:
+    """Walk upward from *start* (default: cwd) looking for a project marker.
+
+    Prefers a ``.honestcode/`` binding, then falls back to a ``.git`` directory.
+    """
+    cur = Path(start or os.getcwd()).resolve()
+    if not cur.is_dir():
+        cur = cur.parent
+    for candidate in [cur, *cur.parents]:
+        if (candidate / BINDING_DIR / CONFIG_NAME).exists():
+            return candidate
+        if (candidate / ".git").exists():
+            return candidate
+    return None
+
+
+def install_mcp_config(
+    path: str | None = None,
+    client: str | None = None,
+    dry_run: bool = False,
+    command: list[str] | None = None,
+) -> dict:
+    """Register the MCP server with a client's config file.
+
+    Probes Cursor, VS Code and Claude Code config locations and writes the
+    stdio server entry. Use ``dry_run=True`` to preview without writing.
+    """
+    root = Path(path or os.getcwd()).resolve()
+    launch = command or _server_command()
+
+    targets = _CLIENT_TARGETS if not client else [t for t in _CLIENT_TARGETS if t[0] == client]
+    if not targets:
+        return {"success": False, "error": f"Unknown client: {client}"}
+
+    entry = {
+        "command": launch[0],
+        "args": launch[1:],
+    }
+    written: list[dict] = []
+    skipped: list[dict] = []
+
+    for name, locator, label in targets:
+        target = Path(locator(root))
+        payload: dict = {}
+        if target.exists():
+            try:
+                payload = json.loads(target.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                payload = {}
+        # Cursor and Claude Code store servers under "mcpServers";
+        # VS Code uses "servers".
+        key = "mcpServers" if name in ("claude", "cursor") else "servers"
+        servers = payload.setdefault(key, {})
+        servers["honestcode"] = entry
+        if dry_run:
+            skipped.append({"client": name, "path": label, "would_write": True})
+            continue
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+        except OSError as exc:
+            return {"success": False, "error": f"Cannot write {label}: {exc}"}
+        written.append({"client": name, "path": label})
+
+    result: dict = {"success": True, "dry_run": dry_run, "command": launch}
+    if written:
+        result["written"] = written
+    if skipped:
+        result["skipped"] = skipped
+    return result

honestcode/honest/router.py

@@ -0,0 +1,200 @@
+"""
+HonestRouter: route natural-language queries to the right tool and detect
+likely hallucinations by checking project symbols and installed dependency APIs.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from honestcode.mcp.knowledge_base import APIKnowledgeBase
+
+__all__ = ["ToolIntent", "RouteChoice", "HonestRouter"]
+
+
+class ToolIntent(Enum):
+    INDEX = "index"
+    CHECK_SYMBOL = "check_symbol"
+    CHECK_API = "check_api"
+    EXECUTE_CODE = "execute_code"
+    SCAN_FILE = "scan_file"
+    FIND_DEAD_CODE = "find_dead_code"
+    EXPLORE_CALL_GRAPH = "explore_call_graph"
+    SEARCH_CODE = "search_code"
+    VALIDATE_TYPES = "validate_types"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class RouteChoice:
+    intent: ToolIntent
+    confidence: float
+    reason: str
+
+
+class HonestRouter:
+    """Route user queries and evaluate code suggestions against the index."""
+
+    def __init__(
+        self,
+        project_symbols: dict[str, Any],
+        dep_symbols: set[str],
+        dep_kb: APIKnowledgeBase | None = None,
+        project_root: str | Path | None = None,
+    ):
+        self.project_symbols = project_symbols
+        self.dep_symbols = dep_symbols
+        self.dep_kb = dep_kb
+        self.project_root = Path(project_root) if project_root else None
+
+    @staticmethod
+    def choose_tool(query: str) -> RouteChoice:
+        q = query.lower()
+        patterns: list[tuple[list[str], ToolIntent, str]] = [
+            (
+                ["index", "scan project", "build index"],
+                ToolIntent.INDEX,
+                "query asks to index project",
+            ),
+            (
+                ["symbol", "defined", "function exists"],
+                ToolIntent.CHECK_SYMBOL,
+                "query checks a symbol",
+            ),
+            (
+                ["api", "library", "pandas", "numpy"],
+                ToolIntent.CHECK_API,
+                "query checks an external API",
+            ),
+            (
+                ["run", "execute", "test code"],
+                ToolIntent.EXECUTE_CODE,
+                "query asks to execute code",
+            ),
+            (["scan file", "check file"], ToolIntent.SCAN_FILE, "query asks to scan a file"),
+            (["dead code", "unused"], ToolIntent.FIND_DEAD_CODE, "query asks for dead code"),
+            (
+                ["call graph", "caller", "callee"],
+                ToolIntent.EXPLORE_CALL_GRAPH,
+                "query explores call graph",
+            ),
+            (["search", "find code"], ToolIntent.SEARCH_CODE, "query searches code"),
+            (["type", "validate"], ToolIntent.VALIDATE_TYPES, "query validates types"),
+        ]
+        for keywords, intent, reason in patterns:
+            if any(k in q for k in keywords):
+                return RouteChoice(intent=intent, confidence=0.7, reason=reason)
+        return RouteChoice(intent=ToolIntent.UNKNOWN, confidence=0.0, reason="no clear intent")
+
+    def route(self, query: str, file_path: str | None = None) -> dict:
+        """Route a query and return a confidence judgement."""
+        choice = self.choose_tool(query)
+
+        if choice.intent == ToolIntent.CHECK_API:
+            # Find dotted API references like pandas.read_csv
+            matches = re.findall(r"\b([a-zA-Z_][\w]*(?:\.[a-zA-Z_][\w]*)+)\b", query)
+            for api in matches:
+                return self._check_api(api)
+            return {"intent": "check_api", "result": "no API reference found"}
+
+        if choice.intent == ToolIntent.CHECK_SYMBOL:
+            words = re.findall(r"\b([a-zA-Z_]\w{2,})\b", query)
+            candidates = [w for w in words if w[0].islower()]
+            if not candidates:
+                return {"intent": "check_symbol", "result": "no symbol candidates"}
+            symbol = candidates[0]
+            defined = symbol in self.project_symbols
+            return {
+                "intent": "check_symbol",
+                "symbol": symbol,
+                "defined": defined,
+                "confidence": 0.8 if defined else 0.3,
+            }
+
+        if choice.intent == ToolIntent.SCAN_FILE and file_path:
+            return {"intent": "scan_file", "file": file_path}
+
+        return {"intent": choice.intent.value, "confidence": choice.confidence}
+
+    def _check_api(self, api_name: str) -> dict:
+        if api_name in self.dep_symbols:
+            return {"intent": "check_api", "api": api_name, "valid": True}
+
+        parts = api_name.split(".")
+        base = parts[0]
+        suggestions: list[str] = []
+        if self.dep_kb is not None:
+            members = [k for k in self.dep_kb.all_names() if k.startswith(base + ".")]
+            if members:
+                suggestions = difflib.get_close_matches(api_name, members, n=3, cutoff=0.5)
+                if not suggestions:
+                    suggestions = members[:3]
+        return {
+            "intent": "check_api",
+            "api": api_name,
+            "valid": False,
+            "reason": "not found in dependency API index",
+            "suggestions": suggestions,
+        }
+
+    def check_call(self, call: str, file_path: str | None = None) -> dict:
+        """Evaluate a single code snippet / API call for hallucination risk."""
+        if "." in call:
+            return self._check_api(call)
+
+        if call in self.project_symbols:
+            return {"call": call, "valid": True, "source": "project"}
+
+        if call in self.dep_symbols:
+            return {"call": call, "valid": True, "source": "dependency"}
+
+        # Check whether the base module looks like a project module.
+        # Compare against the full module path components, not a substring
+        # ("util" must not match "pkg.utility").
+        base = call.split("(")[0].split(".")[0].strip()
+        if file_path and base in self._module_of(file_path).split("."):
+            return {"call": call, "valid": True, "source": "same_module"}
+
+        suggestions = difflib.get_close_matches(
+            call, list(self.project_symbols) + list(self.dep_symbols), n=3
+        )
+        return {
+            "call": call,
+            "valid": False,
+            "risk": "high",
+            "suggestions": suggestions,
+        }
+
+    def _module_of(self, file_path: str | Path) -> str:
+        """Infer a Python module name from a file path relative to the project root.
+
+        Falls back to a best-effort absolute-path derivation when no root is set.
+        """
+        p = Path(file_path)
+
+        # Prefer project-relative path.
+        if self.project_root:
+            try:
+                rel = p.resolve().relative_to(self.project_root.resolve())
+            except ValueError:
+                rel = p
+        else:
+            rel = p
+
+        parts = list(rel.with_suffix("").parts)
+
+        # Only strip "src" if it is a real layout prefix (has sub-packages after it).
+        if len(parts) > 1 and parts[0] == "src":
+            parts = parts[1:]
+
+        # __init__.py represents the package itself.
+        if parts and parts[-1] == "__init__":
+            parts.pop()
+
+        return ".".join(parts)