descry-codegraph 0.1.0__py3-none-any.whl

descry/__init__.py

@@ -0,0 +1,4 @@
+"""Descry — Codebase knowledge graph: polyglot indexer, semantic search, call-graph analysis."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

descry/_env.py

@@ -0,0 +1,30 @@
+"""Subprocess environment sanitization.
+
+Filters environment variables matching known credential patterns before
+passing env to subprocess calls (rust-analyzer, scip-typescript, git,
+ast-grep, descry.generate). Keeps tooling vars (RUSTUP_*, CARGO_*,
+GITHUB_WORKSPACE, AWS_REGION, etc.) intact.
+"""
+
+import os
+import re
+
+
+_SECRET_PATTERNS = re.compile(
+    r"(?i)("
+    r"secret|token|password|passphrase|credential|"
+    r"api[_-]?key|private[_-]?key|ssh[_-]?key|"
+    r"aws[_-](?:access|secret|session|security)|"
+    r"github[_-](?:token|pat|oauth)|"
+    r"openai[_-]|anthropic[_-]|"
+    r"gcp[_-]|azure[_-](?:storage|subscription|tenant|client)[_-]|"
+    r"stripe[_-]|slack[_-]|"
+    r"sentry[_-]|_dsn$|"
+    r"(?:database|redis|mongodb?|postgres|amqp|mysql)[_-]?(?:url|uri)$"
+    r")"
+)
+
+
+def safe_env() -> dict[str, str]:
+    """Return os.environ minus variables matching credential patterns."""
+    return {k: v for k, v in os.environ.items() if not _SECRET_PATTERNS.search(k)}

descry/_graph.py

@@ -0,0 +1,36 @@
+"""Graph schema versioning.
+
+Centralized load helper for codebase_graph.json with schema_version check.
+All callers that deserialize the graph should use load_graph_with_schema to
+ensure they reject out-of-date graphs instead of silently producing wrong
+results.
+"""
+
+import json
+from pathlib import Path
+
+
+CURRENT_SCHEMA = 1
+
+
+class GraphSchemaError(Exception):
+    """Raised when a graph file's schema_version does not match CURRENT_SCHEMA."""
+
+
+def load_graph_with_schema(path: Path | str) -> dict:
+    """Load a codebase graph JSON file and verify its schema_version.
+
+    Raises:
+        GraphSchemaError: if schema_version is missing or mismatched.
+        FileNotFoundError: if path does not exist.
+        json.JSONDecodeError: if path is not valid JSON.
+    """
+    with open(path) as f:
+        data = json.load(f)
+    ver = data.get("schema_version")
+    if ver != CURRENT_SCHEMA:
+        raise GraphSchemaError(
+            f"Graph schema version {ver!r} (expected {CURRENT_SCHEMA}); "
+            f"run 'descry index' to rebuild."
+        )
+    return data

descry/ast_grep.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""
+ast-grep based CALLS extraction for improved accuracy.
+
+Uses tree-sitter via ast-grep to find function calls with higher precision
+than regex-based detection. Handles:
+- Method chaining: foo.bar().baz()
+- Generic calls: Vec::<T>::new()
+- Closures: |x| process(x)
+- Macro invocations: vec![], println!()
+"""
+
+import json
+import subprocess
+from typing import Iterator
+
+from descry._env import safe_env
+
+
+def extract_calls_rust(file_path: str) -> Iterator[dict]:
+    """Extract function calls from a Rust file using ast-grep.
+
+    Yields dicts with:
+        - callee: str - function/method name being called
+        - lineno: int - line number
+        - full_text: str - full call expression text
+
+    Uses multiple patterns to capture:
+    - Direct calls: function(args)
+    - Method calls: receiver.method(args)
+    - Qualified calls: Type::method(args)
+    """
+    # Patterns to match different call types
+    patterns = [
+        "$FUNC($$$ARGS)",  # Direct function calls
+        "$RECEIVER.$METHOD($$$ARGS)",  # Method calls on expressions
+        "$RECEIVER.$METHOD()",  # No-arg method calls
+    ]
+
+    seen = set()  # Deduplicate by (lineno, callee)
+
+    for pattern in patterns:
+        try:
+            result = subprocess.run(
+                # `--json` first so `--` terminates options cleanly and the
+                # following `file_path` cannot be mis-parsed as a flag even
+                # if a local source file literally begins with `-`.
+                ["sg", "run", "-p", pattern, "-l", "rust", "--json", "--", file_path],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env=safe_env(),
+            )
+
+            if result.returncode != 0:
+                continue
+
+            matches = json.loads(result.stdout) if result.stdout else []
+
+            for match in matches:
+                meta = match.get("metaVariables", {}).get("single", {})
+
+                # Try METHOD first (for method calls), then FUNC (for direct calls)
+                func_meta = meta.get("METHOD") or meta.get("FUNC", {})
+                func_name = func_meta.get("text", "") if func_meta else ""
+
+                if not func_name:
+                    continue
+
+                # Skip malformed matches - ast-grep can capture entire method chains
+                # as the "function" when matching builder patterns like Router::new().merge().layer()
+                if "\n" in func_name or len(func_name) > 100:
+                    continue
+
+                # Skip control flow keywords that look like calls
+                if func_name in ("if", "for", "while", "match", "loop", "return"):
+                    continue
+
+                # Skip common macros (they end with !)
+                if func_name.endswith("!"):
+                    continue
+
+                # ast-grep uses 0-based line numbers, convert to 1-based
+                lineno = match.get("range", {}).get("start", {}).get("line", 0) + 1
+
+                # Deduplicate
+                key = (lineno, func_name)
+                if key in seen:
+                    continue
+                seen.add(key)
+
+                # For method calls, include receiver context if it's a type
+                receiver_meta = meta.get("RECEIVER", {})
+                receiver_text = receiver_meta.get("text", "") if receiver_meta else ""
+
+                # If receiver looks like a type (Self, starts with uppercase), qualify the call
+                if receiver_text in ("self", "Self") or (
+                    receiver_text
+                    and receiver_text[0].isupper()
+                    and "::" not in func_name
+                ):
+                    qualified_name = f"{receiver_text}.{func_name}"
+                else:
+                    qualified_name = func_name
+
+                yield {
+                    "callee": qualified_name,
+                    "lineno": lineno,
+                    "full_text": match.get("text", ""),
+                }
+
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
+            continue
+
+
+def extract_calls_typescript(file_path: str) -> Iterator[dict]:
+    """Extract function calls from a TypeScript file using ast-grep.
+
+    Yields dicts with:
+        - callee: str - function/method name being called
+        - lineno: int - line number
+        - full_text: str - full call expression text
+
+    Uses multiple patterns to capture:
+    - Direct calls: function(args)
+    - Method calls: receiver.method(args)
+    - Chained calls: obj.foo().bar()
+    """
+    # Patterns to match different call types
+    patterns = [
+        "$FUNC($$$ARGS)",  # Direct function calls
+        "$RECEIVER.$METHOD($$$ARGS)",  # Method calls on expressions
+        "$RECEIVER.$METHOD()",  # No-arg method calls
+    ]
+
+    seen = set()  # Deduplicate by (lineno, callee)
+
+    for pattern in patterns:
+        try:
+            result = subprocess.run(
+                # See note in Rust branch re: `--` separator for safety.
+                [
+                    "sg",
+                    "run",
+                    "-p",
+                    pattern,
+                    "-l",
+                    "typescript",
+                    "--json",
+                    "--",
+                    file_path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env=safe_env(),
+            )
+
+            if result.returncode != 0:
+                continue
+
+            matches = json.loads(result.stdout) if result.stdout else []
+
+            for match in matches:
+                meta = match.get("metaVariables", {}).get("single", {})
+
+                # Try METHOD first (for method calls), then FUNC (for direct calls)
+                func_meta = meta.get("METHOD") or meta.get("FUNC", {})
+                func_name = func_meta.get("text", "") if func_meta else ""
+
+                if not func_name:
+                    continue
+
+                # Skip control flow and common JS patterns
+                if func_name in (
+                    "if",
+                    "for",
+                    "while",
+                    "switch",
+                    "catch",
+                    "function",
+                    "class",
+                    "return",
+                    "await",
+                    "new",
+                ):
+                    continue
+
+                # ast-grep uses 0-based line numbers, convert to 1-based
+                lineno = match.get("range", {}).get("start", {}).get("line", 0) + 1
+
+                # Deduplicate
+                key = (lineno, func_name)
+                if key in seen:
+                    continue
+                seen.add(key)
+
+                yield {
+                    "callee": func_name,
+                    "lineno": lineno,
+                    "full_text": match.get("text", ""),
+                }
+
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
+            continue
+
+
+def is_ast_grep_available() -> bool:
+    """Check if ast-grep (sg) is available on the system."""
+    try:
+        result = subprocess.run(
+            ["sg", "--version"], capture_output=True, timeout=5, env=safe_env()
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+# Cache the availability check
+_AST_GREP_AVAILABLE = None
+
+
+def ast_grep_available() -> bool:
+    """Cached check for ast-grep availability."""
+    global _AST_GREP_AVAILABLE
+    if _AST_GREP_AVAILABLE is None:
+        _AST_GREP_AVAILABLE = is_ast_grep_available()
+    return _AST_GREP_AVAILABLE
+
+
+def extract_imports_typescript(file_path: str) -> dict:
+    """Extract import declarations from a TypeScript file using ast-grep.
+
+    Returns a dict with:
+        - imports: dict mapping local names to (module_path, import_type)
+        - namespaces: dict mapping namespace alias to module_path
+
+    Import types:
+        - "named": import { foo } from 'module'
+        - "default": import foo from 'module'
+        - "namespace": import * as foo from 'module'
+        - "type": import type { Foo } from 'module'
+    """
+    result = {
+        "imports": {},  # local_name -> (module_path, import_type)
+        "namespaces": {},  # alias -> module_path
+    }
+
+    # Pattern 1: Named imports - import { foo, bar as baz } from 'module'
+    patterns = [
+        # Named imports
+        ("import { $$$IMPORTS } from $SOURCE", "named"),
+        # Default import
+        ("import $DEFAULT from $SOURCE", "default"),
+        # Namespace import
+        ("import * as $ALIAS from $SOURCE", "namespace"),
+        # Type-only imports
+        ("import type { $$$TYPES } from $SOURCE", "type"),
+        # Default with named: import Default, { named } from 'module'
+        ("import $DEFAULT, { $$$NAMED } from $SOURCE", "default_named"),
+    ]
+
+    for pattern, import_type in patterns:
+        try:
+            proc_result = subprocess.run(
+                # See note in Rust branch re: `--` separator for safety.
+                [
+                    "sg",
+                    "run",
+                    "-p",
+                    pattern,
+                    "-l",
+                    "typescript",
+                    "--json",
+                    "--",
+                    file_path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env=safe_env(),
+            )
+
+            if proc_result.returncode != 0:
+                continue
+
+            matches = json.loads(proc_result.stdout) if proc_result.stdout else []
+
+            for match in matches:
+                meta = match.get("metaVariables", {})
+                single = meta.get("single", {})
+                multi = meta.get("multi", {})
+
+                # Extract source module
+                source_meta = single.get("SOURCE", {})
+                source = source_meta.get("text", "").strip("'\"")
+                if not source:
+                    continue
+
+                if import_type == "namespace":
+                    # import * as alias from 'module'
+                    alias_meta = single.get("ALIAS", {})
+                    alias = alias_meta.get("text", "")
+                    if alias:
+                        result["namespaces"][alias] = source
+                        result["imports"][alias] = (source, "namespace")
+
+                elif import_type == "default":
+                    # import Default from 'module'
+                    default_meta = single.get("DEFAULT", {})
+                    default_name = default_meta.get("text", "")
+                    if default_name:
+                        result["imports"][default_name] = (source, "default")
+
+                elif import_type in ("named", "type"):
+                    # import { foo, bar as baz } from 'module'
+                    imports_meta = (
+                        multi.get("IMPORTS", [])
+                        if import_type == "named"
+                        else multi.get("TYPES", [])
+                    )
+                    for imp in imports_meta:
+                        text = imp.get("text", "").strip()
+                        if not text:
+                            continue
+                        # Handle aliased imports: "foo as bar"
+                        if " as " in text:
+                            parts = text.split(" as ")
+                            alias = parts[1].strip()
+                            result["imports"][alias] = (source, import_type)
+                        else:
+                            result["imports"][text] = (source, import_type)
+
+                elif import_type == "default_named":
+                    # import Default, { named } from 'module'
+                    default_meta = single.get("DEFAULT", {})
+                    default_name = default_meta.get("text", "")
+                    if default_name:
+                        result["imports"][default_name] = (source, "default")
+
+                    named_meta = multi.get("NAMED", [])
+                    for imp in named_meta:
+                        text = imp.get("text", "").strip()
+                        if not text:
+                            continue
+                        if " as " in text:
+                            parts = text.split(" as ")
+                            alias = parts[1].strip()
+                            result["imports"][alias] = (source, "named")
+                        else:
+                            result["imports"][text] = (source, "named")
+
+        except (subprocess.TimeoutExpired, json.JSONDecodeError, FileNotFoundError):
+            continue
+
+    return result
+
+
+def extract_imports_typescript_batch(file_paths: list) -> dict:
+    """Extract imports from multiple TypeScript files efficiently.
+
+    Processes files individually but caches results for repeated calls.
+
+    Args:
+        file_paths: List of file paths to process
+
+    Returns:
+        Dict mapping file paths to their import data:
+        {
+            "path/to/file.ts": {
+                "imports": {"name": ("module", "type")},
+                "namespaces": {"alias": "module"},
+            }
+        }
+    """
+    results = {}
+    for file_path in file_paths:
+        try:
+            results[file_path] = extract_imports_typescript(file_path)
+        except Exception:
+            results[file_path] = {"imports": {}, "namespaces": {}}
+    return results