descry-codegraph 0.1.0__py3-none-any.whl

descry/scip/support.py

@@ -0,0 +1,174 @@
+"""SCIP support with auto-discovery for multiple languages.
+
+Provides functions to detect SCIP indexer availability and manage
+SCIP-based symbol resolution for improved descry call resolution.
+
+SCIP (Source Code Index Protocol) is a format from Sourcegraph that
+provides type-aware symbol information from language servers.
+
+Supported indexers:
+- rust-analyzer: Rust
+- scip-typescript: TypeScript, JavaScript
+- scip-python: Python
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+from typing import TYPE_CHECKING
+
+from descry._env import safe_env
+
+if TYPE_CHECKING:
+    from typing import Dict
+
+logger = logging.getLogger(__name__)
+
+# Global state (lazy-initialized)
+_indexer_cache: Dict[str, dict] = {}
+
+
+def _check_indexer(name: str, command: str, version_flag: str = "--version") -> dict:
+    """Check if an indexer is available.
+
+    Args:
+        name: Indexer name for logging
+        command: Command to check for
+        version_flag: Flag to get version info
+
+    Returns:
+        Dict with available, path, version keys
+    """
+    result = {"available": False, "path": None, "version": None}
+
+    path = shutil.which(command)
+    if path:
+        try:
+            proc = subprocess.run(
+                [path, version_flag],
+                capture_output=True,
+                text=True,
+                timeout=10,
+                env=safe_env(),
+            )
+            if proc.returncode == 0:
+                result["available"] = True
+                result["path"] = path
+                result["version"] = proc.stdout.strip() or proc.stderr.strip()
+                logger.debug(f"SCIP: {name} available at {path}")
+            else:
+                logger.debug(f"SCIP: {name} found but failed to run")
+        except subprocess.TimeoutExpired:
+            logger.debug(f"SCIP: {name} version check timed out")
+        except (OSError, FileNotFoundError) as e:
+            logger.debug(f"SCIP: {name} check failed: {e}")
+    else:
+        logger.debug(f"SCIP: {name} not found in PATH")
+
+    return result
+
+
+def rust_analyzer_available() -> bool:
+    """Check if rust-analyzer is available for Rust SCIP generation."""
+    if os.environ.get("DESCRY_NO_SCIP"):
+        return False
+
+    if "rust-analyzer" not in _indexer_cache:
+        _indexer_cache["rust-analyzer"] = _check_indexer(
+            "rust-analyzer", "rust-analyzer", "--version"
+        )
+    return _indexer_cache["rust-analyzer"]["available"]
+
+
+def scip_typescript_available() -> bool:
+    """Check if scip-typescript is available for TypeScript/JavaScript SCIP generation."""
+    if os.environ.get("DESCRY_NO_SCIP"):
+        return False
+
+    if "scip-typescript" not in _indexer_cache:
+        _indexer_cache["scip-typescript"] = _check_indexer(
+            "scip-typescript", "scip-typescript", "--version"
+        )
+    return _indexer_cache["scip-typescript"]["available"]
+
+
+def scip_python_available() -> bool:
+    """Check if scip-python is available for Python SCIP generation.
+
+    scip-python is a Sourcegraph-maintained indexer distributed via npm
+    (@sourcegraph/scip-python) that installs a `scip-python` binary.
+    """
+    if os.environ.get("DESCRY_NO_SCIP"):
+        return False
+
+    if "scip-python" not in _indexer_cache:
+        _indexer_cache["scip-python"] = _check_indexer(
+            "scip-python", "scip-python", "--version"
+        )
+    return _indexer_cache["scip-python"]["available"]
+
+
+def scip_available() -> bool:
+    """Check if any SCIP indexer is available (for backwards compatibility).
+
+    Returns:
+        True if at least one SCIP indexer is available.
+    """
+    if os.environ.get("DESCRY_NO_SCIP"):
+        return False
+
+    return (
+        rust_analyzer_available()
+        or scip_typescript_available()
+        or scip_python_available()
+    )
+
+
+def get_scip_status() -> dict:
+    """Return SCIP status for diagnostics.
+
+    Returns:
+        Dictionary with indexer availability information.
+    """
+    # Force availability checks
+    _ = rust_analyzer_available()
+    _ = scip_typescript_available()
+    _ = scip_python_available()
+
+    rust_info = _indexer_cache.get("rust-analyzer", {})
+    ts_info = _indexer_cache.get("scip-typescript", {})
+    py_info = _indexer_cache.get("scip-python", {})
+
+    return {
+        "available": scip_available(),
+        "disabled_by_env": bool(os.environ.get("DESCRY_NO_SCIP")),
+        "indexers": {
+            "rust-analyzer": {
+                "available": rust_info.get("available", False),
+                "path": rust_info.get("path"),
+                "version": rust_info.get("version"),
+            },
+            "scip-typescript": {
+                "available": ts_info.get("available", False),
+                "path": ts_info.get("path"),
+                "version": ts_info.get("version"),
+            },
+            "scip-python": {
+                "available": py_info.get("available", False),
+                "path": py_info.get("path"),
+                "version": py_info.get("version"),
+            },
+        },
+        # Backwards compatibility
+        "rust_analyzer_path": rust_info.get("path"),
+        "rust_analyzer_version": rust_info.get("version"),
+    }
+
+
+def reset_scip_state():
+    """Reset cached SCIP state. Useful for testing."""
+    global _indexer_cache
+    _indexer_cache = {}

descry/tree_sitter_parser.py

@@ -0,0 +1,356 @@
+"""Optional tree-sitter-backed parser for TypeScript / TSX / JavaScript.
+
+Activated when the ``descry-codegraph[ast]`` extra is installed (providing
+``tree-sitter``, ``tree-sitter-typescript``, ``tree-sitter-javascript``) and
+the user opts in via ``.descry.toml``::
+
+    [features]
+    use_tree_sitter_ts = true
+
+When enabled, ``generate.TSParser`` routes file parsing through this module
+and falls back to regex-only extraction for files the AST walker cannot
+process. When disabled or when the extra is missing, behaviour is
+indistinguishable from the regex-only baseline.
+
+This parser extracts the symbol shapes needed for the call graph:
+
+- ``class_declaration`` / ``interface_declaration`` / ``enum_declaration``
+- ``function_declaration``
+- ``method_definition`` (including ``get``/``set``) inside a class body
+- Arrow / function-expression RHS of ``const foo = …``
+- ``import_statement`` (ES) and ``call_expression`` (call edges)
+
+Anything the grammar hits as ``ERROR`` is surfaced to the caller; the
+BaseParser fallback can then re-run regex-only extraction on that file.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    import tree_sitter
+
+logger = logging.getLogger(__name__)
+
+
+# --- Optional dependency bootstrap -----------------------------------------
+
+_TS_AVAILABLE: bool | None = None
+_TS_LANGUAGE = None
+_TSX_LANGUAGE = None
+_JS_LANGUAGE = None
+
+
+def tree_sitter_available() -> bool:
+    """True iff tree-sitter + the TS/JS grammars are importable.
+
+    Result is cached on first call.
+    """
+    global _TS_AVAILABLE, _TS_LANGUAGE, _TSX_LANGUAGE, _JS_LANGUAGE
+    if _TS_AVAILABLE is not None:
+        return _TS_AVAILABLE
+    try:
+        import tree_sitter as ts
+        import tree_sitter_typescript as tsts
+        import tree_sitter_javascript as tsjs
+
+        _TS_LANGUAGE = ts.Language(tsts.language_typescript())
+        _TSX_LANGUAGE = ts.Language(tsts.language_tsx())
+        _JS_LANGUAGE = ts.Language(tsjs.language())
+        _TS_AVAILABLE = True
+    except Exception as exc:  # pragma: no cover - defensive
+        logger.debug("tree-sitter unavailable: %s", exc)
+        _TS_AVAILABLE = False
+    return _TS_AVAILABLE
+
+
+def _language_for(file_path: str | Path):
+    """Return the tree-sitter Language for a given TS/TSX/JS path, or None."""
+    if not tree_sitter_available():
+        return None
+    suffix = Path(file_path).suffix.lower()
+    if suffix == ".tsx":
+        return _TSX_LANGUAGE
+    if suffix in (".ts", ".d.ts"):
+        return _TS_LANGUAGE
+    if suffix in (".js", ".jsx", ".mjs", ".cjs"):
+        return _JS_LANGUAGE
+    return None
+
+
+# --- Symbol data classes ---------------------------------------------------
+
+
+SymbolKind = Literal[
+    "Class",
+    "Interface",
+    "Enum",
+    "Function",
+    "Method",
+    "Const",
+    "Import",
+    "Call",
+]
+
+
+@dataclass
+class ExtractedSymbol:
+    kind: SymbolKind
+    name: str
+    lineno: int
+    end_lineno: int
+    parent_name: str | None = None
+    signature: str | None = None
+    docstring: str | None = None
+    is_async: bool = False
+    is_static: bool = False
+    accessor: Literal["get", "set", None] | None = None
+    module: str | None = None  # populated for Import
+    imported_names: list[str] = field(default_factory=list)  # for Import
+
+
+@dataclass
+class ParseResult:
+    """Symbols + raw call sites extracted from a single file."""
+
+    symbols: list[ExtractedSymbol] = field(default_factory=list)
+    calls: list[tuple[int, str]] = field(default_factory=list)  # (lineno, callee)
+    had_errors: bool = False
+
+
+# --- Extractor -------------------------------------------------------------
+
+
+def _node_text(node: "tree_sitter.Node") -> str:
+    return node.text.decode("utf-8", errors="replace") if node.text else ""
+
+
+def _first_child_of_type(
+    node: "tree_sitter.Node", type_name: str
+) -> "tree_sitter.Node | None":
+    for child in node.named_children:
+        if child.type == type_name:
+            return child
+    return None
+
+
+def _line(node: "tree_sitter.Node") -> int:
+    return node.start_point[0] + 1
+
+
+def _end_line(node: "tree_sitter.Node") -> int:
+    return node.end_point[0] + 1
+
+
+def _walk(
+    node: "tree_sitter.Node",
+    on_enter,
+    parent_name: str | None = None,
+) -> None:
+    """Depth-first traversal delegating per-node logic to on_enter(node, parent_name).
+
+    on_enter returns the new `parent_name` to use for children (or None to
+    propagate the incoming one).
+    """
+    next_parent = on_enter(node, parent_name)
+    new_parent = next_parent if next_parent is not None else parent_name
+    for child in node.named_children:
+        _walk(child, on_enter, new_parent)
+
+
+def parse_file(content: bytes, file_path: str | Path) -> ParseResult | None:
+    """Parse a TS/TSX/JS source buffer and return extracted symbols + calls.
+
+    Returns None when tree-sitter isn't available or the extension is not
+    one we handle; the caller should fall back to regex in that case.
+    """
+    language = _language_for(file_path)
+    if language is None:
+        return None
+
+    import tree_sitter as ts
+
+    parser = ts.Parser(language)
+    tree = parser.parse(content)
+    root = tree.root_node
+
+    result = ParseResult()
+    result.had_errors = root.has_error
+
+    def on_enter(node, parent_name):
+        t = node.type
+        if t == "class_declaration":
+            # JS grammar uses `identifier` for class names; TS uses
+            # `type_identifier`. Try both so the parser works on both
+            # language variants without a grammar-specific branch.
+            name_node = _first_child_of_type(
+                node, "type_identifier"
+            ) or _first_child_of_type(node, "identifier")
+            name = _node_text(name_node) if name_node else "<anon>"
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Class",
+                    name=name,
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                )
+            )
+            return name
+
+        if t == "interface_declaration":
+            name_node = _first_child_of_type(node, "type_identifier")
+            name = _node_text(name_node) if name_node else "<anon>"
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Interface",
+                    name=name,
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                )
+            )
+            return name
+
+        if t == "enum_declaration":
+            name_node = _first_child_of_type(node, "identifier")
+            name = _node_text(name_node) if name_node else "<anon>"
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Enum",
+                    name=name,
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                )
+            )
+            return None
+
+        if t == "function_declaration":
+            name_node = _first_child_of_type(node, "identifier")
+            name = _node_text(name_node) if name_node else "<anon>"
+            is_async = any(c.type == "async" for c in node.children)
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Function",
+                    name=name,
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                    is_async=is_async,
+                )
+            )
+            return name
+
+        if t == "method_definition":
+            name_node = _first_child_of_type(node, "property_identifier")
+            name = _node_text(name_node) if name_node else "<anon>"
+            # Detect get/set/static/async modifiers as leading sibling tokens.
+            accessor = None
+            is_async = False
+            is_static = False
+            for child in node.children:
+                tt = child.type
+                if tt == "get":
+                    accessor = "get"
+                elif tt == "set":
+                    accessor = "set"
+                elif tt == "async":
+                    is_async = True
+                elif tt == "static":
+                    is_static = True
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Method",
+                    name=name,
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                    is_async=is_async,
+                    is_static=is_static,
+                    accessor=accessor,
+                )
+            )
+            return name
+
+        if t == "lexical_declaration":
+            # const foo = (...) => {...}  |  const foo = function(){}
+            for decl in node.named_children:
+                if decl.type != "variable_declarator":
+                    continue
+                name_node = _first_child_of_type(decl, "identifier")
+                if not name_node:
+                    continue
+                rhs = decl.named_children[-1] if decl.named_children else None
+                if rhs is None:
+                    continue
+                if rhs.type in ("arrow_function", "function_expression"):
+                    name = _node_text(name_node)
+                    result.symbols.append(
+                        ExtractedSymbol(
+                            kind="Function",
+                            name=name,
+                            lineno=_line(decl),
+                            end_lineno=_end_line(decl),
+                            parent_name=parent_name,
+                            is_async=any(c.type == "async" for c in rhs.children),
+                        )
+                    )
+            return None
+
+        if t == "import_statement":
+            source = _first_child_of_type(node, "string")
+            module = None
+            if source is not None:
+                txt = _node_text(source)
+                if len(txt) >= 2 and txt[0] in ("'", '"') and txt[-1] in ("'", '"'):
+                    module = txt[1:-1]
+            imported_names: list[str] = []
+            clause = _first_child_of_type(node, "import_clause")
+            if clause is not None:
+                # default + named + namespace
+                for child in clause.named_children:
+                    if child.type == "identifier":
+                        imported_names.append(_node_text(child))
+                    elif child.type == "named_imports":
+                        for spec in child.named_children:
+                            if spec.type == "import_specifier":
+                                ident = _first_child_of_type(spec, "identifier")
+                                if ident is not None:
+                                    imported_names.append(_node_text(ident))
+                    elif child.type == "namespace_import":
+                        ident = _first_child_of_type(child, "identifier")
+                        if ident is not None:
+                            imported_names.append(_node_text(ident))
+            result.symbols.append(
+                ExtractedSymbol(
+                    kind="Import",
+                    name=module or "<unknown>",
+                    lineno=_line(node),
+                    end_lineno=_end_line(node),
+                    parent_name=parent_name,
+                    module=module,
+                    imported_names=imported_names,
+                )
+            )
+            return None
+
+        if t == "call_expression":
+            callee_node = node.named_children[0] if node.named_children else None
+            if callee_node is None:
+                return None
+            if callee_node.type == "identifier":
+                result.calls.append((_line(node), _node_text(callee_node)))
+            elif callee_node.type == "member_expression":
+                # a.b.c(...) -> "a.b.c"
+                result.calls.append((_line(node), _node_text(callee_node)))
+            return None
+
+        return None
+
+    _walk(root, on_enter)
+    return result