honestcode 0.5.0__py3-none-any.whl

honestcode/structure/multi_lang.py

@@ -0,0 +1,267 @@
+"""Optional tree-sitter multi-language symbol extraction.
+
+Python remains the fully supported language (stdlib ``ast``). For JavaScript,
+TypeScript and a few other popular languages, symbol extraction is available
+when the optional extras are installed::
+
+    pip install -e "honestcode[multi-language]"
+
+Everything degrades gracefully: without tree-sitter, ``is_supported`` still
+recognizes the file by extension, but ``extract_symbols`` raises
+``TreeSitterUnavailable`` so callers can report a clear message instead of a
+traceback.
+"""
+
+from __future__ import annotations
+
+import importlib
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+LANG_BY_EXT: dict[str, str] = {
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+}
+
+# node type -> symbol kind, per language (tree-sitter grammar node names).
+_SYMBOL_RULES: dict[str, list[tuple[str, str]]] = {
+    "javascript": [
+        ("function_declaration", "function"),
+        ("class_declaration", "class"),
+        ("method_definition", "method"),
+        ("function_expression", "function"),
+    ],
+    "typescript": [
+        ("function_declaration", "function"),
+        ("class_declaration", "class"),
+        ("method_definition", "method"),
+        ("function_expression", "function"),
+        ("interface_declaration", "interface"),
+        ("type_alias_declaration", "type"),
+        ("enum_declaration", "enum"),
+    ],
+    "tsx": [
+        ("function_declaration", "function"),
+        ("class_declaration", "class"),
+        ("method_definition", "method"),
+        ("function_expression", "function"),
+        ("interface_declaration", "interface"),
+        ("type_alias_declaration", "type"),
+        ("enum_declaration", "enum"),
+    ],
+    "go": [
+        ("function_declaration", "function"),
+        ("method_declaration", "method"),
+        ("type_spec", "type"),
+    ],
+    "rust": [
+        ("function_item", "function"),
+        ("struct_item", "struct"),
+        ("enum_item", "enum"),
+        ("trait_item", "trait"),
+    ],
+    "java": [
+        ("class_declaration", "class"),
+        ("interface_declaration", "interface"),
+        ("enum_declaration", "enum"),
+        ("method_declaration", "method"),
+    ],
+}
+
+# Some grammars name their declaration nodes with a ``type_identifier``
+# instead of an ``identifier`` (e.g. TypeScript type aliases, Go type specs);
+# the query patterns below use the correct node type per language.
+# Grammars disagree about the node type used for a declaration's name; a query
+# naming the wrong one is rejected outright ("Impossible pattern"), which broke
+# every multi-language scan on the 0.25 grammars.
+_NAME_NODE_TYPES: dict[str, dict[str, str]] = {
+    "javascript": {"method_definition": "property_identifier"},
+    "typescript": {
+        "class_declaration": "type_identifier",
+        "interface_declaration": "type_identifier",
+        "type_alias_declaration": "type_identifier",
+        "method_definition": "property_identifier",
+    },
+    "tsx": {
+        "class_declaration": "type_identifier",
+        "interface_declaration": "type_identifier",
+        "type_alias_declaration": "type_identifier",
+        "method_definition": "property_identifier",
+    },
+    "go": {
+        "method_declaration": "field_identifier",
+        "type_spec": "type_identifier",
+    },
+    "rust": {
+        "struct_item": "type_identifier",
+        "enum_item": "type_identifier",
+        "trait_item": "type_identifier",
+    },
+}
+
+# tree-sitter-typescript ships two grammars in one module and exposes them as
+# named factories rather than a generic ``language()``.
+_LANGUAGE_FACTORIES: dict[str, tuple[str, ...]] = {
+    "typescript": ("language_typescript", "language"),
+    "tsx": ("language_tsx", "language"),
+}
+
+_QUERIES: dict[str, object] = {}
+
+
+class TreeSitterUnavailable(RuntimeError):
+    """Raised when tree-sitter (or a language grammar) is not installed."""
+
+
+def detect_language(path: str | Path) -> str | None:
+    """Return the language name for *path* by extension, or None."""
+    return LANG_BY_EXT.get(Path(path).suffix.lower())
+
+
+def is_supported(path: str | Path) -> bool:
+    return detect_language(path) is not None
+
+
+def _import_tree_sitter():  # pragma: no cover - requires optional extras
+    try:
+        from tree_sitter import Language, Parser  # noqa: F401
+
+        return Language, Parser
+    except ImportError as exc:
+        raise TreeSitterUnavailable(
+            "tree-sitter is not installed. Run: pip install -e '.[multi-language]'"
+        ) from exc
+
+
+def _load_language(name: str) -> object:  # pragma: no cover - requires optional extras
+    """Load a language grammar, supporting tree-sitter >= 0.21 binding APIs."""
+    module_name = (
+        "tree_sitter_typescript" if name in ("typescript", "tsx") else f"tree_sitter_{name}"
+    )
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as exc:
+        raise TreeSitterUnavailable(
+            f"Grammar for '{name}' not installed (tree-sitter-{name} package)"
+        ) from exc
+
+    factory = None
+    for attr in _LANGUAGE_FACTORIES.get(name, ("language",)):
+        factory = getattr(module, attr, None)
+        if factory is not None:
+            break
+    if factory is None:  # old-style / unknown bindings
+        raise TreeSitterUnavailable(
+            f"Unsupported tree-sitter binding for '{name}' (no language factory)"
+        )
+    lang = factory()
+    # tree-sitter >= 0.22 returns a Language instance; 0.21 returns a handle.
+    try:
+        from tree_sitter import Language
+
+        if not isinstance(lang, Language):
+            lang = Language(lang)
+    except Exception:  # noqa: BLE001
+        pass
+    return lang
+
+
+def _query_for(name: str, language) -> object:  # pragma: no cover - optional extras
+    if name in _QUERIES:
+        return _QUERIES[name]
+    name_node_overrides = _NAME_NODE_TYPES.get(name, {})
+    parts = [
+        f"({node} name: ({name_node_overrides.get(node, 'identifier')}) @name.{kind})"
+        for node, kind in _SYMBOL_RULES[name]
+    ]
+    source = " ".join(parts)
+    # ``Language.query(source)`` is the instance API on 0.21-0.25; calling it
+    # on the class (as this did) passes the string as ``self`` and fails on
+    # 0.25 with "descriptor 'query' ... doesn't apply to a 'str' object".
+    # 0.25 deprecates it in favour of the Query constructor, so prefer that
+    # form where the installed binding accepts it.
+    query = None
+    try:
+        from tree_sitter import Query
+    except ImportError:
+        Query = None  # type: ignore[assignment,misc]
+    if Query is not None:
+        try:
+            query = Query(language, source)
+        except (TypeError, ValueError):
+            query = None
+    if query is None:
+        query = language.query(source)
+    _QUERIES[name] = query
+    return query
+
+
+def _captures(query, node) -> list[tuple[object, str]]:
+    """Return ``(node, capture-name)`` pairs across tree-sitter versions.
+
+    0.21-0.24 expose ``Query.captures(node)`` returning a list of tuples; 0.25
+    removed that method in favour of ``QueryCursor(query).captures(node)``,
+    which returns ``{capture_name: [node, ...]}``.
+    """
+    if hasattr(query, "captures"):
+        raw = query.captures(node)
+        return [(item[0], str(item[1])) for item in raw]
+    try:
+        from tree_sitter import QueryCursor
+    except ImportError as exc:  # pragma: no cover - impossible on supported versions
+        raise TreeSitterUnavailable("tree-sitter QueryCursor API unavailable") from exc
+    raw = QueryCursor(query).captures(node)
+    pairs: list[tuple[object, str]] = []
+    for tag, items in raw.items():
+        for item in items:
+            pairs.append((item[0] if isinstance(item, tuple) else item, str(tag)))
+    return pairs
+
+
+def extract_symbols(path: str | Path) -> list[dict]:  # pragma: no cover - requires optional extras
+    """Extract ``{name, line, kind}`` symbols from a non-Python source file.
+
+    Raises ``TreeSitterUnavailable`` when the optional dependency is missing.
+    """
+    path = Path(path)
+    lang = detect_language(path)
+    if lang is None:
+        raise ValueError(f"Unsupported language for {path}")
+
+    Language, Parser = _import_tree_sitter()
+    grammar = _load_language(lang)
+    parser = Parser()
+    try:
+        parser.language = grammar
+    except AttributeError:  # tree-sitter 0.21
+        parser.set_language(grammar)
+    source = path.read_bytes()
+
+    tree = parser.parse(source)
+    query = _query_for(lang, grammar)
+    captures = _captures(query, tree.root_node)
+
+    symbols: list[dict] = []
+    for node, tag in captures:
+        if not tag.startswith("name."):
+            continue
+        name = node.text.decode("utf-8", errors="replace")
+        if not name:
+            continue
+        symbols.append(
+            {
+                "name": name,
+                "line": node.start_point[0] + 1,
+                "kind": tag.split(".", 1)[1],
+            }
+        )
+    return symbols

honestcode/structure/relations.py

@@ -0,0 +1,47 @@
+"""Relation types and shared data structures for structural code analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+__all__ = ["RelationType", "StructEdge", "ParseResult"]
+
+
+class RelationType(Enum):
+    DEF_CALL = "def_call"
+    VAR_DEF_USE = "var_def_use"
+    AST_PARENT_CHILD = "ast_parent_child"
+    IMPORT = "import"
+    IMPORT_REF = "import_ref"
+    SAME_SCOPE = "same_scope"
+    CROSS_FILE_REF = "cross_file_ref"  # def in file_a -> call in file_b
+
+
+@dataclass(frozen=True)
+class StructEdge:
+    src_start: int
+    src_end: int
+    tgt_start: int
+    tgt_end: int
+    relation_type: str
+    name: str | None = None
+    # For cross-file edges: which file the source/target belongs to
+    src_file: str | None = None
+    tgt_file: str | None = None
+
+
+@dataclass
+class ParseResult:
+    edges: list[StructEdge]
+    func_defs: dict[str, tuple[int, int]]
+    class_defs: dict[str, tuple[int, int]]
+    var_defs: dict[str, tuple[int, int]]
+    imports: set[str]
+    # Cross-file: symbols imported from / exported to other files
+    imported_symbols: dict[str, str] | None = None  # name -> source_module
+    exported_symbols: set[str] | None = None  # names defined here, usable by others
+    # class qname -> syntactic base names (dotted, as written). Recorded at
+    # parse time so the symbol index can answer "is any class a subclass of
+    # X" without re-parsing every class-defining file per verification.
+    class_bases: dict[str, list[str]] | None = None

honestcode/structure/utils.py

@@ -0,0 +1,262 @@
+"""Shared AST utilities for HonestCode."""
+
+from __future__ import annotations
+
+import ast
+import importlib
+import importlib.util
+import sys
+import time
+import tokenize
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+__all__ = [
+    "annotation_name",
+    "call_base",
+    "call_name",
+    "importable_root",
+    "iter_python_files",
+    "module_name_for",
+    "prune_cache_files",
+    "read_python_source",
+    "stdlib_resolves",
+    "stdlib_roots",
+]
+
+
+@lru_cache(maxsize=1)
+def stdlib_roots() -> frozenset[str]:
+    """Top-level module names shipped with the interpreter.
+
+    Used to trust imports from the standard library: ``from typing import
+    TypeVar`` cannot be an invented symbol, but without this the verifier
+    rejected every stdlib import whose package was not in the dependency list
+    and reported real code as hallucinated.
+    """
+    names = getattr(sys, "stdlib_module_names", None)
+    if names:
+        return frozenset(names)
+    return frozenset(sys.builtin_module_names)
+
+
+@lru_cache(maxsize=4096)
+def stdlib_resolves(dotted: str) -> bool | None:
+    """Whether *dotted* (e.g. ``typing.TypeVar``) resolves inside the stdlib.
+
+    Returns ``True`` when the attribute exists, ``False`` when the module can
+    be imported but demonstrably lacks it (an invented stdlib symbol), and
+    ``None`` when the question cannot be answered on this platform — callers
+    must then stay silent rather than guess. The standard library is real,
+    importable code, so unlike third-party packages it can be checked exactly;
+    only stdlib-only names are ever imported here.
+    """
+    parts = dotted.split(".")
+    if not parts or not parts[0] or parts[0] not in stdlib_roots():
+        return None
+
+    obj = None
+    consumed = 0
+    # Import the longest importable module prefix: ``urllib.parse.urlparse``
+    # needs ``import urllib.parse`` — a getattr walk from ``urllib`` alone
+    # would miss the submodule.
+    for i in range(len(parts), 0, -1):
+        prefix = ".".join(parts[:i])
+        try:
+            obj = importlib.import_module(prefix)
+            consumed = i
+            break
+        except ImportError:
+            continue
+        except Exception:  # noqa: BLE001 - broken stdlib module, cannot judge
+            return None
+    if obj is None:
+        return None
+
+    for part in parts[consumed:]:
+        try:
+            obj = getattr(obj, part)
+        except AttributeError:
+            return False
+        except Exception:  # noqa: BLE001 - property/module hook misbehaving
+            return None
+    return True
+
+
+@lru_cache(maxsize=2048)
+def importable_root(name: str) -> bool:
+    """Whether the top-level module *name* is importable in this interpreter.
+
+    Used to recognise an undeclared third-party import root as real code: the
+    package exists in the environment even though no manifest declares it
+    (``from requests import get`` in a project whose ``requirements.txt`` only
+    lists pyyaml is an undeclared dependency, not a hallucination). Only the
+    top-level name is ever probed, and ``find_spec`` does not execute the
+    module — parent packages are not imported either.
+    """
+    if not name or not name.isidentifier():
+        return False
+    if name in stdlib_roots():
+        return True
+    try:
+        return importlib.util.find_spec(name) is not None
+    except (ImportError, ValueError, AttributeError, TypeError, OSError):
+        return False
+
+
+# Directories that never contain project source worth indexing. Hidden
+# directories (``.venv``, ``.git``, ``.tox``, ...) are skipped by prefix, and the
+# named ones below cover the common non-hidden artifact trees. Without this,
+# following the README's own development setup (``python -m venv .venv``) made
+# every scan index the entire virtual environment.
+_SKIP_DIR_NAMES = frozenset(
+    {
+        "__pycache__",
+        "node_modules",
+        "site-packages",
+        "dist-packages",
+        "venv",
+        "build",
+        "dist",
+        "htmlcov",
+    }
+)
+
+
+def _is_skipped_part(part: str) -> bool:
+    return part.startswith(".") or part in _SKIP_DIR_NAMES or part.endswith(".egg-info")
+
+
+def iter_python_files(root: Path | str) -> Iterator[Path]:
+    """Yield every indexable ``.py`` file under *root*, sorted by path.
+
+    Skips hidden directories (which covers ``.venv``/``.git``/``.tox`` and the
+    other tool caches), virtual environments and build artifacts. This is the
+    single traversal used by the symbol index, the call graph, the watcher and
+    the MCP tools so their notions of "the project's files" cannot drift apart.
+    """
+    root = Path(root)
+    for path in sorted(root.rglob("*.py")):
+        try:
+            rel = path.relative_to(root)
+        except ValueError:
+            continue
+        if any(_is_skipped_part(part) for part in rel.parts[:-1]):
+            continue
+        if path.name.startswith(".") or path.name in _SKIP_DIR_NAMES:
+            continue
+        yield path
+
+
+def read_python_source(path: Path | str) -> str | None:
+    """Read Python source honouring its PEP 263 coding declaration.
+
+    ``Path.read_text(encoding="utf-8")`` raises on any legally non-UTF-8 source
+    file, and a single such file used to abort an entire project index build.
+    ``tokenize.open`` decodes exactly what the interpreter itself would, and a
+    genuinely unreadable file returns ``None`` so callers can skip it instead of
+    failing the scan.
+    """
+    try:
+        with tokenize.open(str(path)) as handle:
+            return handle.read()
+    except (OSError, SyntaxError, UnicodeDecodeError, LookupError):
+        return None
+
+
+def prune_cache_files(
+    directory: Path | str, patterns: tuple[str, ...], max_age_days: int = 30
+) -> None:
+    """Delete cache files matching *patterns* that have not been touched recently.
+
+    Symbol/graph caches are stored one file per project root and are entirely
+    regenerable. Without a bound they accumulate one entry per temporary or
+    abandoned project forever. Only genuinely old files are removed, so an
+    active project's cache is never collected; a deletion that loses a race
+    with another process is ignored.
+    """
+    directory = Path(directory)
+    if not directory.is_dir():
+        return
+    cutoff = time.time() - max_age_days * 86400
+    for pattern in patterns:
+        for path in directory.glob(pattern):
+            try:
+                if path.is_file() and path.stat().st_mtime < cutoff:
+                    path.unlink()
+            except OSError:
+                continue
+
+
+def call_name(node: ast.expr) -> str | None:
+    """Return a dotted name for a call target (e.g. ``obj.method``).
+
+    Returns ``None`` for complex expressions (e.g. ``(a + b).foo()``).
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parts: list[str] = []
+        current: ast.expr = node
+        while isinstance(current, ast.Attribute):
+            parts.append(current.attr)
+            current = current.value
+        if isinstance(current, ast.Name):
+            parts.append(current.id)
+            return ".".join(reversed(parts))
+    return None
+
+
+def annotation_name(node: ast.expr) -> str | None:
+    """Return a dotted name for an annotation (handles string annotations).
+
+    Lives here rather than in ``verify.surface`` so the symbol index can use
+    it too: recording class base names at index time is what keeps
+    ``may_be_subclassed`` from parsing the whole project on every scan.
+    """
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        parts: list[str] = []
+        cur: ast.expr = node
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr)
+            cur = cur.value
+        if isinstance(cur, ast.Name):
+            parts.append(cur.id)
+            return ".".join(reversed(parts))
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        # ``from __future__ import annotations`` stores annotations verbatim.
+        text = node.value.strip()
+        if text.replace(".", "").replace("_", "").isidentifier():
+            return text
+    if isinstance(node, ast.Subscript):  # Optional[UserClient], list[UserClient], ...
+        return annotation_name(node.value)
+    return None
+
+
+def call_base(name: str) -> str:
+    """Return the first component of a dotted name."""
+    return name.split(".")[0]
+
+
+def module_name_for(path: Path, root: Path) -> str:
+    """Infer a dotted module name for *path* relative to *root*.
+
+    Only strips the ``src`` prefix when it is a standalone directory component
+    (i.e. the standard ``src`` layout) and there are further path segments.
+    """
+    try:
+        rel = path.resolve().relative_to(root.resolve())
+    except ValueError:
+        rel = path
+    parts = list(rel.with_suffix("").parts)
+    if len(parts) > 1 and parts[0] == "src":
+        parts = parts[1:]
+    if parts and parts[-1] == "__init__":
+        parts.pop()
+    return ".".join(parts)

honestcode/verify/__init__.py

@@ -0,0 +1,19 @@
+"""Repository grounding — the deterministic core of HonestCode.
+
+Everything an AI agent writes is a claim about the repository it is working in.
+This package checks those claims against the repository itself:
+
+* :mod:`honestcode.verify.surface`   reconstructs a class's member surface
+* :mod:`honestcode.verify.verify`    walks call sites and resolves receivers
+* :mod:`honestcode.verify.evidence`  emits the agent-facing protocol
+
+No LLM calls, no network, no heuristics that cannot be explained.
+"""
+
+from honestcode.verify.evidence import (
+    Finding,
+    build_report,
+    render_text,
+)
+
+__all__ = ["Finding", "build_report", "render_text"]