Refactor code structure and remove redundant changes

codex-lens/build/lib/codexlens/lsp/__init__.py

@@ -0,0 +1,34 @@
+"""LSP module for real-time language server integration.
+
+This module provides:
+- LspBridge: HTTP bridge to VSCode language servers
+- LspGraphBuilder: Build code association graphs via LSP
+- Location: Position in a source file
+
+Example:
+    >>> from codexlens.lsp import LspBridge, LspGraphBuilder
+    >>> 
+    >>> async with LspBridge() as bridge:
+    ...     refs = await bridge.get_references(symbol)
+    ...     graph = await LspGraphBuilder().build_from_seeds(seeds, bridge)
+"""
+
+from codexlens.lsp.lsp_bridge import (
+    CacheEntry,
+    Location,
+    LspBridge,
+)
+from codexlens.lsp.lsp_graph_builder import (
+    LspGraphBuilder,
+)
+
+# Alias for backward compatibility
+GraphBuilder = LspGraphBuilder
+
+__all__ = [
+    "CacheEntry",
+    "GraphBuilder",
+    "Location",
+    "LspBridge",
+    "LspGraphBuilder",
+]

codex-lens/build/lib/codexlens/lsp/handlers.py

@@ -0,0 +1,551 @@
+"""LSP request handlers for codex-lens.
+
+This module contains handlers for LSP requests:
+- textDocument/definition
+- textDocument/completion
+- workspace/symbol
+- textDocument/didSave
+- textDocument/hover
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import List, Optional, Union
+from urllib.parse import quote, unquote
+
+try:
+    from lsprotocol import types as lsp
+except ImportError as exc:
+    raise ImportError(
+        "LSP dependencies not installed. Install with: pip install codex-lens[lsp]"
+    ) from exc
+
+from codexlens.entities import Symbol
+from codexlens.lsp.server import server
+
+logger = logging.getLogger(__name__)
+
+# Symbol kind mapping from codex-lens to LSP
+SYMBOL_KIND_MAP = {
+    "class": lsp.SymbolKind.Class,
+    "function": lsp.SymbolKind.Function,
+    "method": lsp.SymbolKind.Method,
+    "variable": lsp.SymbolKind.Variable,
+    "constant": lsp.SymbolKind.Constant,
+    "property": lsp.SymbolKind.Property,
+    "field": lsp.SymbolKind.Field,
+    "interface": lsp.SymbolKind.Interface,
+    "module": lsp.SymbolKind.Module,
+    "namespace": lsp.SymbolKind.Namespace,
+    "package": lsp.SymbolKind.Package,
+    "enum": lsp.SymbolKind.Enum,
+    "enum_member": lsp.SymbolKind.EnumMember,
+    "struct": lsp.SymbolKind.Struct,
+    "type": lsp.SymbolKind.TypeParameter,
+    "type_alias": lsp.SymbolKind.TypeParameter,
+}
+
+# Completion kind mapping from codex-lens to LSP
+COMPLETION_KIND_MAP = {
+    "class": lsp.CompletionItemKind.Class,
+    "function": lsp.CompletionItemKind.Function,
+    "method": lsp.CompletionItemKind.Method,
+    "variable": lsp.CompletionItemKind.Variable,
+    "constant": lsp.CompletionItemKind.Constant,
+    "property": lsp.CompletionItemKind.Property,
+    "field": lsp.CompletionItemKind.Field,
+    "interface": lsp.CompletionItemKind.Interface,
+    "module": lsp.CompletionItemKind.Module,
+    "enum": lsp.CompletionItemKind.Enum,
+    "enum_member": lsp.CompletionItemKind.EnumMember,
+    "struct": lsp.CompletionItemKind.Struct,
+    "type": lsp.CompletionItemKind.TypeParameter,
+    "type_alias": lsp.CompletionItemKind.TypeParameter,
+}
+
+
+def _path_to_uri(path: Union[str, Path]) -> str:
+    """Convert a file path to a URI.
+
+    Args:
+        path: File path (string or Path object)
+
+    Returns:
+        File URI string
+    """
+    path_str = str(Path(path).resolve())
+    # Handle Windows paths
+    if path_str.startswith("/"):
+        return f"file://{quote(path_str)}"
+    else:
+        return f"file:///{quote(path_str.replace(chr(92), '/'))}"
+
+
+def _uri_to_path(uri: str) -> Path:
+    """Convert a URI to a file path.
+
+    Args:
+        uri: File URI string
+
+    Returns:
+        Path object
+    """
+    path = uri.replace("file:///", "").replace("file://", "")
+    return Path(unquote(path))
+
+
+def _get_word_at_position(document_text: str, line: int, character: int) -> Optional[str]:
+    """Extract the word at the given position in the document.
+
+    Args:
+        document_text: Full document text
+        line: 0-based line number
+        character: 0-based character position
+
+    Returns:
+        Word at position, or None if no word found
+    """
+    lines = document_text.splitlines()
+    if line >= len(lines):
+        return None
+
+    line_text = lines[line]
+    if character > len(line_text):
+        return None
+
+    # Find word boundaries
+    word_pattern = re.compile(r"[a-zA-Z_][a-zA-Z0-9_]*")
+    for match in word_pattern.finditer(line_text):
+        if match.start() <= character <= match.end():
+            return match.group()
+
+    return None
+
+
+def _get_prefix_at_position(document_text: str, line: int, character: int) -> str:
+    """Extract the incomplete word prefix at the given position.
+
+    Args:
+        document_text: Full document text
+        line: 0-based line number
+        character: 0-based character position
+
+    Returns:
+        Prefix string (may be empty)
+    """
+    lines = document_text.splitlines()
+    if line >= len(lines):
+        return ""
+
+    line_text = lines[line]
+    if character > len(line_text):
+        character = len(line_text)
+
+    # Extract text before cursor
+    before_cursor = line_text[:character]
+
+    # Find the start of the current word
+    match = re.search(r"[a-zA-Z_][a-zA-Z0-9_]*$", before_cursor)
+    if match:
+        return match.group()
+
+    return ""
+
+
+def symbol_to_location(symbol: Symbol) -> Optional[lsp.Location]:
+    """Convert a codex-lens Symbol to an LSP Location.
+
+    Args:
+        symbol: codex-lens Symbol object
+
+    Returns:
+        LSP Location, or None if symbol has no file
+    """
+    if not symbol.file:
+        return None
+
+    # LSP uses 0-based lines, codex-lens uses 1-based
+    start_line = max(0, symbol.range[0] - 1)
+    end_line = max(0, symbol.range[1] - 1)
+
+    return lsp.Location(
+        uri=_path_to_uri(symbol.file),
+        range=lsp.Range(
+            start=lsp.Position(line=start_line, character=0),
+            end=lsp.Position(line=end_line, character=0),
+        ),
+    )
+
+
+def _symbol_kind_to_lsp(kind: str) -> lsp.SymbolKind:
+    """Map codex-lens symbol kind to LSP SymbolKind.
+
+    Args:
+        kind: codex-lens symbol kind string
+
+    Returns:
+        LSP SymbolKind
+    """
+    return SYMBOL_KIND_MAP.get(kind.lower(), lsp.SymbolKind.Variable)
+
+
+def _symbol_kind_to_completion_kind(kind: str) -> lsp.CompletionItemKind:
+    """Map codex-lens symbol kind to LSP CompletionItemKind.
+
+    Args:
+        kind: codex-lens symbol kind string
+
+    Returns:
+        LSP CompletionItemKind
+    """
+    return COMPLETION_KIND_MAP.get(kind.lower(), lsp.CompletionItemKind.Text)
+
+
+# -----------------------------------------------------------------------------
+# LSP Request Handlers
+# -----------------------------------------------------------------------------
+
+
+@server.feature(lsp.TEXT_DOCUMENT_DEFINITION)
+def lsp_definition(
+    params: lsp.DefinitionParams,
+) -> Optional[Union[lsp.Location, List[lsp.Location]]]:
+    """Handle textDocument/definition request.
+
+    Finds the definition of the symbol at the cursor position.
+    """
+    if not server.global_index:
+        logger.debug("No global index available for definition lookup")
+        return None
+
+    # Get document
+    document = server.workspace.get_text_document(params.text_document.uri)
+    if not document:
+        return None
+
+    # Get word at position
+    word = _get_word_at_position(
+        document.source,
+        params.position.line,
+        params.position.character,
+    )
+
+    if not word:
+        logger.debug("No word found at position")
+        return None
+
+    logger.debug("Looking up definition for: %s", word)
+
+    # Search for exact symbol match
+    try:
+        symbols = server.global_index.search(
+            name=word,
+            limit=10,
+            prefix_mode=False,  # Exact match preferred
+        )
+
+        # Filter for exact name match
+        exact_matches = [s for s in symbols if s.name == word]
+        if not exact_matches:
+            # Fall back to prefix search
+            symbols = server.global_index.search(
+                name=word,
+                limit=10,
+                prefix_mode=True,
+            )
+            exact_matches = [s for s in symbols if s.name == word]
+
+        if not exact_matches:
+            logger.debug("No definition found for: %s", word)
+            return None
+
+        # Convert to LSP locations
+        locations = []
+        for sym in exact_matches:
+            loc = symbol_to_location(sym)
+            if loc:
+                locations.append(loc)
+
+        if len(locations) == 1:
+            return locations[0]
+        elif locations:
+            return locations
+        else:
+            return None
+
+    except Exception as exc:
+        logger.error("Error looking up definition: %s", exc)
+        return None
+
+
+@server.feature(lsp.TEXT_DOCUMENT_REFERENCES)
+def lsp_references(params: lsp.ReferenceParams) -> Optional[List[lsp.Location]]:
+    """Handle textDocument/references request.
+
+    Finds all references to the symbol at the cursor position using
+    the code_relationships table for accurate call-site tracking.
+    Falls back to same-name symbol search if search_engine is unavailable.
+    """
+    document = server.workspace.get_text_document(params.text_document.uri)
+    if not document:
+        return None
+
+    word = _get_word_at_position(
+        document.source,
+        params.position.line,
+        params.position.character,
+    )
+
+    if not word:
+        return None
+
+    logger.debug("Finding references for: %s", word)
+
+    try:
+        # Try using search_engine.search_references() for accurate reference tracking
+        if server.search_engine and server.workspace_root:
+            references = server.search_engine.search_references(
+                symbol_name=word,
+                source_path=server.workspace_root,
+                limit=200,
+            )
+
+            if references:
+                locations = []
+                for ref in references:
+                    locations.append(
+                        lsp.Location(
+                            uri=_path_to_uri(ref.file_path),
+                            range=lsp.Range(
+                                start=lsp.Position(
+                                    line=max(0, ref.line - 1),
+                                    character=ref.column,
+                                ),
+                                end=lsp.Position(
+                                    line=max(0, ref.line - 1),
+                                    character=ref.column + len(word),
+                                ),
+                            ),
+                        )
+                    )
+                return locations if locations else None
+
+        # Fallback: search for symbols with same name using global_index
+        if server.global_index:
+            symbols = server.global_index.search(
+                name=word,
+                limit=100,
+                prefix_mode=False,
+            )
+
+            # Filter for exact matches
+            exact_matches = [s for s in symbols if s.name == word]
+
+            locations = []
+            for sym in exact_matches:
+                loc = symbol_to_location(sym)
+                if loc:
+                    locations.append(loc)
+
+            return locations if locations else None
+
+        return None
+
+    except Exception as exc:
+        logger.error("Error finding references: %s", exc)
+        return None
+
+
+@server.feature(lsp.TEXT_DOCUMENT_COMPLETION)
+def lsp_completion(params: lsp.CompletionParams) -> Optional[lsp.CompletionList]:
+    """Handle textDocument/completion request.
+
+    Provides code completion suggestions based on indexed symbols.
+    """
+    if not server.global_index:
+        return None
+
+    document = server.workspace.get_text_document(params.text_document.uri)
+    if not document:
+        return None
+
+    prefix = _get_prefix_at_position(
+        document.source,
+        params.position.line,
+        params.position.character,
+    )
+
+    if not prefix or len(prefix) < 2:
+        # Require at least 2 characters for completion
+        return None
+
+    logger.debug("Completing prefix: %s", prefix)
+
+    try:
+        symbols = server.global_index.search(
+            name=prefix,
+            limit=50,
+            prefix_mode=True,
+        )
+
+        if not symbols:
+            return None
+
+        # Convert to completion items
+        items = []
+        seen_names = set()
+
+        for sym in symbols:
+            if sym.name in seen_names:
+                continue
+            seen_names.add(sym.name)
+
+            items.append(
+                lsp.CompletionItem(
+                    label=sym.name,
+                    kind=_symbol_kind_to_completion_kind(sym.kind),
+                    detail=f"{sym.kind} - {Path(sym.file).name if sym.file else 'unknown'}",
+                    sort_text=sym.name.lower(),
+                )
+            )
+
+        return lsp.CompletionList(
+            is_incomplete=len(symbols) >= 50,
+            items=items,
+        )
+
+    except Exception as exc:
+        logger.error("Error getting completions: %s", exc)
+        return None
+
+
+@server.feature(lsp.TEXT_DOCUMENT_HOVER)
+def lsp_hover(params: lsp.HoverParams) -> Optional[lsp.Hover]:
+    """Handle textDocument/hover request.
+
+    Provides hover information for the symbol at the cursor position
+    using HoverProvider for rich symbol information including
+    signature, documentation, and location.
+    """
+    if not server.global_index:
+        return None
+
+    document = server.workspace.get_text_document(params.text_document.uri)
+    if not document:
+        return None
+
+    word = _get_word_at_position(
+        document.source,
+        params.position.line,
+        params.position.character,
+    )
+
+    if not word:
+        return None
+
+    logger.debug("Hover for: %s", word)
+
+    try:
+        # Use HoverProvider for rich symbol information
+        from codexlens.lsp.providers import HoverProvider
+
+        provider = HoverProvider(server.global_index, server.registry)
+        info = provider.get_hover_info(word)
+
+        if not info:
+            return None
+
+        # Format as markdown with signature and location
+        content = provider.format_hover_markdown(info)
+
+        return lsp.Hover(
+            contents=lsp.MarkupContent(
+                kind=lsp.MarkupKind.Markdown,
+                value=content,
+            ),
+        )
+
+    except Exception as exc:
+        logger.error("Error getting hover info: %s", exc)
+        return None
+
+
+@server.feature(lsp.WORKSPACE_SYMBOL)
+def lsp_workspace_symbol(
+    params: lsp.WorkspaceSymbolParams,
+) -> Optional[List[lsp.SymbolInformation]]:
+    """Handle workspace/symbol request.
+
+    Searches for symbols across the workspace.
+    """
+    if not server.global_index:
+        return None
+
+    query = params.query
+    if not query or len(query) < 2:
+        return None
+
+    logger.debug("Workspace symbol search: %s", query)
+
+    try:
+        symbols = server.global_index.search(
+            name=query,
+            limit=100,
+            prefix_mode=True,
+        )
+
+        if not symbols:
+            return None
+
+        result = []
+        for sym in symbols:
+            loc = symbol_to_location(sym)
+            if loc:
+                result.append(
+                    lsp.SymbolInformation(
+                        name=sym.name,
+                        kind=_symbol_kind_to_lsp(sym.kind),
+                        location=loc,
+                        container_name=Path(sym.file).parent.name if sym.file else None,
+                    )
+                )
+
+        return result if result else None
+
+    except Exception as exc:
+        logger.error("Error searching workspace symbols: %s", exc)
+        return None
+
+
+@server.feature(lsp.TEXT_DOCUMENT_DID_SAVE)
+def lsp_did_save(params: lsp.DidSaveTextDocumentParams) -> None:
+    """Handle textDocument/didSave notification.
+
+    Triggers incremental re-indexing of the saved file.
+    Note: Full incremental indexing requires WatcherManager integration,
+    which is planned for Phase 2.
+    """
+    file_path = _uri_to_path(params.text_document.uri)
+    logger.info("File saved: %s", file_path)
+
+    # Phase 1: Just log the save event
+    # Phase 2 will integrate with WatcherManager for incremental indexing
+    # if server.watcher_manager:
+    #     server.watcher_manager.trigger_reindex(file_path)
+
+
+@server.feature(lsp.TEXT_DOCUMENT_DID_OPEN)
+def lsp_did_open(params: lsp.DidOpenTextDocumentParams) -> None:
+    """Handle textDocument/didOpen notification."""
+    file_path = _uri_to_path(params.text_document.uri)
+    logger.debug("File opened: %s", file_path)
+
+
+@server.feature(lsp.TEXT_DOCUMENT_DID_CLOSE)
+def lsp_did_close(params: lsp.DidCloseTextDocumentParams) -> None:
+    """Handle textDocument/didClose notification."""
+    file_path = _uri_to_path(params.text_document.uri)
+    logger.debug("File closed: %s", file_path)

codex-lens/build/lib/codexlens/lsp/lsp_bridge.py

@@ -0,0 +1,834 @@
+"""LspBridge service for real-time LSP communication with caching.
+
+This module provides a bridge to communicate with language servers either via:
+1. Standalone LSP Manager (direct subprocess communication - default)
+2. VSCode Bridge extension (HTTP-based, legacy mode)
+
+Features:
+- Direct communication with language servers (no VSCode dependency)
+- Cache with TTL and file modification time invalidation
+- Graceful error handling with empty results on failure
+- Support for definition, references, hover, and call hierarchy
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codexlens.lsp.standalone_manager import StandaloneLspManager
+
+# Check for optional dependencies
+try:
+    import aiohttp
+    HAS_AIOHTTP = True
+except ImportError:
+    HAS_AIOHTTP = False
+
+from codexlens.hybrid_search.data_structures import (
+    CallHierarchyItem,
+    CodeSymbolNode,
+    Range,
+)
+
+
+@dataclass
+class Location:
+    """A location in a source file (LSP response format)."""
+    
+    file_path: str
+    line: int
+    character: int
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary format."""
+        return {
+            "file_path": self.file_path,
+            "line": self.line,
+            "character": self.character,
+        }
+    
+    @classmethod
+    def from_lsp_response(cls, data: Dict[str, Any]) -> "Location":
+        """Create Location from LSP response format.
+        
+        Handles both direct format and VSCode URI format.
+        """
+        # Handle VSCode URI format (file:///path/to/file)
+        uri = data.get("uri", data.get("file_path", ""))
+        if uri.startswith("file:///"):
+            # Windows: file:///C:/path -> C:/path
+            # Unix: file:///path -> /path
+            file_path = uri[8:] if uri[8:9].isalpha() and uri[9:10] == ":" else uri[7:]
+        elif uri.startswith("file://"):
+            file_path = uri[7:]
+        else:
+            file_path = uri
+        
+        # Get position from range or direct fields
+        if "range" in data:
+            range_data = data["range"]
+            start = range_data.get("start", {})
+            line = start.get("line", 0) + 1  # LSP is 0-based, convert to 1-based
+            character = start.get("character", 0) + 1
+        else:
+            line = data.get("line", 1)
+            character = data.get("character", 1)
+        
+        return cls(file_path=file_path, line=line, character=character)
+
+
+@dataclass
+class CacheEntry:
+    """A cached LSP response with expiration metadata.
+    
+    Attributes:
+        data: The cached response data
+        file_mtime: File modification time when cached (for invalidation)
+        cached_at: Unix timestamp when entry was cached
+    """
+    
+    data: Any
+    file_mtime: float
+    cached_at: float
+
+
+class LspBridge:
+    """Bridge for real-time LSP communication with language servers.
+    
+    By default, uses StandaloneLspManager to directly spawn and communicate
+    with language servers via JSON-RPC over stdio. No VSCode dependency required.
+    
+    For legacy mode, can use VSCode Bridge HTTP server (set use_vscode_bridge=True).
+    
+    Features:
+    - Direct language server communication (default)
+    - Response caching with TTL and file modification invalidation
+    - Timeout handling
+    - Graceful error handling returning empty results
+    
+    Example:
+        # Default: standalone mode (no VSCode needed)
+        async with LspBridge() as bridge:
+            refs = await bridge.get_references(symbol)
+            definition = await bridge.get_definition(symbol)
+        
+        # Legacy: VSCode Bridge mode
+        async with LspBridge(use_vscode_bridge=True) as bridge:
+            refs = await bridge.get_references(symbol)
+    """
+    
+    DEFAULT_BRIDGE_URL = "http://127.0.0.1:3457"
+    DEFAULT_TIMEOUT = 30.0  # seconds (increased for standalone mode)
+    DEFAULT_CACHE_TTL = 300  # 5 minutes
+    DEFAULT_MAX_CACHE_SIZE = 1000  # Maximum cache entries
+
+    def __init__(
+        self,
+        bridge_url: str = DEFAULT_BRIDGE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        cache_ttl: int = DEFAULT_CACHE_TTL,
+        max_cache_size: int = DEFAULT_MAX_CACHE_SIZE,
+        use_vscode_bridge: bool = False,
+        workspace_root: Optional[str] = None,
+        config_file: Optional[str] = None,
+    ):
+        """Initialize LspBridge.
+
+        Args:
+            bridge_url: URL of the VSCode Bridge HTTP server (legacy mode only)
+            timeout: Request timeout in seconds
+            cache_ttl: Cache time-to-live in seconds
+            max_cache_size: Maximum number of cache entries (LRU eviction)
+            use_vscode_bridge: If True, use VSCode Bridge HTTP mode (requires aiohttp)
+            workspace_root: Root directory for standalone LSP manager
+            config_file: Path to lsp-servers.json configuration file
+        """
+        self.bridge_url = bridge_url
+        self.timeout = timeout
+        self.cache_ttl = cache_ttl
+        self.max_cache_size = max_cache_size
+        self.use_vscode_bridge = use_vscode_bridge
+        self.workspace_root = workspace_root
+        self.config_file = config_file
+        
+        self.cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        
+        # VSCode Bridge mode (legacy)
+        self._session: Optional["aiohttp.ClientSession"] = None
+        
+        # Standalone mode (default)
+        self._manager: Optional["StandaloneLspManager"] = None
+        self._manager_started = False
+        
+        # Validate dependencies
+        if use_vscode_bridge and not HAS_AIOHTTP:
+            raise ImportError(
+                "aiohttp is required for VSCode Bridge mode: pip install aiohttp"
+            )
+    
+    async def _ensure_manager(self) -> "StandaloneLspManager":
+        """Ensure standalone LSP manager is started."""
+        if self._manager is None:
+            from codexlens.lsp.standalone_manager import StandaloneLspManager
+            self._manager = StandaloneLspManager(
+                workspace_root=self.workspace_root,
+                config_file=self.config_file,
+                timeout=self.timeout,
+            )
+        
+        if not self._manager_started:
+            await self._manager.start()
+            self._manager_started = True
+        
+        return self._manager
+    
+    async def _get_session(self) -> "aiohttp.ClientSession":
+        """Get or create the aiohttp session (VSCode Bridge mode only)."""
+        if not HAS_AIOHTTP:
+            raise ImportError("aiohttp required for VSCode Bridge mode")
+        
+        if self._session is None or self._session.closed:
+            timeout = aiohttp.ClientTimeout(total=self.timeout)
+            self._session = aiohttp.ClientSession(timeout=timeout)
+        return self._session
+    
+    async def close(self) -> None:
+        """Close connections and cleanup resources."""
+        # Close VSCode Bridge session
+        if self._session and not self._session.closed:
+            await self._session.close()
+            self._session = None
+        
+        # Stop standalone manager
+        if self._manager and self._manager_started:
+            await self._manager.stop()
+            self._manager_started = False
+    
+    def _get_file_mtime(self, file_path: str) -> float:
+        """Get file modification time, or 0 if file doesn't exist."""
+        try:
+            return os.path.getmtime(file_path)
+        except OSError:
+            return 0.0
+    
+    def _is_cached(self, cache_key: str, file_path: str) -> bool:
+        """Check if cache entry is valid.
+
+        Cache is invalid if:
+        - Entry doesn't exist
+        - TTL has expired
+        - File has been modified since caching
+
+        Args:
+            cache_key: The cache key to check
+            file_path: Path to source file for mtime check
+
+        Returns:
+            True if cache is valid and can be used
+        """
+        if cache_key not in self.cache:
+            return False
+
+        entry = self.cache[cache_key]
+        now = time.time()
+
+        # Check TTL
+        if now - entry.cached_at > self.cache_ttl:
+            del self.cache[cache_key]
+            return False
+
+        # Check file modification time
+        current_mtime = self._get_file_mtime(file_path)
+        if current_mtime != entry.file_mtime:
+            del self.cache[cache_key]
+            return False
+
+        # Move to end on access (LRU behavior)
+        self.cache.move_to_end(cache_key)
+        return True
+    
+    def _cache(self, key: str, file_path: str, data: Any) -> None:
+        """Store data in cache with LRU eviction.
+
+        Args:
+            key: Cache key
+            file_path: Path to source file (for mtime tracking)
+            data: Data to cache
+        """
+        # Remove oldest entries if at capacity
+        while len(self.cache) >= self.max_cache_size:
+            self.cache.popitem(last=False)  # Remove oldest (FIFO order)
+
+        # Move to end if key exists (update access order)
+        if key in self.cache:
+            self.cache.move_to_end(key)
+
+        self.cache[key] = CacheEntry(
+            data=data,
+            file_mtime=self._get_file_mtime(file_path),
+            cached_at=time.time(),
+        )
+    
+    def clear_cache(self) -> None:
+        """Clear all cached entries."""
+        self.cache.clear()
+    
+    async def _request_vscode_bridge(self, action: str, params: Dict[str, Any]) -> Any:
+        """Make HTTP request to VSCode Bridge (legacy mode).
+        
+        Args:
+            action: The endpoint/action name (e.g., "get_definition")
+            params: Request parameters
+            
+        Returns:
+            Response data on success, None on failure
+        """
+        url = f"{self.bridge_url}/{action}"
+        
+        try:
+            session = await self._get_session()
+            async with session.post(url, json=params) as response:
+                if response.status != 200:
+                    return None
+                
+                data = await response.json()
+                if data.get("success") is False:
+                    return None
+                
+                return data.get("result")
+        
+        except asyncio.TimeoutError:
+            return None
+        except Exception:
+            return None
+    
+    async def get_references(self, symbol: CodeSymbolNode) -> List[Location]:
+        """Get all references to a symbol via real-time LSP.
+
+        Args:
+            symbol: The code symbol to find references for
+
+        Returns:
+            List of Location objects where the symbol is referenced.
+            Returns empty list on error or timeout.
+        """
+        cache_key = f"refs:{symbol.id}"
+
+        if self._is_cached(cache_key, symbol.file_path):
+            return self.cache[cache_key].data
+
+        locations: List[Location] = []
+
+        if self.use_vscode_bridge:
+            # Legacy: VSCode Bridge HTTP mode
+            result = await self._request_vscode_bridge("get_references", {
+                "file_path": symbol.file_path,
+                "line": symbol.range.start_line,
+                "character": symbol.range.start_character,
+            })
+
+            # Don't cache on connection error (result is None)
+            if result is None:
+                return locations
+
+            if isinstance(result, list):
+                for item in result:
+                    try:
+                        locations.append(Location.from_lsp_response(item))
+                    except (KeyError, TypeError):
+                        continue
+        else:
+            # Default: Standalone mode
+            manager = await self._ensure_manager()
+            result = await manager.get_references(
+                file_path=symbol.file_path,
+                line=symbol.range.start_line,
+                character=symbol.range.start_character,
+            )
+
+            for item in result:
+                try:
+                    locations.append(Location.from_lsp_response(item))
+                except (KeyError, TypeError):
+                    continue
+
+        self._cache(cache_key, symbol.file_path, locations)
+        return locations
+    
+    async def get_definition(self, symbol: CodeSymbolNode) -> Optional[Location]:
+        """Get symbol definition location.
+        
+        Args:
+            symbol: The code symbol to find definition for
+            
+        Returns:
+            Location of the definition, or None if not found
+        """
+        cache_key = f"def:{symbol.id}"
+        
+        if self._is_cached(cache_key, symbol.file_path):
+            return self.cache[cache_key].data
+        
+        location: Optional[Location] = None
+        
+        if self.use_vscode_bridge:
+            # Legacy: VSCode Bridge HTTP mode
+            result = await self._request_vscode_bridge("get_definition", {
+                "file_path": symbol.file_path,
+                "line": symbol.range.start_line,
+                "character": symbol.range.start_character,
+            })
+            
+            if result:
+                if isinstance(result, list) and len(result) > 0:
+                    try:
+                        location = Location.from_lsp_response(result[0])
+                    except (KeyError, TypeError):
+                        pass
+                elif isinstance(result, dict):
+                    try:
+                        location = Location.from_lsp_response(result)
+                    except (KeyError, TypeError):
+                        pass
+        else:
+            # Default: Standalone mode
+            manager = await self._ensure_manager()
+            result = await manager.get_definition(
+                file_path=symbol.file_path,
+                line=symbol.range.start_line,
+                character=symbol.range.start_character,
+            )
+            
+            if result:
+                try:
+                    location = Location.from_lsp_response(result)
+                except (KeyError, TypeError):
+                    pass
+        
+        self._cache(cache_key, symbol.file_path, location)
+        return location
+    
+    async def get_call_hierarchy(self, symbol: CodeSymbolNode) -> List[CallHierarchyItem]:
+        """Get incoming/outgoing calls for a symbol.
+        
+        If call hierarchy is not supported by the language server,
+        falls back to using references.
+        
+        Args:
+            symbol: The code symbol to get call hierarchy for
+            
+        Returns:
+            List of CallHierarchyItem representing callers/callees.
+            Returns empty list on error or if not supported.
+        """
+        cache_key = f"calls:{symbol.id}"
+        
+        if self._is_cached(cache_key, symbol.file_path):
+            return self.cache[cache_key].data
+        
+        items: List[CallHierarchyItem] = []
+        
+        if self.use_vscode_bridge:
+            # Legacy: VSCode Bridge HTTP mode
+            result = await self._request_vscode_bridge("get_call_hierarchy", {
+                "file_path": symbol.file_path,
+                "line": symbol.range.start_line,
+                "character": symbol.range.start_character,
+            })
+            
+            if result is None:
+                # Fallback: use references
+                refs = await self.get_references(symbol)
+                for ref in refs:
+                    items.append(CallHierarchyItem(
+                        name=f"caller@{ref.line}",
+                        kind="reference",
+                        file_path=ref.file_path,
+                        range=Range(
+                            start_line=ref.line,
+                            start_character=ref.character,
+                            end_line=ref.line,
+                            end_character=ref.character,
+                        ),
+                        detail="Inferred from reference",
+                    ))
+            elif isinstance(result, list):
+                for item in result:
+                    try:
+                        range_data = item.get("range", {})
+                        start = range_data.get("start", {})
+                        end = range_data.get("end", {})
+                        
+                        items.append(CallHierarchyItem(
+                            name=item.get("name", "unknown"),
+                            kind=item.get("kind", "unknown"),
+                            file_path=item.get("file_path", item.get("uri", "")),
+                            range=Range(
+                                start_line=start.get("line", 0) + 1,
+                                start_character=start.get("character", 0) + 1,
+                                end_line=end.get("line", 0) + 1,
+                                end_character=end.get("character", 0) + 1,
+                            ),
+                            detail=item.get("detail"),
+                        ))
+                    except (KeyError, TypeError):
+                        continue
+        else:
+            # Default: Standalone mode
+            manager = await self._ensure_manager()
+            
+            # Try to get call hierarchy items
+            hierarchy_items = await manager.get_call_hierarchy_items(
+                file_path=symbol.file_path,
+                line=symbol.range.start_line,
+                character=symbol.range.start_character,
+            )
+            
+            if hierarchy_items:
+                # Get incoming calls for each item
+                for h_item in hierarchy_items:
+                    incoming = await manager.get_incoming_calls(h_item)
+                    for call in incoming:
+                        from_item = call.get("from", {})
+                        range_data = from_item.get("range", {})
+                        start = range_data.get("start", {})
+                        end = range_data.get("end", {})
+                        
+                        # Parse URI
+                        uri = from_item.get("uri", "")
+                        if uri.startswith("file:///"):
+                            fp = uri[8:] if uri[8:9].isalpha() and uri[9:10] == ":" else uri[7:]
+                        elif uri.startswith("file://"):
+                            fp = uri[7:]
+                        else:
+                            fp = uri
+                        
+                        items.append(CallHierarchyItem(
+                            name=from_item.get("name", "unknown"),
+                            kind=str(from_item.get("kind", "unknown")),
+                            file_path=fp,
+                            range=Range(
+                                start_line=start.get("line", 0) + 1,
+                                start_character=start.get("character", 0) + 1,
+                                end_line=end.get("line", 0) + 1,
+                                end_character=end.get("character", 0) + 1,
+                            ),
+                            detail=from_item.get("detail"),
+                        ))
+            else:
+                # Fallback: use references
+                refs = await self.get_references(symbol)
+                for ref in refs:
+                    items.append(CallHierarchyItem(
+                        name=f"caller@{ref.line}",
+                        kind="reference",
+                        file_path=ref.file_path,
+                        range=Range(
+                            start_line=ref.line,
+                            start_character=ref.character,
+                            end_line=ref.line,
+                            end_character=ref.character,
+                        ),
+                        detail="Inferred from reference",
+                    ))
+        
+        self._cache(cache_key, symbol.file_path, items)
+        return items
+    
+    async def get_document_symbols(self, file_path: str) -> List[Dict[str, Any]]:
+        """Get all symbols in a document (batch operation).
+
+        This is more efficient than individual hover queries when processing
+        multiple locations in the same file.
+
+        Args:
+            file_path: Path to the source file
+
+        Returns:
+            List of symbol dictionaries with name, kind, range, etc.
+            Returns empty list on error or timeout.
+        """
+        cache_key = f"symbols:{file_path}"
+
+        if self._is_cached(cache_key, file_path):
+            return self.cache[cache_key].data
+
+        symbols: List[Dict[str, Any]] = []
+
+        if self.use_vscode_bridge:
+            # Legacy: VSCode Bridge HTTP mode
+            result = await self._request_vscode_bridge("get_document_symbols", {
+                "file_path": file_path,
+            })
+
+            if isinstance(result, list):
+                symbols = self._flatten_document_symbols(result)
+        else:
+            # Default: Standalone mode
+            manager = await self._ensure_manager()
+            result = await manager.get_document_symbols(file_path)
+            
+            if result:
+                symbols = self._flatten_document_symbols(result)
+
+        self._cache(cache_key, file_path, symbols)
+        return symbols
+
+    def _flatten_document_symbols(
+        self, symbols: List[Dict[str, Any]], parent_name: str = ""
+    ) -> List[Dict[str, Any]]:
+        """Flatten nested document symbols into a flat list.
+
+        Document symbols can be nested (e.g., methods inside classes).
+        This flattens them for easier lookup by line number.
+
+        Args:
+            symbols: List of symbol dictionaries (may be nested)
+            parent_name: Name of parent symbol for qualification
+
+        Returns:
+            Flat list of all symbols with their ranges
+        """
+        flat: List[Dict[str, Any]] = []
+
+        for sym in symbols:
+            # Add the symbol itself
+            symbol_entry = {
+                "name": sym.get("name", "unknown"),
+                "kind": self._symbol_kind_to_string(sym.get("kind", 0)),
+                "range": sym.get("range", sym.get("location", {}).get("range", {})),
+                "selection_range": sym.get("selectionRange", {}),
+                "detail": sym.get("detail", ""),
+                "parent": parent_name,
+            }
+            flat.append(symbol_entry)
+
+            # Recursively process children
+            children = sym.get("children", [])
+            if children:
+                qualified_name = sym.get("name", "")
+                if parent_name:
+                    qualified_name = f"{parent_name}.{qualified_name}"
+                flat.extend(self._flatten_document_symbols(children, qualified_name))
+
+        return flat
+
+    def _symbol_kind_to_string(self, kind: int) -> str:
+        """Convert LSP SymbolKind integer to string.
+
+        Args:
+            kind: LSP SymbolKind enum value
+
+        Returns:
+            Human-readable string representation
+        """
+        # LSP SymbolKind enum (1-indexed)
+        kinds = {
+            1: "file",
+            2: "module",
+            3: "namespace",
+            4: "package",
+            5: "class",
+            6: "method",
+            7: "property",
+            8: "field",
+            9: "constructor",
+            10: "enum",
+            11: "interface",
+            12: "function",
+            13: "variable",
+            14: "constant",
+            15: "string",
+            16: "number",
+            17: "boolean",
+            18: "array",
+            19: "object",
+            20: "key",
+            21: "null",
+            22: "enum_member",
+            23: "struct",
+            24: "event",
+            25: "operator",
+            26: "type_parameter",
+        }
+        return kinds.get(kind, "unknown")
+
+    async def get_hover(self, symbol: CodeSymbolNode) -> Optional[str]:
+        """Get hover documentation for a symbol.
+
+        Args:
+            symbol: The code symbol to get hover info for
+
+        Returns:
+            Hover documentation as string, or None if not available
+        """
+        cache_key = f"hover:{symbol.id}"
+        
+        if self._is_cached(cache_key, symbol.file_path):
+            return self.cache[cache_key].data
+        
+        hover_text: Optional[str] = None
+        
+        if self.use_vscode_bridge:
+            # Legacy: VSCode Bridge HTTP mode
+            result = await self._request_vscode_bridge("get_hover", {
+                "file_path": symbol.file_path,
+                "line": symbol.range.start_line,
+                "character": symbol.range.start_character,
+            })
+            
+            if result:
+                hover_text = self._parse_hover_result(result)
+        else:
+            # Default: Standalone mode
+            manager = await self._ensure_manager()
+            hover_text = await manager.get_hover(
+                file_path=symbol.file_path,
+                line=symbol.range.start_line,
+                character=symbol.range.start_character,
+            )
+        
+        self._cache(cache_key, symbol.file_path, hover_text)
+        return hover_text
+    
+    def _parse_hover_result(self, result: Any) -> Optional[str]:
+        """Parse hover result into string."""
+        if isinstance(result, str):
+            return result
+        elif isinstance(result, list):
+            parts = []
+            for item in result:
+                if isinstance(item, str):
+                    parts.append(item)
+                elif isinstance(item, dict):
+                    value = item.get("value", item.get("contents", ""))
+                    if value:
+                        parts.append(str(value))
+            return "\n\n".join(parts) if parts else None
+        elif isinstance(result, dict):
+            contents = result.get("contents", result.get("value", ""))
+            if isinstance(contents, str):
+                return contents
+            elif isinstance(contents, list):
+                parts = []
+                for c in contents:
+                    if isinstance(c, str):
+                        parts.append(c)
+                    elif isinstance(c, dict):
+                        parts.append(str(c.get("value", "")))
+                return "\n\n".join(parts) if parts else None
+        return None
+    
+    async def __aenter__(self) -> "LspBridge":
+        """Async context manager entry."""
+        return self
+    
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Async context manager exit - close connections."""
+        await self.close()
+
+
+# Simple test
+if __name__ == "__main__":
+    import sys
+    
+    async def test_lsp_bridge():
+        """Simple test of LspBridge functionality."""
+        print("Testing LspBridge (Standalone Mode)...")
+        print(f"Timeout: {LspBridge.DEFAULT_TIMEOUT}s")
+        print(f"Cache TTL: {LspBridge.DEFAULT_CACHE_TTL}s")
+        print()
+        
+        # Create a test symbol pointing to this file
+        test_file = os.path.abspath(__file__)
+        test_symbol = CodeSymbolNode(
+            id=f"{test_file}:LspBridge:96",
+            name="LspBridge",
+            kind="class",
+            file_path=test_file,
+            range=Range(
+                start_line=96,
+                start_character=1,
+                end_line=200,
+                end_character=1,
+            ),
+        )
+        
+        print(f"Test symbol: {test_symbol.name} in {os.path.basename(test_symbol.file_path)}")
+        print()
+        
+        # Use standalone mode (default)
+        async with LspBridge(
+            workspace_root=str(Path(__file__).parent.parent.parent.parent),
+        ) as bridge:
+            print("1. Testing get_document_symbols...")
+            try:
+                symbols = await bridge.get_document_symbols(test_file)
+                print(f"   Found {len(symbols)} symbols")
+                for sym in symbols[:5]:
+                    print(f"   - {sym.get('name')} ({sym.get('kind')})")
+            except Exception as e:
+                print(f"   Error: {e}")
+            
+            print()
+            print("2. Testing get_definition...")
+            try:
+                definition = await bridge.get_definition(test_symbol)
+                if definition:
+                    print(f"   Definition: {os.path.basename(definition.file_path)}:{definition.line}")
+                else:
+                    print("   No definition found")
+            except Exception as e:
+                print(f"   Error: {e}")
+            
+            print()
+            print("3. Testing get_references...")
+            try:
+                refs = await bridge.get_references(test_symbol)
+                print(f"   Found {len(refs)} references")
+                for ref in refs[:3]:
+                    print(f"   - {os.path.basename(ref.file_path)}:{ref.line}")
+            except Exception as e:
+                print(f"   Error: {e}")
+            
+            print()
+            print("4. Testing get_hover...")
+            try:
+                hover = await bridge.get_hover(test_symbol)
+                if hover:
+                    print(f"   Hover: {hover[:100]}...")
+                else:
+                    print("   No hover info found")
+            except Exception as e:
+                print(f"   Error: {e}")
+            
+            print()
+            print("5. Testing get_call_hierarchy...")
+            try:
+                calls = await bridge.get_call_hierarchy(test_symbol)
+                print(f"   Found {len(calls)} call hierarchy items")
+                for call in calls[:3]:
+                    print(f"   - {call.name} in {os.path.basename(call.file_path)}")
+            except Exception as e:
+                print(f"   Error: {e}")
+            
+            print()
+            print("6. Testing cache...")
+            print(f"   Cache entries: {len(bridge.cache)}")
+            for key in list(bridge.cache.keys())[:5]:
+                print(f"   - {key}")
+        
+        print()
+        print("Test complete!")
+
+    # Run the test
+    # Note: On Windows, use default ProactorEventLoop (supports subprocess creation)
+
+    asyncio.run(test_lsp_bridge())

codex-lens/build/lib/codexlens/lsp/lsp_graph_builder.py

@@ -0,0 +1,375 @@
+"""Graph builder for code association graphs via LSP."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from codexlens.hybrid_search.data_structures import (
+    CallHierarchyItem,
+    CodeAssociationGraph,
+    CodeSymbolNode,
+    Range,
+)
+from codexlens.lsp.lsp_bridge import (
+    Location,
+    LspBridge,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LspGraphBuilder:
+    """Builds code association graph by expanding from seed symbols using LSP."""
+
+    def __init__(
+        self,
+        max_depth: int = 2,
+        max_nodes: int = 100,
+        max_concurrent: int = 10,
+    ):
+        """Initialize GraphBuilder.
+
+        Args:
+            max_depth: Maximum depth for BFS expansion from seeds.
+            max_nodes: Maximum number of nodes in the graph.
+            max_concurrent: Maximum concurrent LSP requests.
+        """
+        self.max_depth = max_depth
+        self.max_nodes = max_nodes
+        self.max_concurrent = max_concurrent
+        # Cache for document symbols per file (avoids per-location hover queries)
+        self._document_symbols_cache: Dict[str, List[Dict[str, Any]]] = {}
+
+    async def build_from_seeds(
+        self,
+        seeds: List[CodeSymbolNode],
+        lsp_bridge: LspBridge,
+    ) -> CodeAssociationGraph:
+        """Build association graph by BFS expansion from seeds.
+
+        For each seed:
+        1. Get references via LSP
+        2. Get call hierarchy via LSP
+        3. Add nodes and edges to graph
+        4. Continue expanding until max_depth or max_nodes reached
+
+        Args:
+            seeds: Initial seed symbols to expand from.
+            lsp_bridge: LSP bridge for querying language servers.
+
+        Returns:
+            CodeAssociationGraph with expanded nodes and relationships.
+        """
+        graph = CodeAssociationGraph()
+        visited: Set[str] = set()
+        semaphore = asyncio.Semaphore(self.max_concurrent)
+
+        # Initialize queue with seeds at depth 0
+        queue: List[Tuple[CodeSymbolNode, int]] = [(s, 0) for s in seeds]
+
+        # Add seed nodes to graph
+        for seed in seeds:
+            graph.add_node(seed)
+
+        # BFS expansion
+        while queue and len(graph.nodes) < self.max_nodes:
+            # Take a batch of nodes from queue
+            batch_size = min(self.max_concurrent, len(queue))
+            batch = queue[:batch_size]
+            queue = queue[batch_size:]
+
+            # Expand nodes in parallel
+            tasks = [
+                self._expand_node(
+                    node, depth, graph, lsp_bridge, visited, semaphore
+                )
+                for node, depth in batch
+            ]
+
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            # Process results and add new nodes to queue
+            for result in results:
+                if isinstance(result, Exception):
+                    logger.warning("Error expanding node: %s", result)
+                    continue
+                if result:
+                    # Add new nodes to queue if not at max depth
+                    for new_node, new_depth in result:
+                        if (
+                            new_depth <= self.max_depth
+                            and len(graph.nodes) < self.max_nodes
+                        ):
+                            queue.append((new_node, new_depth))
+
+        return graph
+
+    async def _expand_node(
+        self,
+        node: CodeSymbolNode,
+        depth: int,
+        graph: CodeAssociationGraph,
+        lsp_bridge: LspBridge,
+        visited: Set[str],
+        semaphore: asyncio.Semaphore,
+    ) -> List[Tuple[CodeSymbolNode, int]]:
+        """Expand a single node, return new nodes to process.
+
+        Args:
+            node: Node to expand.
+            depth: Current depth in BFS.
+            graph: Graph to add nodes and edges to.
+            lsp_bridge: LSP bridge for queries.
+            visited: Set of visited node IDs.
+            semaphore: Semaphore for concurrency control.
+
+        Returns:
+            List of (new_node, new_depth) tuples to add to queue.
+        """
+        # Skip if already visited or at max depth
+        if node.id in visited:
+            return []
+        if depth > self.max_depth:
+            return []
+        if len(graph.nodes) >= self.max_nodes:
+            return []
+
+        visited.add(node.id)
+        new_nodes: List[Tuple[CodeSymbolNode, int]] = []
+
+        async with semaphore:
+            # Get relationships in parallel
+            try:
+                refs_task = lsp_bridge.get_references(node)
+                calls_task = lsp_bridge.get_call_hierarchy(node)
+
+                refs, calls = await asyncio.gather(
+                    refs_task, calls_task, return_exceptions=True
+                )
+
+                # Handle reference results
+                if isinstance(refs, Exception):
+                    logger.debug(
+                        "Failed to get references for %s: %s", node.id, refs
+                    )
+                    refs = []
+
+                # Handle call hierarchy results
+                if isinstance(calls, Exception):
+                    logger.debug(
+                        "Failed to get call hierarchy for %s: %s",
+                        node.id,
+                        calls,
+                    )
+                    calls = []
+
+                # Process references
+                for ref in refs:
+                    if len(graph.nodes) >= self.max_nodes:
+                        break
+
+                    ref_node = await self._location_to_node(ref, lsp_bridge)
+                    if ref_node and ref_node.id != node.id:
+                        if ref_node.id not in graph.nodes:
+                            graph.add_node(ref_node)
+                            new_nodes.append((ref_node, depth + 1))
+                        # Use add_edge since both nodes should exist now
+                        graph.add_edge(node.id, ref_node.id, "references")
+
+                # Process call hierarchy (incoming calls)
+                for call in calls:
+                    if len(graph.nodes) >= self.max_nodes:
+                        break
+
+                    call_node = await self._call_hierarchy_to_node(
+                        call, lsp_bridge
+                    )
+                    if call_node and call_node.id != node.id:
+                        if call_node.id not in graph.nodes:
+                            graph.add_node(call_node)
+                            new_nodes.append((call_node, depth + 1))
+                        # Incoming call: call_node calls node
+                        graph.add_edge(call_node.id, node.id, "calls")
+
+            except Exception as e:
+                logger.warning(
+                    "Error during node expansion for %s: %s", node.id, e
+                )
+
+        return new_nodes
+
+    def clear_cache(self) -> None:
+        """Clear the document symbols cache.
+
+        Call this between searches to free memory and ensure fresh data.
+        """
+        self._document_symbols_cache.clear()
+
+    async def _get_symbol_at_location(
+        self,
+        file_path: str,
+        line: int,
+        lsp_bridge: LspBridge,
+    ) -> Optional[Dict[str, Any]]:
+        """Find symbol at location using cached document symbols.
+
+        This is much more efficient than individual hover queries because
+        document symbols are fetched once per file and cached.
+
+        Args:
+            file_path: Path to the source file.
+            line: Line number (1-based).
+            lsp_bridge: LSP bridge for fetching document symbols.
+
+        Returns:
+            Symbol dictionary with name, kind, range, etc., or None if not found.
+        """
+        # Get or fetch document symbols for this file
+        if file_path not in self._document_symbols_cache:
+            symbols = await lsp_bridge.get_document_symbols(file_path)
+            self._document_symbols_cache[file_path] = symbols
+
+        symbols = self._document_symbols_cache[file_path]
+
+        # Find symbol containing this line (best match = smallest range)
+        best_match: Optional[Dict[str, Any]] = None
+        best_range_size = float("inf")
+
+        for symbol in symbols:
+            sym_range = symbol.get("range", {})
+            start = sym_range.get("start", {})
+            end = sym_range.get("end", {})
+
+            # LSP ranges are 0-based, our line is 1-based
+            start_line = start.get("line", 0) + 1
+            end_line = end.get("line", 0) + 1
+
+            if start_line <= line <= end_line:
+                range_size = end_line - start_line
+                if range_size < best_range_size:
+                    best_match = symbol
+                    best_range_size = range_size
+
+        return best_match
+
+    async def _location_to_node(
+        self,
+        location: Location,
+        lsp_bridge: LspBridge,
+    ) -> Optional[CodeSymbolNode]:
+        """Convert LSP location to CodeSymbolNode.
+
+        Uses cached document symbols instead of individual hover queries
+        for better performance.
+
+        Args:
+            location: LSP location to convert.
+            lsp_bridge: LSP bridge for additional queries.
+
+        Returns:
+            CodeSymbolNode or None if conversion fails.
+        """
+        try:
+            file_path = location.file_path
+            start_line = location.line
+
+            # Try to find symbol info from cached document symbols (fast)
+            symbol_info = await self._get_symbol_at_location(
+                file_path, start_line, lsp_bridge
+            )
+
+            if symbol_info:
+                name = symbol_info.get("name", f"symbol_L{start_line}")
+                kind = symbol_info.get("kind", "unknown")
+
+                # Extract range from symbol if available
+                sym_range = symbol_info.get("range", {})
+                start = sym_range.get("start", {})
+                end = sym_range.get("end", {})
+
+                location_range = Range(
+                    start_line=start.get("line", start_line - 1) + 1,
+                    start_character=start.get("character", location.character - 1) + 1,
+                    end_line=end.get("line", start_line - 1) + 1,
+                    end_character=end.get("character", location.character - 1) + 1,
+                )
+            else:
+                # Fallback to basic node without symbol info
+                name = f"symbol_L{start_line}"
+                kind = "unknown"
+                location_range = Range(
+                    start_line=location.line,
+                    start_character=location.character,
+                    end_line=location.line,
+                    end_character=location.character,
+                )
+
+            node_id = self._create_node_id(file_path, name, start_line)
+
+            return CodeSymbolNode(
+                id=node_id,
+                name=name,
+                kind=kind,
+                file_path=file_path,
+                range=location_range,
+                docstring="",  # Skip hover for performance
+            )
+
+        except Exception as e:
+            logger.debug("Failed to convert location to node: %s", e)
+            return None
+
+    async def _call_hierarchy_to_node(
+        self,
+        call_item: CallHierarchyItem,
+        lsp_bridge: LspBridge,
+    ) -> Optional[CodeSymbolNode]:
+        """Convert CallHierarchyItem to CodeSymbolNode.
+
+        Args:
+            call_item: Call hierarchy item to convert.
+            lsp_bridge: LSP bridge (unused, kept for API consistency).
+
+        Returns:
+            CodeSymbolNode or None if conversion fails.
+        """
+        try:
+            file_path = call_item.file_path
+            name = call_item.name
+            start_line = call_item.range.start_line
+            # CallHierarchyItem.kind is already a string
+            kind = call_item.kind
+
+            node_id = self._create_node_id(file_path, name, start_line)
+
+            return CodeSymbolNode(
+                id=node_id,
+                name=name,
+                kind=kind,
+                file_path=file_path,
+                range=call_item.range,
+                docstring=call_item.detail or "",
+            )
+
+        except Exception as e:
+            logger.debug(
+                "Failed to convert call hierarchy item to node: %s", e
+            )
+            return None
+
+    def _create_node_id(
+        self, file_path: str, name: str, line: int
+    ) -> str:
+        """Create unique node ID.
+
+        Args:
+            file_path: Path to the file.
+            name: Symbol name.
+            line: Line number (0-based).
+
+        Returns:
+            Unique node ID string.
+        """
+        return f"{file_path}:{name}:{line}"

codex-lens/build/lib/codexlens/lsp/providers.py

@@ -0,0 +1,177 @@
+"""LSP feature providers."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from codexlens.storage.global_index import GlobalSymbolIndex
+    from codexlens.storage.registry import RegistryStore
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HoverInfo:
+    """Hover information for a symbol."""
+
+    name: str
+    kind: str
+    signature: str
+    documentation: Optional[str]
+    file_path: str
+    line_range: tuple  # (start_line, end_line)
+
+
+class HoverProvider:
+    """Provides hover information for symbols."""
+
+    def __init__(
+        self,
+        global_index: "GlobalSymbolIndex",
+        registry: Optional["RegistryStore"] = None,
+    ) -> None:
+        """Initialize hover provider.
+
+        Args:
+            global_index: Global symbol index for lookups
+            registry: Optional registry store for index path resolution
+        """
+        self.global_index = global_index
+        self.registry = registry
+
+    def get_hover_info(self, symbol_name: str) -> Optional[HoverInfo]:
+        """Get hover information for a symbol.
+
+        Args:
+            symbol_name: Name of the symbol to look up
+
+        Returns:
+            HoverInfo or None if symbol not found
+        """
+        # Look up symbol in global index using exact match
+        symbols = self.global_index.search(
+            name=symbol_name,
+            limit=1,
+            prefix_mode=False,
+        )
+
+        # Filter for exact name match
+        exact_matches = [s for s in symbols if s.name == symbol_name]
+
+        if not exact_matches:
+            return None
+
+        symbol = exact_matches[0]
+
+        # Extract signature from source file
+        signature = self._extract_signature(symbol)
+
+        # Symbol uses 'file' attribute and 'range' tuple
+        file_path = symbol.file or ""
+        start_line, end_line = symbol.range
+
+        return HoverInfo(
+            name=symbol.name,
+            kind=symbol.kind,
+            signature=signature,
+            documentation=None,  # Symbol doesn't have docstring field
+            file_path=file_path,
+            line_range=(start_line, end_line),
+        )
+
+    def _extract_signature(self, symbol) -> str:
+        """Extract function/class signature from source file.
+
+        Args:
+            symbol: Symbol object with file and range information
+
+        Returns:
+            Extracted signature string or fallback kind + name
+        """
+        try:
+            file_path = Path(symbol.file) if symbol.file else None
+            if not file_path or not file_path.exists():
+                return f"{symbol.kind} {symbol.name}"
+
+            content = file_path.read_text(encoding="utf-8", errors="ignore")
+            lines = content.split("\n")
+
+            # Extract signature lines (first line of definition + continuation)
+            start_line = symbol.range[0] - 1  # Convert 1-based to 0-based
+            if start_line >= len(lines) or start_line < 0:
+                return f"{symbol.kind} {symbol.name}"
+
+            signature_lines = []
+            first_line = lines[start_line]
+            signature_lines.append(first_line)
+
+            # Continue if multiline signature (no closing paren + colon yet)
+            # Look for patterns like "def func(", "class Foo(", etc.
+            i = start_line + 1
+            max_lines = min(start_line + 5, len(lines))
+            while i < max_lines:
+                line = signature_lines[-1]
+                # Stop if we see closing pattern
+                if "):" in line or line.rstrip().endswith(":"):
+                    break
+                signature_lines.append(lines[i])
+                i += 1
+
+            return "\n".join(signature_lines)
+
+        except Exception as e:
+            logger.debug(f"Failed to extract signature for {symbol.name}: {e}")
+            return f"{symbol.kind} {symbol.name}"
+
+    def format_hover_markdown(self, info: HoverInfo) -> str:
+        """Format hover info as Markdown.
+
+        Args:
+            info: HoverInfo object to format
+
+        Returns:
+            Markdown-formatted hover content
+        """
+        parts = []
+
+        # Detect language for code fence based on file extension
+        ext = Path(info.file_path).suffix.lower() if info.file_path else ""
+        lang_map = {
+            ".py": "python",
+            ".js": "javascript",
+            ".ts": "typescript",
+            ".tsx": "typescript",
+            ".jsx": "javascript",
+            ".java": "java",
+            ".go": "go",
+            ".rs": "rust",
+            ".c": "c",
+            ".cpp": "cpp",
+            ".h": "c",
+            ".hpp": "cpp",
+            ".cs": "csharp",
+            ".rb": "ruby",
+            ".php": "php",
+        }
+        lang = lang_map.get(ext, "")
+
+        # Code block with signature
+        parts.append(f"```{lang}\n{info.signature}\n```")
+
+        # Documentation if available
+        if info.documentation:
+            parts.append(f"\n---\n\n{info.documentation}")
+
+        # Location info
+        file_name = Path(info.file_path).name if info.file_path else "unknown"
+        parts.append(
+            f"\n---\n\n*{info.kind}* defined in "
+            f"`{file_name}` "
+            f"(line {info.line_range[0]})"
+        )
+
+        return "\n".join(parts)

codex-lens/build/lib/codexlens/lsp/server.py

@@ -0,0 +1,263 @@
+"""codex-lens LSP Server implementation using pygls.
+
+This module provides the main Language Server class and entry point.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import Optional
+
+try:
+    from lsprotocol import types as lsp
+    from pygls.lsp.server import LanguageServer
+except ImportError as exc:
+    raise ImportError(
+        "LSP dependencies not installed. Install with: pip install codex-lens[lsp]"
+    ) from exc
+
+from codexlens.config import Config
+from codexlens.search.chain_search import ChainSearchEngine
+from codexlens.storage.global_index import GlobalSymbolIndex
+from codexlens.storage.path_mapper import PathMapper
+from codexlens.storage.registry import RegistryStore
+
+logger = logging.getLogger(__name__)
+
+
+class CodexLensLanguageServer(LanguageServer):
+    """Language Server for codex-lens code indexing.
+
+    Provides IDE features using codex-lens symbol index:
+    - Go to Definition
+    - Find References
+    - Code Completion
+    - Hover Information
+    - Workspace Symbol Search
+
+    Attributes:
+        registry: Global project registry for path lookups
+        mapper: Path mapper for source/index conversions
+        global_index: Project-wide symbol index
+        search_engine: Chain search engine for symbol search
+        workspace_root: Current workspace root path
+    """
+
+    def __init__(self) -> None:
+        super().__init__(name="codexlens-lsp", version="0.1.0")
+
+        self.registry: Optional[RegistryStore] = None
+        self.mapper: Optional[PathMapper] = None
+        self.global_index: Optional[GlobalSymbolIndex] = None
+        self.search_engine: Optional[ChainSearchEngine] = None
+        self.workspace_root: Optional[Path] = None
+        self._config: Optional[Config] = None
+
+    def initialize_components(self, workspace_root: Path) -> bool:
+        """Initialize codex-lens components for the workspace.
+
+        Args:
+            workspace_root: Root path of the workspace
+
+        Returns:
+            True if initialization succeeded, False otherwise
+        """
+        self.workspace_root = workspace_root.resolve()
+        logger.info("Initializing codex-lens for workspace: %s", self.workspace_root)
+
+        try:
+            # Initialize registry
+            self.registry = RegistryStore()
+            self.registry.initialize()
+
+            # Initialize path mapper
+            self.mapper = PathMapper()
+
+            # Try to find project in registry
+            project_info = self.registry.find_by_source_path(str(self.workspace_root))
+
+            if project_info:
+                project_id = int(project_info["id"])
+                index_root = Path(project_info["index_root"])
+
+                # Initialize global symbol index
+                global_db = index_root / GlobalSymbolIndex.DEFAULT_DB_NAME
+                self.global_index = GlobalSymbolIndex(global_db, project_id)
+                self.global_index.initialize()
+
+                # Initialize search engine
+                self._config = Config()
+                self.search_engine = ChainSearchEngine(
+                    registry=self.registry,
+                    mapper=self.mapper,
+                    config=self._config,
+                )
+
+                logger.info("codex-lens initialized for project: %s", project_info["source_root"])
+                return True
+            else:
+                logger.warning(
+                    "Workspace not indexed by codex-lens: %s. "
+                    "Run 'codexlens index %s' to index first.",
+                    self.workspace_root,
+                    self.workspace_root,
+                )
+                return False
+
+        except Exception as exc:
+            logger.error("Failed to initialize codex-lens: %s", exc)
+            return False
+
+    def shutdown_components(self) -> None:
+        """Clean up codex-lens components."""
+        if self.global_index:
+            try:
+                self.global_index.close()
+            except Exception as exc:
+                logger.debug("Error closing global index: %s", exc)
+            self.global_index = None
+
+        if self.search_engine:
+            try:
+                self.search_engine.close()
+            except Exception as exc:
+                logger.debug("Error closing search engine: %s", exc)
+            self.search_engine = None
+
+        if self.registry:
+            try:
+                self.registry.close()
+            except Exception as exc:
+                logger.debug("Error closing registry: %s", exc)
+            self.registry = None
+
+
+# Create server instance
+server = CodexLensLanguageServer()
+
+
+@server.feature(lsp.INITIALIZE)
+def lsp_initialize(params: lsp.InitializeParams) -> lsp.InitializeResult:
+    """Handle LSP initialize request."""
+    logger.info("LSP initialize request received")
+
+    # Get workspace root
+    workspace_root: Optional[Path] = None
+    if params.root_uri:
+        workspace_root = Path(params.root_uri.replace("file://", "").replace("file:", ""))
+    elif params.root_path:
+        workspace_root = Path(params.root_path)
+
+    if workspace_root:
+        server.initialize_components(workspace_root)
+
+    # Declare server capabilities
+    return lsp.InitializeResult(
+        capabilities=lsp.ServerCapabilities(
+            text_document_sync=lsp.TextDocumentSyncOptions(
+                open_close=True,
+                change=lsp.TextDocumentSyncKind.Incremental,
+                save=lsp.SaveOptions(include_text=False),
+            ),
+            definition_provider=True,
+            references_provider=True,
+            completion_provider=lsp.CompletionOptions(
+                trigger_characters=[".", ":"],
+                resolve_provider=False,
+            ),
+            hover_provider=True,
+            workspace_symbol_provider=True,
+        ),
+        server_info=lsp.ServerInfo(
+            name="codexlens-lsp",
+            version="0.1.0",
+        ),
+    )
+
+
+@server.feature(lsp.SHUTDOWN)
+def lsp_shutdown(params: None) -> None:
+    """Handle LSP shutdown request."""
+    logger.info("LSP shutdown request received")
+    server.shutdown_components()
+
+
+def main() -> int:
+    """Entry point for codexlens-lsp command.
+
+    Returns:
+        Exit code (0 for success)
+    """
+    # Import handlers to register them with the server
+    # This must be done before starting the server
+    import codexlens.lsp.handlers  # noqa: F401
+
+    parser = argparse.ArgumentParser(
+        description="codex-lens Language Server",
+        prog="codexlens-lsp",
+    )
+    parser.add_argument(
+        "--stdio",
+        action="store_true",
+        default=True,
+        help="Use stdio for communication (default)",
+    )
+    parser.add_argument(
+        "--tcp",
+        action="store_true",
+        help="Use TCP for communication",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="TCP host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=2087,
+        help="TCP port (default: 2087)",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Log level (default: INFO)",
+    )
+    parser.add_argument(
+        "--log-file",
+        help="Log file path (optional)",
+    )
+
+    args = parser.parse_args()
+
+    # Configure logging
+    log_handlers = []
+    if args.log_file:
+        log_handlers.append(logging.FileHandler(args.log_file))
+    else:
+        log_handlers.append(logging.StreamHandler(sys.stderr))
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=log_handlers,
+    )
+
+    logger.info("Starting codexlens-lsp server")
+
+    if args.tcp:
+        logger.info("Starting TCP server on %s:%d", args.host, args.port)
+        server.start_tcp(args.host, args.port)
+    else:
+        logger.info("Starting stdio server")
+        server.start_io()
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())