@ngocsangairvds/vsaf 3.2.14 → 3.2.15

package/tools/vds-scripts/lsp_orchestrator/src/vds_lsp_orchestrator/workspace_indexer.py

@@ -1,1037 +0,0 @@
-"""Tree-sitter based workspace indexer."""
-
-import fnmatch
-import logging
-import os
-import re
-
-# Import LSP models directly from models.py module (not models package)
-# Use sys.modules trick to avoid package conflict
-import sys
-import time
-from collections import defaultdict, deque
-from collections.abc import Callable
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from enum import StrEnum
-from pathlib import Path
-from threading import Lock
-from typing import Any, Protocol, runtime_checkable
-
-import tree_sitter_python
-from pydantic import BaseModel, ConfigDict
-from rich.console import Console
-from rich.progress import Progress
-from tree_sitter import Language, Node, Parser, Query, QueryCursor
-
-_models_py_path = Path(__file__).parent.parent / "models.py"
-if _models_py_path.exists():
-    import importlib.util
-
-    _spec = importlib.util.spec_from_file_location("vds_lsp_orchestrator._models", _models_py_path)
-    if _spec and _spec.loader:
-        _models_mod = importlib.util.module_from_spec(_spec)
-        sys.modules["vds_lsp_orchestrator._models"] = _models_mod
-        _spec.loader.exec_module(_models_mod)
-        Call = _models_mod.Call
-        SymbolInformation = _models_mod.SymbolInformation
-        SymbolKind = _models_mod.SymbolKind
-        SymbolLocation = _models_mod.SymbolLocation
-        WorkspaceIndex = _models_mod.WorkspaceIndex
-    else:
-        # Fallback: define proper stubs with correct type annotations
-        class SymbolKind(StrEnum):
-            FILE = "File"
-            MODULE = "Module"
-            NAMESPACE = "Namespace"
-            PACKAGE = "Package"
-            CLASS = "Class"
-            METHOD = "Method"
-            PROPERTY = "Property"
-            FIELD = "Field"
-            CONSTRUCTOR = "Constructor"
-            ENUM = "Enum"
-            INTERFACE = "Interface"
-            FUNCTION = "Function"
-            VARIABLE = "Variable"
-            CONSTANT = "Constant"
-            STRING = "String"
-            NUMBER = "Number"
-            BOOLEAN = "Boolean"
-            ARRAY = "Array"
-            OBJECT = "Object"
-            KEY = "Key"
-            NULL = "Null"
-            ENUM_MEMBER = "EnumMember"
-            STRUCT = "Struct"
-            EVENT = "Event"
-            OPERATOR = "Operator"
-            TYPE_PARAMETER = "TypeParameter"
-
-        class SymbolLocation(BaseModel):
-            model_config = ConfigDict(arbitrary_types_allowed=True)
-            file: str
-            line: int
-            column: int
-            end_line: int
-            end_column: int
-
-        class SymbolInformation(BaseModel):
-            model_config = ConfigDict(arbitrary_types_allowed=True)
-            name: str
-            kind: SymbolKind
-            location: SymbolLocation
-            container_name: str | None = None
-
-        class Call(BaseModel):
-            model_config = ConfigDict(arbitrary_types_allowed=True)
-            from_symbol: str
-            to_symbol: str
-            location: SymbolLocation
-
-        class WorkspaceIndex(BaseModel):
-            model_config = ConfigDict(arbitrary_types_allowed=True)
-            symbols: list[SymbolInformation] = []
-            calls: list[Call] = []
-            total_symbols: int = 0
-            timestamp: float = 0.0
-else:
-    # Last resort: define proper stubs
-    class SymbolKind(StrEnum):
-        FILE = "File"
-        MODULE = "Module"
-        NAMESPACE = "Namespace"
-        PACKAGE = "Package"
-        CLASS = "Class"
-        METHOD = "Method"
-        PROPERTY = "Property"
-        FIELD = "Field"
-        CONSTRUCTOR = "Constructor"
-        ENUM = "Enum"
-        INTERFACE = "Interface"
-        FUNCTION = "Function"
-        VARIABLE = "Variable"
-        CONSTANT = "Constant"
-        STRING = "String"
-        NUMBER = "Number"
-        BOOLEAN = "Boolean"
-        ARRAY = "Array"
-        OBJECT = "Object"
-        KEY = "Key"
-        NULL = "Null"
-        ENUM_MEMBER = "EnumMember"
-        STRUCT = "Struct"
-        EVENT = "Event"
-        OPERATOR = "Operator"
-        TYPE_PARAMETER = "TypeParameter"
-
-    class SymbolLocation(BaseModel):
-        model_config = ConfigDict(arbitrary_types_allowed=True)
-        file: str
-        line: int
-        column: int
-        end_line: int
-        end_column: int
-
-    class SymbolInformation(BaseModel):
-        model_config = ConfigDict(arbitrary_types_allowed=True)
-        name: str
-        kind: SymbolKind
-        location: SymbolLocation
-        container_name: str | None = None
-
-    class Call(BaseModel):
-        model_config = ConfigDict(arbitrary_types_allowed=True)
-        from_symbol: str
-        to_symbol: str
-        location: SymbolLocation
-
-    class WorkspaceIndex(BaseModel):
-        model_config = ConfigDict(arbitrary_types_allowed=True)
-        symbols: list[SymbolInformation] = []
-        calls: list[Call] = []
-        total_symbols: int = 0
-        timestamp: float = 0.0
-
-
-from .utils import extract_context, is_wsl2, is_wsl_path
-
-
-@runtime_checkable
-class IndexerConfig(Protocol):
-    """Protocol for workspace indexer configuration.
-
-    This protocol defines the expected interface for configuration objects
-    passed to WorkspaceIndexer. Using Protocol allows for duck-typing while
-    maintaining type safety.
-    """
-
-    def __getattr__(self, name: str) -> Any: ...  # pragma: no cover
-
-
-# Type alias for index function used in parallel processing
-IndexFileFunc = Callable[[Path], tuple[list[SymbolInformation], list[Call]]]
-
-# Type alias for context extraction result
-ContextResult = dict[str, str | int] | None
-
-console = Console()
-logger = logging.getLogger(__name__)
-
-# Default batch size for parallel indexing
-DEFAULT_BATCH_SIZE = 75
-# Default number of workers for parallel indexing
-DEFAULT_MAX_WORKERS = max(1, os.cpu_count() or 1)
-
-
-class WorkspaceIndexer:
-    """Fast Tree-sitter based workspace indexer."""
-
-    def __init__(self, root: Path, config: IndexerConfig | None = None):
-        self.root: Path = root
-        self.config: IndexerConfig | None = config
-        self.language: Language = Language(tree_sitter_python.language())
-        self.parser: Parser = Parser(self.language)
-
-        # WSL2 optimization detection
-        self.wsl_detected: bool = is_wsl2()
-        self.wsl_root_mount: bool | str = is_wsl_path(root) if self.wsl_detected else False
-        self.wsl_optimize: bool | None = None
-        if config:
-            self.wsl_optimize = getattr(config, "wsl_optimize", None)
-
-        # Auto-enable WSL optimization if detected and not explicitly disabled
-        if self.wsl_detected and self.wsl_root_mount and self.wsl_optimize is None:
-            logger.info("WSL2 with Windows filesystem detected - enabling optimization mode")
-            self.wsl_optimize = True
-        elif self.wsl_optimize is None:
-            self.wsl_optimize = False
-
-        # Log WSL status if optimization is enabled
-        if self.wsl_optimize:
-            if self.wsl_root_mount:
-                logger.warning(
-                    "Indexing files on Windows filesystem via WSL2 (/mnt/c/). "
-                    "Performance may be slower than native Linux filesystem.",
-                )
-            else:
-                logger.debug("WSL2 optimization enabled (native WSL filesystem)")
-
-        # Queries for symbol extraction
-        # Note: tree-sitter 0.22+ uses Query constructor, not language.query
-        self.class_query: Query = Query(
-            self.language,
-            """(class_definition
-                name: (identifier) @name
-            ) @class""",
-        )
-
-        self.function_query: Query = Query(
-            self.language,
-            """(function_definition
-                name: (identifier) @name
-            ) @function""",
-        )
-
-        self.identifier_query: Query = Query(
-            self.language,
-            """(identifier) @name""",
-        )
-
-        self.call_query: Query = Query(
-            self.language,
-            """(call
-                function: [
-                    (identifier) @function_call
-                    (attribute attribute: (identifier) @method_call)
-                ]
-            ) @call_site""",
-        )
-
-    def index_directory(
-        self,
-        force: bool = False,
-        progress: Progress | None = None,
-        parallel: bool = False,
-    ) -> WorkspaceIndex:
-        """Index entire directory with caching.
-
-        Args:
-            force: Force rebuild of index even if cache is valid
-            progress: Optional Rich Progress object for UI updates
-            parallel: Enable parallel indexing using ThreadPoolExecutor
-
-        Returns:
-            WorkspaceIndex containing symbols and calls
-
-        Note:
-            Parallel indexing uses ThreadPoolExecutor with batch processing.
-            Each worker thread creates its own Parser instance to avoid
-            thread-safety issues with tree-sitter. Results are combined
-            using thread-safe locks.
-        """
-        # Check cache
-        cache_dir = self.root / ".vds-lsp" / "cache"
-        if self.config and getattr(self.config, "cache_dir", None):
-            cache_dir = self.config.cache_dir
-
-        cache_file = cache_dir / "workspace_index.json"
-
-        # For WSL2 with Windows filesystem, prefer caching in WSL home for better performance
-        if self.wsl_optimize and self.wsl_root_mount:
-            wsl_cache_dir = Path.home() / ".cache" / "vds-lsp" / self.root.name
-            try:
-                wsl_cache_dir.mkdir(parents=True, exist_ok=True)
-                # Create symlink from project cache to WSL home cache
-                if not cache_dir.exists():
-                    _ = cache_dir.parent.mkdir(parents=True, exist_ok=True)
-                    _ = cache_dir.symlink_to(wsl_cache_dir)
-                    logger.debug(
-                        f"Created WSL-optimized cache symlink: {cache_dir} -> {wsl_cache_dir}"
-                    )
-                cache_file = wsl_cache_dir / "workspace_index.json"
-            except (OSError, RuntimeError) as exc:
-                logger.debug(f"Could not create WSL-optimized cache: {exc}")
-                # Fall back to standard cache location
-
-        # Simple cache invalidation: check if any python file is newer than cache
-        _current_time = time.time()
-        files = list(self.root.rglob("*.py"))
-        # Fix: Corrected list comprehension syntax
-        files = [f for f in files if not self._is_excluded(f)]
-
-        # If cache exists, check validity
-        if not force and cache_file.exists():
-            try:
-                cached = WorkspaceIndex.model_validate_json(cache_file.read_text())
-                cache_mtime = cache_file.stat().st_mtime
-                changed_files = [f for f in files if f.stat().st_mtime > cache_mtime]
-                current_rel = {f.relative_to(self.root).as_posix() for f in files}
-                cached_files = {
-                    *(sym.location.file for sym in cached.symbols),
-                    *(call.location.file for call in cached.calls),
-                }
-                removed_files = cached_files - current_rel
-
-                if not changed_files and not removed_files:
-                    return cached
-
-                changed_rel = {f.relative_to(self.root).as_posix() for f in changed_files}
-                if removed_files or changed_rel:
-                    cached.symbols = [
-                        sym
-                        for sym in cached.symbols
-                        if sym.location.file not in removed_files | changed_rel
-                    ]
-                    cached.calls = [
-                        call
-                        for call in cached.calls
-                        if call.location.file not in removed_files | changed_rel
-                    ]
-
-                for file_path in changed_files:
-                    try:
-                        file_symbols, file_calls = self._index_file(file_path)
-                        cached.symbols.extend(file_symbols)
-                        cached.calls.extend(file_calls)
-                    except Exception as exc:
-                        logger.debug("Failed to index %s: %s", file_path, exc)
-
-                cached.total_symbols = len(cached.symbols)
-                cached.timestamp = time.time()
-
-                try:
-                    _ = cache_dir.mkdir(parents=True, exist_ok=True)
-                    _ = cache_file.write_text(cached.model_dump_json(indent=2))
-                except Exception as exc:
-                    console.print(f"[yellow]Failed to save cache: {exc}[/yellow]")
-
-                return cached
-            except Exception as exc:
-                logger.debug("Cache load failed, rebuilding: %s", exc)
-
-        # Rebuild index
-        # console.print("[dim]Indexing workspace...[/dim]")
-        _start_time = time.time()
-        symbols: list[SymbolInformation] = []
-        calls: list[Call] = []
-
-        task_id = None
-        if progress:
-            task_id = progress.add_task("Indexing workspace", total=len(files))
-
-        if parallel and len(files) > DEFAULT_BATCH_SIZE:
-            # Parallel indexing with ThreadPoolExecutor
-            symbols, calls = self._index_files_parallel(
-                files,
-                progress=progress,
-                task_id=task_id,
-            )
-        else:
-            # Sequential indexing (original behavior)
-            for file_path in files:
-                try:
-                    file_symbols, file_calls = self._index_file(file_path)
-                    symbols.extend(file_symbols)
-                    calls.extend(file_calls)
-                except Exception as exc:
-                    logger.debug("Failed to index %s: %s", file_path, exc)
-                if progress and task_id is not None:
-                    progress.advance(task_id)
-
-        index = WorkspaceIndex(
-            symbols=symbols,
-            calls=calls,
-            total_symbols=len(symbols),
-            timestamp=time.time(),
-        )
-
-        # Save cache
-        try:
-            _ = cache_dir.mkdir(parents=True, exist_ok=True)
-            _ = cache_file.write_text(index.model_dump_json(indent=2))
-        except Exception as e:
-            console.print(f"[yellow]Failed to save cache: {e}[/yellow]")
-
-        return index
-
-    def get_document_symbols(self, file_path: Path) -> list[SymbolInformation]:
-        """Get symbols for a single document."""
-        try:
-            symbols, _ = self._index_file(file_path)
-            return symbols
-        except Exception as exc:
-            logger.debug("Failed to read document symbols for %s: %s", file_path, exc)
-            return []
-
-    def _index_file(self, path: Path) -> tuple[list[SymbolInformation], list[Call]]:
-        """Index a single file."""
-        content = path.read_bytes()
-        tree = self.parser.parse(content)
-        symbols: list[SymbolInformation] = []
-        calls: list[Call] = []
-
-        # Extract Classes
-        cursor = QueryCursor(self.class_query)
-        captures = cursor.captures(tree.root_node)
-
-        # tree-sitter 0.22+ returns dict {name: [nodes]}
-        for name, nodes in captures.items():
-            if name == "name":
-                for node in nodes:
-                    symbols.append(self._create_symbol(node, path, SymbolKind.CLASS))
-
-        # Extract Functions
-        cursor = QueryCursor(self.function_query)
-        captures = cursor.captures(tree.root_node)
-
-        for name, nodes in captures.items():
-            if name == "name":
-                for node in nodes:
-                    self._process_function_node(node, path, symbols)
-
-        # Extract Calls
-        cursor = QueryCursor(self.call_query)
-        captures = cursor.captures(tree.root_node)
-
-        # Iterate through call sites
-        # We need to handle both 'function_call' and 'method_call' captures
-        # Depending on query structure, might get multiple captures for same node
-
-        processed_nodes = set()
-
-        for capture_name, nodes in captures.items():
-            if capture_name in ("function_call", "method_call"):
-                for node in nodes:
-                    if node.id in processed_nodes:
-                        continue
-                    processed_nodes.add(node.id)
-
-                    callee_name = self._node_text(node)
-                    if not callee_name:
-                        continue
-                    caller_name = self._get_enclosing_function(node)
-
-                    if caller_name:
-                        start_row, start_col = node.start_point
-                        end_row, end_col = node.end_point
-
-                        calls.append(
-                            Call(
-                                from_symbol=caller_name,
-                                to_symbol=callee_name,
-                                location=SymbolLocation(
-                                    file=str(path.relative_to(self.root)),
-                                    line=start_row + 1,
-                                    column=start_col + 1,
-                                    end_line=end_row + 1,
-                                    end_column=end_col + 1,
-                                ),
-                            ),
-                        )
-
-        return symbols, calls
-
-    def _index_files_parallel(
-        self,
-        files: list[Path],
-        progress: Progress | None = None,
-        task_id: object | None = None,
-    ) -> tuple[list[SymbolInformation], list[Call]]:
-        """Index multiple files in parallel using ThreadPoolExecutor.
-
-        Divides files into batches and processes them concurrently.
-        Thread-safe result collection using locks.
-        """
-        symbols: list[SymbolInformation] = []
-        calls: list[Call] = []
-        symbols_lock = Lock()
-        calls_lock = Lock()
-        completed_count = 0
-        count_lock = Lock()
-
-        def _index_file_worker(file_path: Path) -> tuple[list[SymbolInformation], list[Call]]:
-            """Worker function to index a single file."""
-            try:
-                return self._index_file(file_path)
-            except Exception as exc:
-                logger.debug("Failed to index %s: %s", file_path, exc)
-                return [], []
-
-        def _update_progress(advance: int = 1) -> None:
-            """Update progress bar in a thread-safe manner."""
-            nonlocal completed_count
-            with count_lock:
-                completed_count += advance
-            if progress and task_id is not None:
-                progress.advance(task_id, advance)  # pyright: ignore[reportArgumentType]
-
-        # Split files into batches
-        batches = [
-            files[i : i + DEFAULT_BATCH_SIZE] for i in range(0, len(files), DEFAULT_BATCH_SIZE)
-        ]
-
-        # Process batches in parallel
-        max_workers = min(DEFAULT_MAX_WORKERS, len(batches))
-
-        with ThreadPoolExecutor(
-            max_workers=max_workers, thread_name_prefix="vds_lsp_index"
-        ) as executor:
-            # Submit all batch jobs
-            future_to_batch = {
-                executor.submit(self._process_batch, batch, _index_file_worker): i
-                for i, batch in enumerate(batches)
-            }
-
-            # Collect results as they complete
-            for future in as_completed(future_to_batch):
-                batch_idx = future_to_batch[future]
-                try:
-                    batch_symbols, batch_calls = future.result()
-                    # Thread-safe append
-                    with symbols_lock:
-                        symbols.extend(batch_symbols)
-                    with calls_lock:
-                        calls.extend(batch_calls)
-                    _update_progress(len(batches[batch_idx]))
-                except Exception as exc:
-                    logger.debug("Batch %d failed: %s", batch_idx, exc)
-                    _update_progress(len(batches[batch_idx]))
-
-        return symbols, calls
-
-    def _process_batch(
-        self,
-        batch: list[Path],
-        index_func: IndexFileFunc,
-    ) -> tuple[list[SymbolInformation], list[Call]]:
-        """Process a batch of files and return combined results.
-
-        This function runs in a worker thread and creates its own parser
-        to avoid thread-safety issues with tree-sitter Parser objects.
-        """
-        batch_symbols: list[SymbolInformation] = []
-        batch_calls: list[Call] = []
-
-        # Create a new parser for this thread (tree-sitter parsers are not thread-safe)
-        thread_parser = Parser(self.language)
-
-        # Temporarily replace self.parser for this batch
-        original_parser = self.parser
-        self.parser = thread_parser
-
-        try:
-            for file_path in batch:
-                try:
-                    file_symbols, file_calls = index_func(file_path)
-                    batch_symbols.extend(file_symbols)
-                    batch_calls.extend(file_calls)
-                except Exception as exc:
-                    logger.debug("Failed to index %s in batch: %s", file_path, exc)
-        finally:
-            # Restore original parser
-            self.parser = original_parser
-
-        return batch_symbols, batch_calls
-
-    def _get_enclosing_function(self, node: Node) -> str | None:
-        """Find the name of the function containing this node."""
-        parent = node.parent
-        while parent:
-            if parent.type == "function_definition":
-                # Find the name node child
-                for i, child in enumerate(parent.children):
-                    if child.type == "identifier" and parent.field_name_for_child(i) == "name":
-                        child_text = self._node_text(child)
-                        if child_text:
-                            return child_text
-            parent = parent.parent
-        return None
-
-    def _get_enclosing_class(self, node: Node) -> str | None:
-        """Find the name of the class containing this node."""
-        parent = node.parent
-        while parent:
-            if parent.type == "class_definition":
-                for i, child in enumerate(parent.children):
-                    if child.type == "identifier" and parent.field_name_for_child(i) == "name":
-                        child_text = self._node_text(child)
-                        if child_text:
-                            return child_text
-            parent = parent.parent
-        return None
-
-    def _get_decorators(self, node: Node) -> list[str]:
-        """Collect decorator text for a definition node."""
-        decorators: list[str] = []
-        parent = node.parent
-        while parent:
-            if parent.type == "decorated_definition":
-                for child in parent.children:
-                    if child.type == "decorator":
-                        text = self._node_text(child)
-                        if text:
-                            decorators.append(text)
-                break
-            parent = parent.parent
-        return decorators
-
-    def _get_parameters(self, node: Node) -> str | None:
-        parent = node.parent
-        if not parent:
-            return None
-        for child in parent.children:
-            if child.type in {"parameters", "parameter_list"}:
-                return self._node_text(child)
-        return None
-
-    def _is_async(self, node: Node) -> bool:
-        parent = node.parent
-        if not parent:
-            return False
-        if parent.type.startswith("async_"):
-            return True
-        return any(child.type == "async" for child in parent.children)
-
-    def _process_function_node(self, node: Node, path: Path, symbols: list[SymbolInformation]):
-        # Check if it's a method (inside a class)
-        kind = SymbolKind.FUNCTION
-        parent = node.parent
-        container_name = None
-        while parent:
-            if parent.type == "class_definition":
-                kind = SymbolKind.METHOD
-                container_name = self._get_enclosing_class(node)
-                break
-            parent = parent.parent
-
-        if not container_name:
-            container_name = self._get_enclosing_function(node)
-
-        extra: dict[str, str | list[str] | bool | None] = {
-            "parameters": self._get_parameters(node),
-            "decorators": self._get_decorators(node) or None,
-            "is_async": self._is_async(node),
-        }
-
-        symbols.append(
-            self._create_symbol(node, path, kind, container_name=container_name, extra=extra),
-        )
-
-    def _create_symbol(
-        self,
-        node: Node,
-        path: Path,
-        kind: SymbolKind,
-        *,
-        container_name: str | None = None,
-        extra: dict[str, str | list[str] | bool | None] | None = None,
-    ) -> SymbolInformation:
-        """Create a SymbolInformation object from a node."""
-        # Convert byte offset to line/col
-        # Tree-sitter 0.21+ node.start_point is (row, col)
-        start_row, start_col = node.start_point
-        end_row, end_col = node.end_point
-
-        # Node text is bytes, decode to string
-        name = self._node_text(node) or "unknown"
-
-        payload: dict[str, str | SymbolKind | SymbolLocation | list[str] | bool | None] = {
-            "name": name,
-            "kind": kind,
-            "location": SymbolLocation(
-                file=str(path.relative_to(self.root)),
-                line=start_row + 1,  # 1-based line
-                column=start_col + 1,
-                end_line=end_row + 1,
-                end_column=end_col + 1,
-            ),
-            "container_name": container_name,
-        }
-        if extra:
-            payload.update(extra)
-        return SymbolInformation(**payload)  # pyright: ignore[reportArgumentType]
-
-    def get_callers(
-        self, symbol_name: str, max_depth: int | None = None
-    ) -> list[dict[str, str | int | list[str] | bool]]:
-        """Get callers of a symbol."""
-        index = self.index_directory()
-        depth_limit = 1 if max_depth is None else max(max_depth, 1)
-
-        calls_by_callee: dict[str, list[Call]] = defaultdict(list)
-        for call in index.calls:
-            calls_by_callee[call.to_symbol].append(call)
-
-        callers: list[dict[str, str | int | list[str] | bool]] = []
-        queue: deque[tuple[str, int, list[str]]] = deque([(symbol_name, 0, [symbol_name])])
-        best_depth: dict[str, int] = {symbol_name: 0}
-
-        while queue:
-            current, depth, path = queue.popleft()
-            if depth >= depth_limit:
-                continue
-            for call in calls_by_callee.get(current, []):
-                next_depth = depth + 1
-                item = call.model_dump()
-                item["depth"] = next_depth
-                item["relation"] = "direct" if next_depth == 1 else "indirect"
-                item["external"] = False
-                caller = call.from_symbol
-                item["path"] = ([caller] + path) if caller else path
-                callers.append(item)
-                if caller and (caller not in best_depth or next_depth < best_depth[caller]):
-                    best_depth[caller] = next_depth
-                    queue.append((caller, next_depth, item["path"]))
-
-        return callers
-
-    def get_callees(
-        self, symbol_name: str, max_depth: int | None = None
-    ) -> list[dict[str, str | int | list[str] | bool]]:
-        """Get callees of a symbol."""
-        index = self.index_directory()
-        depth_limit = 1 if max_depth is None else max(max_depth, 1)
-
-        calls_by_caller: dict[str, list[Call]] = defaultdict(list)
-        for call in index.calls:
-            calls_by_caller[call.from_symbol].append(call)
-
-        callees: list[dict[str, str | int | list[str] | bool]] = []
-        queue: deque[tuple[str, int, list[str]]] = deque([(symbol_name, 0, [symbol_name])])
-        best_depth: dict[str, int] = {symbol_name: 0}
-
-        while queue:
-            current, depth, path = queue.popleft()
-            if depth >= depth_limit:
-                continue
-            for call in calls_by_caller.get(current, []):
-                next_depth = depth + 1
-                item = call.model_dump()
-                item["depth"] = next_depth
-                item["relation"] = "direct" if next_depth == 1 else "indirect"
-                item["external"] = False
-                callee = call.to_symbol
-                item["path"] = (path + [callee]) if callee else path
-                callees.append(item)
-                if callee and (callee not in best_depth or next_depth < best_depth[callee]):
-                    best_depth[callee] = next_depth
-                    queue.append((callee, next_depth, item["path"]))
-
-        return callees
-
-    def find_symbols(
-        self,
-        query: str,
-        kind: str | None = None,
-        *,
-        match: str = "contains",
-        limit: int | None = 50,
-    ) -> list[dict[str, str | int | SymbolKind | SymbolLocation | list[str] | bool | None]]:
-        """Find symbols matching query."""
-        index = self.index_directory()
-        mode = match.lower()
-        query_lower = query.lower()
-        pattern: re.Pattern[str] | None = None
-
-        if mode == "regex":
-            try:
-                pattern = re.compile(query, re.IGNORECASE)
-            except re.error as exc:
-                raise ValueError(f"Invalid regex pattern: {exc}") from exc
-        elif mode not in {"contains", "exact"}:
-            raise ValueError(f"Unsupported match mode: {match}")
-
-        # Score tuples have variable length based on match mode
-        scored: list[
-            tuple[tuple[int | str, ...], dict[str, str | int | SymbolKind | SymbolLocation]]
-        ] = []  # type: ignore[assignment]
-
-        for symbol in index.symbols:
-            if kind and symbol.kind.value.lower() != kind.lower():
-                continue
-
-            name = symbol.name
-            name_lower = name.lower()
-            score: tuple[int | str, ...] | None = None
-
-            if mode == "exact":
-                if name_lower == query_lower:
-                    score = (0, len(name), name_lower, symbol.location.file)
-            elif mode == "contains":
-                idx = name_lower.find(query_lower)
-                if idx != -1:
-                    rank = 0 if idx == 0 else 1
-                    score = (rank, idx, len(name), name_lower, symbol.location.file)
-            else:
-                assert pattern is not None
-                match_result = pattern.search(name)
-                if match_result:
-                    matched = match_result.group(0) or ""
-                    if matched.lower() == name_lower:
-                        rank = 0
-                    elif match_result.start() == 0:
-                        rank = 1
-                    else:
-                        rank = 2
-                    score = (
-                        rank,
-                        match_result.start(),
-                        len(name),
-                        name_lower,
-                        symbol.location.file,
-                    )
-
-            if score is not None:
-                scored.append((score, symbol.model_dump()))
-
-        scored.sort(key=lambda item: item[0])
-        results = [item for _, item in scored]
-
-        if limit is not None and limit > 0:
-            results = results[:limit]
-
-        return results  # pyright: ignore[reportReturnType]
-
-    def get_symbol_at_position(self, file_path: Path, line: int, column: int) -> str | None:
-        """Get the name of the symbol at the specified position."""
-        try:
-            content = file_path.read_bytes()
-            tree = self.parser.parse(content)
-            # Tree-sitter uses 0-based indexing for rows and columns
-            point = (line - 1, column - 1)
-
-            node = tree.root_node.descendant_for_point_range(point, point)
-
-            if not node:
-                return None
-
-            # If we landed on a leaf node that is an identifier, return its text
-            if node.type == "identifier":
-                return self._node_text(node)
-
-            # If we are part of an attribute (obj.attr), we might want the attr name
-            # or if we are in a call (func()), the function name
-            # This is a simple implementation: just check if current or parent is identifier
-            if node.parent and node.parent.type == "identifier":
-                return self._node_text(node.parent)
-
-            return None
-        except Exception as exc:
-            logger.debug("Failed to resolve symbol at %s:%s:%s: %s", file_path, line, column, exc)
-            return None
-
-    def find_references(
-        self,
-        symbol_name: str,
-        *,
-        context_lines: int = 0,
-    ) -> list[dict[str, str | int | dict[str, int | str]]]:
-        """Find references to a symbol by name (AST-based approximation)."""
-        references = []
-        files = [f for f in self.root.rglob("*.py") if not self._is_excluded(f)]
-
-        for file_path in files:
-            try:
-                content = file_path.read_bytes()
-                tree = self.parser.parse(content)
-                cursor = QueryCursor(self.identifier_query)
-                captures = cursor.captures(tree.root_node)
-
-                for name, nodes in captures.items():
-                    if name == "name":
-                        for node in nodes:
-                            node_text = self._node_text(node)
-                            if node_text == symbol_name:
-                                # Create symbol info (kind=Variable as placeholder for ref)
-                                start_row, start_col = node.start_point
-                                end_row, end_col = node.end_point
-                                parent = node.parent
-                                category = "read"
-                                if parent:
-                                    try:
-                                        field_name = parent.field_name_for_child(
-                                            parent.children.index(node),
-                                        )
-                                    except ValueError:
-                                        field_name = None
-
-                                    if (
-                                        parent.type in {"function_definition", "class_definition"}
-                                        and field_name == "name"
-                                    ):
-                                        category = "definition"
-                                    elif parent.type == "call" and field_name == "function":
-                                        category = "call"
-                                    elif (
-                                        parent.type in {"assignment", "augmented_assignment"}
-                                        and field_name in {"left", "target"}
-                                    ) or (
-                                        parent.type in {"for_statement", "with_item"}
-                                        and field_name in {"left", "target", "alias"}
-                                    ):
-                                        category = "write"
-
-                                    context = extract_context(
-                                        file_path,
-                                        line=start_row + 1,
-                                        context_lines=context_lines,
-                                    )
-
-                                    ref: dict[str, str | int | list[str] | dict[str, int | str]] = {
-                                        "name": symbol_name,
-                                        "kind": "Reference",
-                                        "category": category,
-                                        "location": {
-                                            "file": str(file_path.relative_to(self.root)),
-                                            "line": start_row + 1,
-                                            "column": start_col + 1,
-                                            "end_line": end_row + 1,
-                                            "end_column": end_col + 1,
-                                        },
-                                    }
-                                    if context:
-                                        ref["context"] = context  # type: ignore[assignment]
-                                    references.append(ref)  # type: ignore[arg-type]
-            except Exception as exc:
-                logger.debug("Failed to parse %s for references: %s", file_path, exc)
-
-        return references
-
-    def get_document_symbols_tree(
-        self, file_path: Path
-    ) -> list[dict[str, str | int | SymbolKind | SymbolLocation | list[str] | bool | None]]:
-        """Build hierarchical document symbols for a single file."""
-        content = file_path.read_bytes()
-        tree = self.parser.parse(content)
-
-        def is_def(node: Node) -> bool:
-            return node.type in {
-                "class_definition",
-                "function_definition",
-                "async_function_definition",
-            }
-
-        def find_body(node: Node) -> Node | None:
-            for child in node.children:
-                if child.type == "block":
-                    return child
-            return None
-
-        def symbol_from_node(
-            node: Node,
-        ) -> dict[str, str | int | SymbolKind | SymbolLocation | list[str] | bool | None] | None:
-            name_node: Node | None = None
-            for i, child in enumerate(node.children):
-                if child.type == "identifier" and node.field_name_for_child(i) == "name":
-                    name_node = child
-                    break
-            if name_node is None:
-                return None
-
-            kind = SymbolKind.CLASS if node.type == "class_definition" else SymbolKind.FUNCTION
-            if self._get_enclosing_class(name_node) and kind == SymbolKind.FUNCTION:
-                kind = SymbolKind.METHOD
-
-            extra: dict[str, str | list[str] | bool | None] = {
-                "parameters": self._get_parameters(name_node),
-                "decorators": self._get_decorators(node) or None,
-                "is_async": self._is_async(name_node),
-            }
-            symbol = self._create_symbol(
-                name_node,
-                file_path,
-                kind,
-                container_name=self._get_enclosing_class(name_node)
-                or self._get_enclosing_function(name_node),
-                extra=extra,
-            )
-            return symbol.model_dump()
-
-        def collect(
-            parent: Node,
-        ) -> list[dict[str, str | int | SymbolKind | SymbolLocation | list[str] | bool | None]]:
-            results: list[
-                dict[str, str | int | SymbolKind | SymbolLocation | list[str] | bool | None]
-            ] = []
-            for child in parent.children:
-                if is_def(child):
-                    symbol = symbol_from_node(child)
-                    if symbol:
-                        body = find_body(child)
-                        if body is not None:
-                            children = collect(body)
-                            if children:
-                                symbol["children"] = children  # pyright: ignore[reportArgumentType, reportIndexIssue]
-                        results.append(symbol)
-                    continue
-                # Traverse into wrapper nodes (decorators, etc.)
-                results.extend(collect(child))
-            return results
-
-        return collect(tree.root_node)
-
-    def _node_text(self, node: Node) -> str | None:
-        text = node.text
-        if not text:
-            return None
-        return text.decode("utf-8")
-
-    def _is_excluded(self, path: Path) -> bool:
-        """Check if file path matches exclude patterns."""
-        rel_path = path.relative_to(self.root).as_posix()
-        patterns: list[str] = []
-        if self.config:
-            exclude_patterns = getattr(self.config, "exclude_patterns", None)
-            if exclude_patterns:
-                patterns.extend(exclude_patterns)  # type: ignore[arg-type]
-        if not patterns:
-            patterns.extend(
-                [
-                    "**/node_modules/**",
-                    "**/.venv/**",
-                    "**/__pycache__/**",
-                    "**/build/**",
-                    "**/dist/**",
-                ],
-            )
-        return any(fnmatch.fnmatch(rel_path, pattern) for pattern in patterns)