shotgun-sh 0.2.29.dev2__py3-none-any.whl → 0.6.1.dev1__py3-none-any.whl

shotgun/codebase/core/change_detector.py

@@ -1,16 +1,21 @@
 """Change detection for incremental graph updates."""
 
+from __future__ import annotations
+
 import hashlib
 import os
 from enum import Enum
 from pathlib import Path
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import aiofiles
-import kuzu
 
+from shotgun.codebase.models import NodeLabel, RelationshipType
 from shotgun.logging_config import get_logger
 
+if TYPE_CHECKING:
+    import real_ladybug as kuzu
+
 logger = get_logger(__name__)
 
 
@@ -332,10 +337,10 @@ class ChangeDetector:
 
         # Query each TRACKS relationship type
         for node_type, rel_type in [
-            ("Module", "TRACKS_Module"),
-            ("Class", "TRACKS_Class"),
-            ("Function", "TRACKS_Function"),
-            ("Method", "TRACKS_Method"),
+            (NodeLabel.MODULE, RelationshipType.TRACKS_MODULE),
+            (NodeLabel.CLASS, RelationshipType.TRACKS_CLASS),
+            (NodeLabel.FUNCTION, RelationshipType.TRACKS_FUNCTION),
+            (NodeLabel.METHOD, RelationshipType.TRACKS_METHOD),
         ]:
             try:
                 result = self.conn.execute(

shotgun/codebase/core/errors.py

@@ -0,0 +1,159 @@
+"""Error classification for Kuzu database operations.
+
+This module provides error classification for Kuzu database errors,
+allowing the application to distinguish between different failure modes
+(lock contention, corruption, permissions, etc.) and handle each appropriately.
+"""
+
+from enum import StrEnum
+from pathlib import Path
+
+from pydantic import BaseModel
+
+
+class KuzuErrorType(StrEnum):
+    """Classification of Kuzu database errors."""
+
+    LOCKED = "locked"  # Another process has DB open
+    CORRUPTION = "corruption"  # Database file is invalid/corrupted
+    PERMISSION = "permission"  # Permission denied (transient)
+    MISSING = "missing"  # File not found
+    SCHEMA = "schema"  # Table doesn't exist (incomplete build)
+    TIMEOUT = "timeout"  # Operation timed out
+    UNKNOWN = "unknown"  # Unrecognized error
+
+
+def classify_kuzu_error(exception: Exception) -> KuzuErrorType:
+    """Classify a Kuzu RuntimeError by its message pattern.
+
+    Note: Kuzu only throws generic RuntimeError exceptions with no error codes
+    or custom exception types. String matching on the error message is the only
+    way to distinguish between different failure modes.
+
+    Args:
+        exception: The exception to classify
+
+    Returns:
+        KuzuErrorType indicating the category of error
+    """
+    error_str = str(exception)
+
+    # Lock contention - another process has the database open
+    if "Could not set lock" in error_str:
+        return KuzuErrorType.LOCKED
+
+    # True corruption - database file is invalid
+    if "Unable to open database" in error_str:
+        return KuzuErrorType.CORRUPTION
+    if "Reading past the end of the file" in error_str:
+        return KuzuErrorType.CORRUPTION
+    if "not a valid" in error_str.lower() and "database" in error_str.lower():
+        return KuzuErrorType.CORRUPTION
+
+    # C++ internal errors - likely corruption
+    if "unordered_map" in error_str:
+        return KuzuErrorType.CORRUPTION
+    if "key not found" in error_str.lower():
+        return KuzuErrorType.CORRUPTION
+    if "std::exception" in error_str:
+        return KuzuErrorType.CORRUPTION
+
+    # Permission errors - transient, may resolve on retry
+    if "Permission denied" in error_str:
+        return KuzuErrorType.PERMISSION
+
+    # Missing file - nothing to delete
+    if "No such file or directory" in error_str:
+        return KuzuErrorType.MISSING
+
+    # Schema errors - incomplete build, table doesn't exist
+    if "Table" in error_str and "does not exist" in error_str:
+        return KuzuErrorType.SCHEMA
+    if "Binder exception" in error_str and "does not exist" in error_str:
+        return KuzuErrorType.SCHEMA
+
+    return KuzuErrorType.UNKNOWN
+
+
+class DatabaseIssue(BaseModel):
+    """Structured information about a database issue.
+
+    Attributes:
+        graph_id: The ID of the affected graph
+        graph_path: Path to the database file
+        error_type: Classification of the error
+        message: Human-readable error message
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    graph_id: str
+    graph_path: Path
+    error_type: KuzuErrorType
+    message: str
+
+
+class KuzuDatabaseError(Exception):
+    """Base exception for Kuzu database errors with classification."""
+
+    def __init__(
+        self, message: str, graph_id: str, graph_path: str, error_type: KuzuErrorType
+    ) -> None:
+        super().__init__(message)
+        self.graph_id = graph_id
+        self.graph_path = graph_path
+        self.error_type = error_type
+
+
+class DatabaseLockedError(KuzuDatabaseError):
+    """Raised when the database is locked by another process."""
+
+    def __init__(self, graph_id: str, graph_path: str) -> None:
+        super().__init__(
+            f"Database '{graph_id}' is locked by another process. "
+            "Only one shotgun instance can access a codebase at a time.",
+            graph_id=graph_id,
+            graph_path=graph_path,
+            error_type=KuzuErrorType.LOCKED,
+        )
+
+
+class DatabaseCorruptedError(KuzuDatabaseError):
+    """Raised when the database is corrupted."""
+
+    def __init__(self, graph_id: str, graph_path: str, details: str = "") -> None:
+        message = f"Database '{graph_id}' is corrupted"
+        if details:
+            message += f": {details}"
+        super().__init__(
+            message,
+            graph_id=graph_id,
+            graph_path=graph_path,
+            error_type=KuzuErrorType.CORRUPTION,
+        )
+
+
+class DatabaseSchemaError(KuzuDatabaseError):
+    """Raised when the database schema is incomplete (interrupted build)."""
+
+    def __init__(self, graph_id: str, graph_path: str) -> None:
+        super().__init__(
+            f"Database '{graph_id}' has incomplete schema (build was interrupted)",
+            graph_id=graph_id,
+            graph_path=graph_path,
+            error_type=KuzuErrorType.SCHEMA,
+        )
+
+
+class DatabaseTimeoutError(KuzuDatabaseError):
+    """Raised when database operation times out."""
+
+    def __init__(self, graph_id: str, graph_path: str, timeout_seconds: float) -> None:
+        super().__init__(
+            f"Database '{graph_id}' operation timed out after {timeout_seconds}s. "
+            "This can happen with large codebases.",
+            graph_id=graph_id,
+            graph_path=graph_path,
+            error_type=KuzuErrorType.TIMEOUT,
+        )
+        self.timeout_seconds = timeout_seconds

shotgun/codebase/core/extractors/__init__.py

@@ -0,0 +1,23 @@
+"""Language-specific AST extraction framework.
+
+This module provides a Protocol-based architecture for extracting
+definitions, relationships, and metadata from source code ASTs.
+
+Usage:
+    from shotgun.codebase.core.extractors import get_extractor, SupportedLanguage
+
+    extractor = get_extractor(SupportedLanguage.PYTHON)
+    decorators = extractor.extract_decorators(node)
+"""
+
+from __future__ import annotations
+
+from .factory import get_extractor
+from .protocol import LanguageExtractor
+from .types import SupportedLanguage
+
+__all__ = [
+    "SupportedLanguage",
+    "LanguageExtractor",
+    "get_extractor",
+]

shotgun/codebase/core/extractors/base.py

@@ -0,0 +1,138 @@
+"""Base extractor with shared extraction logic."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+    from .types import SupportedLanguage
+
+
+class BaseExtractor(ABC):
+    """Abstract base class for language extractors.
+
+    Provides shared extraction logic that works across languages,
+    with abstract methods for language-specific operations.
+    """
+
+    @property
+    @abstractmethod
+    def language(self) -> SupportedLanguage:
+        """The language this extractor handles."""
+        ...
+
+    @abstractmethod
+    def extract_decorators(self, node: Node) -> list[str]:
+        """Extract decorators/attributes from a function or class node."""
+        ...
+
+    @abstractmethod
+    def extract_docstring(self, node: Node) -> str | None:
+        """Extract documentation string from a function or class node."""
+        ...
+
+    @abstractmethod
+    def extract_inheritance(self, class_node: Node) -> list[str]:
+        """Extract parent class names from a class definition."""
+        ...
+
+    @abstractmethod
+    def parse_call_node(self, call_node: Node) -> tuple[str | None, str | None]:
+        """Parse a call expression node to extract callee information."""
+        ...
+
+    @abstractmethod
+    def _class_definition_types(self) -> list[str]:
+        """Return node types that represent class definitions."""
+        ...
+
+    @abstractmethod
+    def _function_definition_types(self) -> list[str]:
+        """Return node types that represent function definitions."""
+        ...
+
+    def find_parent_class(self, func_node: Node, module_qn: str) -> str | None:
+        """Find the parent class of a function node.
+
+        Args:
+            func_node: The function definition AST node
+            module_qn: Module qualified name
+
+        Returns:
+            Qualified name of parent class, or None if not in a class
+        """
+        current = func_node.parent
+
+        while current:
+            if current.type in self._class_definition_types():
+                for child in current.children:
+                    if child.type == "identifier" and child.text:
+                        class_name = child.text.decode("utf-8")
+                        return f"{module_qn}.{class_name}"
+
+            current = current.parent
+
+        return None
+
+    def find_containing_function(self, node: Node, module_qn: str) -> str | None:
+        """Find the containing function/method of a node.
+
+        Args:
+            node: The AST node
+            module_qn: Module qualified name
+
+        Returns:
+            Qualified name of containing function, or None
+        """
+        current = node.parent
+
+        while current:
+            if current.type in self._function_definition_types():
+                for child in current.children:
+                    if child.type == "identifier" and child.text:
+                        func_name = child.text.decode("utf-8")
+
+                        parent_class = self.find_parent_class(current, module_qn)
+                        if parent_class:
+                            return f"{parent_class}.{func_name}"
+                        else:
+                            return f"{module_qn}.{func_name}"
+
+            current = current.parent
+
+        return None
+
+    def count_ast_nodes(self, node: Node) -> int:
+        """Count total AST nodes for metrics.
+
+        Args:
+            node: Root AST node
+
+        Returns:
+            Total node count
+        """
+        count = 1
+        for child in node.children:
+            count += self.count_ast_nodes(child)
+        return count
+
+    def _extract_full_name(self, node: Node, parts: list[str]) -> None:
+        """Recursively extract full qualified name from attribute access.
+
+        Args:
+            node: The AST node
+            parts: List to accumulate name parts (modified in place)
+        """
+        if node.type == "identifier" and node.text:
+            parts.insert(0, node.text.decode("utf-8"))
+        elif node.type == "attribute":
+            attr_node = node.child_by_field_name("attribute")
+            if attr_node and attr_node.text:
+                parts.insert(0, attr_node.text.decode("utf-8"))
+
+            obj_node = node.child_by_field_name("object")
+            if obj_node:
+                self._extract_full_name(obj_node, parts)

shotgun/codebase/core/extractors/factory.py

@@ -0,0 +1,63 @@
+"""Factory for creating language-specific extractors."""
+
+from __future__ import annotations
+
+from .protocol import LanguageExtractor
+from .types import SupportedLanguage
+
+# Cache of extractor instances (created lazily)
+_extractors: dict[SupportedLanguage, LanguageExtractor] = {}
+
+
+def get_extractor(language: SupportedLanguage | str) -> LanguageExtractor:
+    """Get the extractor for a language.
+
+    Args:
+        language: The language as enum or string
+
+    Returns:
+        The language extractor instance
+
+    Raises:
+        ValueError: If language is not supported
+    """
+    if isinstance(language, str):
+        language = SupportedLanguage(language)
+
+    if language not in _extractors:
+        _extractors[language] = _create_extractor(language)
+
+    return _extractors[language]
+
+
+def _create_extractor(language: SupportedLanguage) -> LanguageExtractor:
+    """Create a new extractor instance for the language.
+
+    Uses lazy imports to avoid loading all extractors at once.
+    """
+    match language:
+        case SupportedLanguage.PYTHON:
+            from .python.extractor import PythonExtractor
+
+            return PythonExtractor()
+        case SupportedLanguage.JAVASCRIPT:
+            from .javascript.extractor import JavaScriptExtractor
+
+            return JavaScriptExtractor()
+        case SupportedLanguage.TYPESCRIPT:
+            from .typescript.extractor import TypeScriptExtractor
+
+            return TypeScriptExtractor()
+        case SupportedLanguage.GO:
+            from .go.extractor import GoExtractor
+
+            return GoExtractor()
+        case SupportedLanguage.RUST:
+            from .rust.extractor import RustExtractor
+
+            return RustExtractor()
+
+
+def clear_extractor_cache() -> None:
+    """Clear the extractor cache (useful for testing)."""
+    _extractors.clear()

shotgun/codebase/core/extractors/go/__init__.py

@@ -0,0 +1,7 @@
+"""Go language extractor."""
+
+from __future__ import annotations
+
+from .extractor import GoExtractor
+
+__all__ = ["GoExtractor"]

shotgun/codebase/core/extractors/go/extractor.py

@@ -0,0 +1,122 @@
+"""Go language extractor implementation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shotgun.codebase.core.extractors.base import BaseExtractor
+from shotgun.codebase.core.extractors.types import SupportedLanguage
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+
+class GoExtractor(BaseExtractor):
+    """Extractor for Go source code."""
+
+    @property
+    def language(self) -> SupportedLanguage:
+        """The language this extractor handles."""
+        return SupportedLanguage.GO
+
+    def _class_definition_types(self) -> list[str]:
+        """Return node types that represent type definitions.
+
+        Go doesn't have classes but has type definitions and interfaces.
+        """
+        return ["type_declaration", "type_spec"]
+
+    def _function_definition_types(self) -> list[str]:
+        """Return node types that represent function definitions."""
+        return ["function_declaration", "method_declaration"]
+
+    def extract_decorators(self, node: Node) -> list[str]:
+        """Extract decorators from a function node.
+
+        Go doesn't have decorators. Returns empty list.
+
+        Args:
+            node: The AST node
+
+        Returns:
+            Empty list (Go has no decorators)
+        """
+        return []
+
+    def extract_docstring(self, node: Node) -> str | None:
+        """Extract godoc comment from a function or type node.
+
+        Args:
+            node: The AST node
+
+        Returns:
+            The godoc comment, or None if not present
+        """
+        prev_sibling = node.prev_named_sibling
+        if prev_sibling and prev_sibling.type == "comment":
+            comment_text = prev_sibling.text
+            if comment_text:
+                text = comment_text.decode("utf-8")
+                if text.startswith("//"):
+                    return text[2:].strip()
+        return None
+
+    def extract_inheritance(self, class_node: Node) -> list[str]:
+        """Extract embedded types from a struct or interface.
+
+        Go uses composition instead of inheritance.
+        This extracts embedded type names from struct/interface definitions.
+
+        Args:
+            class_node: The type definition AST node
+
+        Returns:
+            List of embedded type names
+        """
+        embedded: list[str] = []
+
+        for child in class_node.children:
+            if child.type == "struct_type":
+                field_list = child.child_by_field_name("fields")
+                if field_list:
+                    for field in field_list.children:
+                        if field.type == "field_declaration":
+                            if len(field.named_children) == 1:
+                                type_node = field.named_children[0]
+                                if (
+                                    type_node.type == "type_identifier"
+                                    and type_node.text
+                                ):
+                                    embedded.append(type_node.text.decode("utf-8"))
+            elif child.type == "interface_type":
+                for iface_child in child.children:
+                    if iface_child.type == "type_identifier" and iface_child.text:
+                        embedded.append(iface_child.text.decode("utf-8"))
+
+        return embedded
+
+    def parse_call_node(self, call_node: Node) -> tuple[str | None, str | None]:
+        """Parse a call expression node to extract callee information.
+
+        Args:
+            call_node: The call expression AST node
+
+        Returns:
+            Tuple of (callee_name, object_name)
+        """
+        callee_name = None
+        object_name = None
+
+        func_node = call_node.child_by_field_name("function")
+        if func_node:
+            if func_node.type == "identifier" and func_node.text:
+                callee_name = func_node.text.decode("utf-8")
+            elif func_node.type == "selector_expression":
+                operand = func_node.child_by_field_name("operand")
+                field = func_node.child_by_field_name("field")
+                if operand and operand.text:
+                    object_name = operand.text.decode("utf-8")
+                if field and field.text:
+                    callee_name = field.text.decode("utf-8")
+
+        return callee_name, object_name

shotgun/codebase/core/extractors/javascript/__init__.py

@@ -0,0 +1,7 @@
+"""JavaScript language extractor."""
+
+from __future__ import annotations
+
+from .extractor import JavaScriptExtractor
+
+__all__ = ["JavaScriptExtractor"]

shotgun/codebase/core/extractors/javascript/extractor.py

@@ -0,0 +1,132 @@
+"""JavaScript language extractor implementation."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shotgun.codebase.core.extractors.base import BaseExtractor
+from shotgun.codebase.core.extractors.types import SupportedLanguage
+
+if TYPE_CHECKING:
+    from tree_sitter import Node
+
+
+class JavaScriptExtractor(BaseExtractor):
+    """Extractor for JavaScript source code."""
+
+    @property
+    def language(self) -> SupportedLanguage:
+        """The language this extractor handles."""
+        return SupportedLanguage.JAVASCRIPT
+
+    def _class_definition_types(self) -> list[str]:
+        """Return node types that represent class definitions."""
+        return ["class_declaration", "class"]
+
+    def _function_definition_types(self) -> list[str]:
+        """Return node types that represent function definitions."""
+        return ["function_declaration", "method_definition", "arrow_function"]
+
+    def extract_decorators(self, node: Node) -> list[str]:
+        """Extract decorators from a function or class node.
+
+        JavaScript doesn't have native decorators (they're a proposal).
+        Returns empty list.
+
+        Args:
+            node: The AST node
+
+        Returns:
+            Empty list (JavaScript has no decorators)
+        """
+        return []
+
+    def extract_docstring(self, node: Node) -> str | None:
+        """Extract JSDoc comment from a function or class node.
+
+        Args:
+            node: The AST node
+
+        Returns:
+            The JSDoc content, or None if not present
+        """
+        prev_sibling = node.prev_named_sibling
+        if prev_sibling and prev_sibling.type == "comment":
+            comment_text = prev_sibling.text
+            if comment_text:
+                text = comment_text.decode("utf-8")
+                if text.startswith("/**"):
+                    text = text[3:]
+                    if text.endswith("*/"):
+                        text = text[:-2]
+                    return text.strip()
+        return None
+
+    def extract_inheritance(self, class_node: Node) -> list[str]:
+        """Extract parent class names from a class definition.
+
+        Args:
+            class_node: The class definition AST node
+
+        Returns:
+            List of parent class names
+        """
+        parent_names: list[str] = []
+
+        heritage = class_node.child_by_field_name("heritage")
+        if heritage:
+            for child in heritage.children:
+                if child.type == "identifier" and child.text:
+                    parent_names.append(child.text.decode("utf-8"))
+                elif child.type == "member_expression":
+                    parts: list[str] = []
+                    self._extract_member_expression(child, parts)
+                    if parts:
+                        parent_names.append(".".join(parts))
+
+        return parent_names
+
+    def parse_call_node(self, call_node: Node) -> tuple[str | None, str | None]:
+        """Parse a call expression node to extract callee information.
+
+        Args:
+            call_node: The call expression AST node
+
+        Returns:
+            Tuple of (callee_name, object_name)
+        """
+        callee_name = None
+        object_name = None
+
+        for child in call_node.children:
+            if child.type == "identifier" and child.text:
+                callee_name = child.text.decode("utf-8")
+                break
+            elif child.type == "member_expression":
+                obj_node = child.child_by_field_name("object")
+                prop_node = child.child_by_field_name("property")
+                if obj_node and obj_node.text:
+                    object_name = obj_node.text.decode("utf-8")
+                if prop_node and prop_node.text:
+                    callee_name = prop_node.text.decode("utf-8")
+                    break
+
+        return callee_name, object_name
+
+    def _extract_member_expression(self, node: Node, parts: list[str]) -> None:
+        """Recursively extract full name from member expression.
+
+        Args:
+            node: The AST node
+            parts: List to accumulate name parts (modified in place)
+        """
+        if node.type == "identifier" and node.text:
+            parts.insert(0, node.text.decode("utf-8"))
+        elif node.type == "member_expression":
+            prop_node = node.child_by_field_name("property")
+            if prop_node and prop_node.text:
+                parts.insert(0, prop_node.text.decode("utf-8"))
+
+            obj_node = node.child_by_field_name("object")
+            if obj_node:
+                self._extract_member_expression(obj_node, parts)