honestcode 0.2.0__py3-none-any.whl

honestcode/__init__.py

@@ -0,0 +1,19 @@
+"""HonestCode: verify AI-generated code against project structure and installed APIs."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from honestcode import honest, mcp, sandbox, structure
+
+__version__ = "0.1.0"
+__all__ = ["honest", "mcp", "sandbox", "structure"]
+
+
+def __getattr__(name: str):
+    if name in __all__:
+        import importlib
+
+        return importlib.import_module(f"honestcode.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

honestcode/cli.py

@@ -0,0 +1,338 @@
+"""
+Command-line interface for HonestCode.
+
+Every MCP tool has a CLI equivalent so the same capabilities can be used
+from scripts, CI pipelines, and non-MCP harnesses without launching a
+server process.
+
+Usage:
+    honestcode index /path/to/project
+    honestcode deps /path/to/project
+    honestcode scan src/main.py
+    honestcode check-symbol pkg.core.helper
+    honestcode check-api pandas.read_csv
+    honestcode validate "for x in None: pass"
+    honestcode dead-code --entrypoints pkg.cli.main
+    honestcode search "def \\w+_helper"
+    honestcode call-graph pkg.core.helper
+    honestcode similar --threshold 0.85
+    honestcode stats
+    honestcode choose-tool "is my_symbol defined"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from typing import TYPE_CHECKING, Any
+
+from honestcode.honest import project_binding as _binding
+from honestcode.mcp import tools as _tools
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["main"]
+
+
+def _emit(result: dict[str, Any]) -> int:
+    """Print *result* as JSON to stdout and return an exit code."""
+    sys.stdout.write(json.dumps(result, indent=2, default=str) + "\n")
+    # Non-zero exit when the operation reported a failure.
+    return 0 if result.get("success", True) else 1
+
+
+def _emit_issues(result: dict[str, Any], issue_key: str = "issues") -> int:
+    """Like _emit but exit non-zero when issues were found."""
+    sys.stdout.write(json.dumps(result, indent=2, default=str) + "\n")
+    if not result.get("success", True):
+        return 1
+    n = len(result.get(issue_key, []))
+    return 1 if n else 0
+
+
+def _cmd_index(args: argparse.Namespace) -> int:
+    return _emit(_tools.index_project(args.path, force_rebuild=args.force, watch=args.watch))
+
+
+def _cmd_affected(args: argparse.Namespace) -> int:
+    return _emit(_tools.affected_files(base=args.base, head=args.head, max_depth=args.depth))
+
+
+def _cmd_impact(args: argparse.Namespace) -> int:
+    return _emit(_tools.explore_impact(args.symbol, max_depth=args.depth))
+
+
+def _cmd_watch(args: argparse.Namespace) -> int:
+    """Index and keep the project fresh until interrupted (Ctrl+C)."""
+    res = _tools.index_project(args.path, force_rebuild=args.force, watch=True)
+    _emit(res)
+    if not res.get("success"):
+        return 1
+    print(f"Watching {args.path} — press Ctrl+C to stop.", file=sys.stderr)
+    try:
+        while True:
+            time.sleep(60)
+    except KeyboardInterrupt:
+        _emit(_tools.stop_watching())
+        return 0
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    return _emit(_binding.init_project(args.path, force=args.force))
+
+
+def _cmd_uninit(args: argparse.Namespace) -> int:
+    return _emit(_binding.uninit_project(args.path))
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    return _emit(
+        _binding.install_mcp_config(
+            path=args.path,
+            client=args.client,
+            dry_run=args.dry_run,
+        )
+    )
+
+
+def _cmd_root(args: argparse.Namespace) -> int:
+    root = _binding.find_project_root(args.path)
+    if root is None:
+        return _emit(
+            {"success": False, "error": "No project root found (no .honestcode/ or .git/)"}
+        )
+    return _emit({"success": True, "root": str(root)})
+
+
+def _cmd_deps(args: argparse.Namespace) -> int:
+    return _emit(_tools.load_project_deps(args.path))
+
+
+def _cmd_scan(args: argparse.Namespace) -> int:
+    return _emit_issues(_tools.scan_file(args.file), issue_key="issues")
+
+
+def _cmd_check_symbol(args: argparse.Namespace) -> int:
+    res = _tools.check_symbol(args.symbol, file_path=args.file or None)
+    _emit(res)
+    return 0 if res.get("defined") else 1
+
+
+def _cmd_check_api(args: argparse.Namespace) -> int:
+    res = _tools.check_api(args.api)
+    _emit(res)
+    return 0 if res.get("valid") else 1
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    return _emit_issues(_tools.validate_types(args.code), issue_key="issues")
+
+
+def _cmd_execute(args: argparse.Namespace) -> int:
+    return _emit(_tools.execute_code(args.code, prelude=args.prelude, known_names=args.known_names))
+
+
+def _cmd_dead_code(args: argparse.Namespace) -> int:
+    return _emit_issues(
+        _tools.find_dead_code(
+            entrypoints=args.entrypoints,
+            ignore_patterns=args.ignore,
+            include_tests=args.include_tests,
+        ),
+        issue_key="dead_symbols",
+    )
+
+
+def _cmd_similar(args: argparse.Namespace) -> int:
+    return _emit_issues(_tools.find_similar_code(threshold=args.threshold), issue_key="pairs")
+
+
+def _cmd_call_graph(args: argparse.Namespace) -> int:
+    return _emit(_tools.explore_call_graph(args.symbol))
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    return _emit_issues(_tools.search_code(args.pattern, glob=args.glob), issue_key="matches")
+
+
+def _cmd_load_package(args: argparse.Namespace) -> int:
+    return _emit(_tools.load_package_apis(args.package))
+
+
+def _cmd_stats(args: argparse.Namespace) -> int:
+    return _emit(_tools.get_project_stats())
+
+
+def _cmd_choose_tool(args: argparse.Namespace) -> int:
+    return _emit(_tools.choose_tool(args.query))
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="honestcode",
+        description="HonestCode CLI — verify AI-generated code against your project.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    p = sub.add_parser("index", help="Build (or reuse) the project symbol index.")
+    p.add_argument("path", help="Project root directory.")
+    p.add_argument("--force", action="store_true", help="Force rebuild the index.")
+    p.add_argument(
+        "--watch",
+        action="store_true",
+        help="Start a background watcher that re-indexes on file changes.",
+    )
+    p.set_defaults(func=_cmd_index)
+
+    p = sub.add_parser(
+        "watch",
+        help="Index a project and keep it fresh (background watcher, Ctrl+C to stop).",
+    )
+    p.add_argument("path", help="Project root directory.")
+    p.add_argument("--force", action="store_true", help="Force rebuild the index.")
+    p.set_defaults(func=_cmd_watch)
+
+    p = sub.add_parser("deps", help="Load dependency APIs from requirements.txt / pyproject.toml.")
+    p.add_argument("path", help="Project root directory.")
+    p.set_defaults(func=_cmd_deps)
+
+    p = sub.add_parser("scan", help="Scan a file for undefined calls and API issues.")
+    p.add_argument("file", help="Path to the Python file to scan.")
+    p.set_defaults(func=_cmd_scan)
+
+    p = sub.add_parser("check-symbol", help="Check whether a symbol is defined in the project.")
+    p.add_argument("symbol", help="Module-qualified symbol name, e.g. pkg.core.helper.")
+    p.add_argument("--file", default="", help="Optional file the symbol appears in.")
+    p.set_defaults(func=_cmd_check_symbol)
+
+    p = sub.add_parser("check-api", help="Verify a library API call exists.")
+    p.add_argument("api", help="Fully qualified API name, e.g. pandas.read_csv.")
+    p.set_defaults(func=_cmd_check_api)
+
+    p = sub.add_parser("validate", help="Run structural type checks on a code snippet.")
+    p.add_argument("code", help="Python source to validate.")
+    p.set_defaults(func=_cmd_validate)
+
+    p = sub.add_parser("execute", help="Execute code in a sandboxed subprocess.")
+    p.add_argument("code", help="Python source to execute.")
+    p.add_argument("--prelude", default="", help="Setup code run before the main code.")
+    p.add_argument(
+        "--known-names",
+        nargs="*",
+        default=None,
+        help="Known symbol names for typo suggestions.",
+    )
+    p.set_defaults(func=_cmd_execute)
+
+    p = sub.add_parser(
+        "dead-code",
+        help="Find unused symbols. Exit code 1 if any dead symbols are found.",
+    )
+    p.add_argument(
+        "--entrypoints",
+        nargs="*",
+        default=None,
+        help="Symbol names to always treat as alive.",
+    )
+    p.add_argument(
+        "--ignore",
+        nargs="*",
+        default=None,
+        help="Regex patterns for files to exclude from dead-code results.",
+    )
+    p.add_argument(
+        "--no-tests",
+        dest="include_tests",
+        action="store_false",
+        help="Do not treat symbols in test files as alive.",
+    )
+    p.set_defaults(func=_cmd_dead_code, include_tests=True)
+
+    p = sub.add_parser("similar", help="Find function-level code clones across the project.")
+    p.add_argument(
+        "--threshold",
+        type=float,
+        default=0.85,
+        help="Similarity ratio above which two functions are reported (0-1).",
+    )
+    p.set_defaults(func=_cmd_similar)
+
+    p = sub.add_parser("call-graph", help="Explore callers and callees of a symbol.")
+    p.add_argument("symbol", help="Symbol name to explore.")
+    p.set_defaults(func=_cmd_call_graph)
+
+    p = sub.add_parser("impact", help="Compute the blast radius of a symbol.")
+    p.add_argument("symbol", help="Symbol name to analyze.")
+    p.add_argument("--depth", type=int, default=3, help="Max call-graph hops (default: 3).")
+    p.set_defaults(func=_cmd_impact)
+
+    p = sub.add_parser(
+        "affected",
+        help="Files/tests that may be affected by a git diff (from the call graph).",
+    )
+    p.add_argument("--base", default="HEAD", help="Git ref to diff against (default: HEAD).")
+    p.add_argument("--head", default=None, help="Optional second ref for base..head diffs.")
+    p.add_argument("--depth", type=int, default=4, help="Max call-graph hops (default: 4).")
+    p.set_defaults(func=_cmd_affected)
+
+    p = sub.add_parser("search", help="Search project source code with a regex pattern.")
+    p.add_argument("pattern", help="Regular expression to search for.")
+    p.add_argument("--glob", default="*.py", help="Glob pattern for files to search.")
+    p.set_defaults(func=_cmd_search)
+
+    p = sub.add_parser("load-package", help="Load API signatures for a specific package.")
+    p.add_argument("package", help="Importable package name, e.g. numpy.")
+    p.set_defaults(func=_cmd_load_package)
+
+    p = sub.add_parser("stats", help="Show statistics about the indexed project.")
+    p.set_defaults(func=_cmd_stats)
+
+    p = sub.add_parser("choose-tool", help="Show which tool a natural-language query maps to.")
+    p.add_argument("query", help="Natural-language query.")
+    p.set_defaults(func=_cmd_choose_tool)
+
+    p = sub.add_parser(
+        "init",
+        help="Bind a directory as a HonestCode project (.honestcode/).",
+    )
+    p.add_argument("path", nargs="?", default=None, help="Project directory (default: cwd).")
+    p.add_argument("--force", action="store_true", help="Re-create an existing binding.")
+    p.set_defaults(func=_cmd_init)
+
+    p = sub.add_parser("uninit", help="Remove the .honestcode/ project binding.")
+    p.add_argument("path", nargs="?", default=None, help="Project directory (default: cwd).")
+    p.set_defaults(func=_cmd_uninit)
+
+    p = sub.add_parser(
+        "install",
+        help="Register the MCP server with a client (Cursor, VS Code, Claude Code).",
+    )
+    p.add_argument("path", nargs="?", default=None, help="Project directory (default: cwd).")
+    p.add_argument(
+        "--client",
+        choices=["cursor", "vscode", "claude"],
+        default=None,
+        help="Only configure this client (default: all detected).",
+    )
+    p.add_argument("--dry-run", action="store_true", help="Preview changes without writing.")
+    p.set_defaults(func=_cmd_install)
+
+    p = sub.add_parser("root", help="Print the detected project root (binding or git).")
+    p.add_argument("path", nargs="?", default=None, help="Start directory (default: cwd).")
+    p.set_defaults(func=_cmd_root)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    func: Callable[[argparse.Namespace], int] = args.func
+    return func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

honestcode/graph/__init__.py

@@ -0,0 +1,13 @@
+"""Persistent graph storage for HonestCode.
+
+The call graph (definitions + references) is expensive to rebuild — it needs
+an AST pass over every source file. ``graph_store.GraphCache`` persists it to
+SQLite next to the symbol index so graph queries read from disk instead of
+re-parsing the project on every call, and a FTS5 virtual table backs fast
+full-text search.
+"""
+
+from honestcode.graph.graph_store import CallGraph, GraphCache
+from honestcode.graph.watcher import ProjectWatcher
+
+__all__ = ["CallGraph", "GraphCache", "ProjectWatcher"]

honestcode/graph/graph_store.py

@@ -0,0 +1,229 @@
+"""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 SHA-256 hashes of 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.
+
+The same database hosts a FTS5 virtual table over file contents. ``search_code``
+uses it to shrink a regex scan to a *superset* of candidate files, keeping
+results identical to a full scan while touching far fewer files on large repos.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+import sqlite3
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["CallGraph", "GraphCache"]
+
+_DB_VERSION = 1
+
+
+@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 sorted(
+        p for p in root.rglob("*.py") if not p.name.startswith(".") and "__pycache__" not in p.parts
+    )
+
+
+def _file_hashes(root: Path) -> dict[str, str]:
+    """Map each relative .py path to a SHA-256 of its bytes."""
+    hashes: dict[str, str] = {}
+    for p in _python_files(root):
+        try:
+            hashes[str(p.relative_to(root))] = hashlib.sha256(p.read_bytes()).hexdigest()
+        except OSError:
+            continue
+    return hashes
+
+
+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='hashes'").fetchone()
+            root_row = cur.execute("SELECT value FROM meta WHERE key='root'").fetchone()
+        except sqlite3.Error:
+            return False
+        finally:
+            if conn is not None:
+                conn.close()
+        if row is None or root_row is None:
+            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_hashes(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()
+        hashes = _file_hashes(root)
+        files = sorted(hashes.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)),
+                    ("hashes", json.dumps(hashes)),
+                ],
+            )
+            conn.commit()
+            self._rebuild_fts(conn, root, files)
+        finally:
+            conn.close()
+
+    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='unicode61')"
+            )
+        except sqlite3.Error:
+            logger.debug("FTS5 unavailable; search_code will fall back to regex scans")
+            return
+        for rel in files:
+            path = root / rel
+            try:
+                content = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            conn.execute("INSERT INTO fts_files (path, content) VALUES (?, ?)", (rel, content))
+        conn.commit()
+
+    def search_candidate_files(self, pattern: str) -> list[str] | None:
+        """Return files that *may* match ``pattern`` using FTS5 prefix queries.
+
+        The candidate set is a superset of what a plain regex scan can match
+        (token prefix queries such as ``foo*`` also find ``foobar``), so callers
+        get identical results while scanning far fewer files.
+
+        Returns ``None`` when FTS5 is unavailable (fall back to a full scan),
+        or an empty list when nothing can match (short-circuit to no results).
+        """
+        tokens = [t for t in re.findall(r"\w+", pattern) if t]
+        if not tokens:
+            return None
+        try:
+            conn = sqlite3.connect(str(self.path))
+            try:
+                cur = conn.cursor()
+                seen: set[str] = set()
+                for tok in tokens:
+                    for (path,) in cur.execute(
+                        "SELECT path FROM fts_files WHERE fts_files MATCH ?", (tok + "*",)
+                    ):
+                        seen.add(path)
+            finally:
+                conn.close()
+        except sqlite3.Error:
+            return None
+        return sorted(seen)