@ngocsangairvds/vsaf 3.2.13 → 3.2.15

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

@@ -1,957 +0,0 @@
-"""Minimal JSON-RPC LSP client over stdio."""
-
-import json
-import logging
-import os
-import shlex
-import shutil
-import subprocess
-import threading
-import time
-from concurrent.futures import Future
-from pathlib import Path
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-
-class LspClient:
-    """JSON-RPC Client for LSP servers.
-
-    Supports both native LSP servers and Docker containerized LSP servers.
-    """
-
-    def __init__(
-        self,
-        root: Path,
-        config: Any = None,
-        server_cmd: list[str] | None = None,
-        docker_mode: bool = False,
-    ):
-        self.root = root
-        self.config = config
-        self.docker_mode = (
-            docker_mode or os.environ.get("VDS_LSP_DOCKER_MODE", "").lower() == "true"
-        )
-        self.server_cmd = server_cmd or self._detect_server()
-        self.process: subprocess.Popen[bytes] | None = None
-        self._docker_container: subprocess.Popen[bytes] | None = None
-        self._request_id = 0
-        self._pending_requests: dict[int, Future[Any]] = {}
-        self._listener_thread: threading.Thread | None = None
-        self._stderr_thread: threading.Thread | None = None
-        self._stop_event = threading.Event()
-        self.timeout = getattr(config, "timeout", 10)
-        self._diagnostics: dict[str, list[dict[str, Any]]] = {}
-        self._open_documents: set[str] = set()  # Track open documents to avoid redundant didOpen
-        self._docker_image = os.environ.get("VDS_LSP_DOCKER_IMAGE", "vds-lsp-orchestrator:latest")
-        self._docker_workspace_mount = os.environ.get("VDS_LSP_DOCKER_WORKSPACE", str(root))
-
-    def _detect_server(self) -> list[str]:
-        """Detect available LSP server."""
-        # 0. Check config override
-        if self.config and getattr(self.config, "server_path", None):
-            override = str(self.config.server_path)
-            if isinstance(override, str) and " " in override:
-                args = shlex.split(override)
-                if "--stdio" not in args:
-                    args.append("--stdio")
-                return args
-            return [override, "--stdio"]
-
-        # Order: basedpyright-langserver -> pyright-langserver -> pylsp
-        for bin_name in ["basedpyright-langserver", "pyright-langserver", "pylsp"]:
-            # Check venv first
-            venv_bin = Path(os.environ.get("VIRTUAL_ENV", "")) / "bin" / bin_name
-            if venv_bin.exists():
-                return [str(venv_bin), "--stdio"]
-
-            # Check system
-            sys_bin = shutil.which(bin_name)
-            if sys_bin:
-                return [sys_bin, "--stdio"]
-
-        raise FileNotFoundError(
-            "No LSP server found (checked basedpyright-langserver, pyright-langserver, pylsp)",
-        )
-
-    def _check_docker_available(self) -> bool:
-        """Check if Docker is available and running."""
-        try:
-            result = subprocess.run(
-                ["docker", "--version"],
-                capture_output=True,
-                text=True,
-                timeout=5,
-            )
-            return result.returncode == 0
-        except FileNotFoundError, subprocess.TimeoutExpired:
-            return False
-
-    def _start_docker_container(self) -> None:
-        """Start LSP server in a Docker container."""
-        if not self._check_docker_available():
-            raise RuntimeError(
-                "Docker mode requested but Docker is not available. "
-                "Install Docker or use native mode."
-            )
-
-        # Prepare Docker command
-        docker_cmd = [
-            "docker",
-            "run",
-            "--rm",
-            "-i",
-            "-v",
-            f"{self.root}:/workspace:rw",
-            "-w",
-            "/workspace",
-            "-e",
-            f"VDS_LSP_TIMEOUT={self.timeout}",
-            "-e",
-            "VDS_LSP_DAEMON_ENABLED=false",  # Run in ephemeral mode
-        ]
-
-        # Pass through relevant environment variables
-        env_vars_to_pass = [
-            "VDS_LSP_LOG_LEVEL",
-            "VDS_LSP_ENABLE_RUFF_LSP",
-            "VDS_LSP_RUFF_SERVER",
-            "VDS_LSP_FIXES_ALLOW_UNSAFE",
-            "VDS_LSP_ENABLE_LANGUAGE_SERVICES",
-            "VDS_LSP_NOTEBOOK_SUPPORT",
-            "VDS_LSP_TYPE_CHECKING_MODE",
-            "VDS_LSP_DIAGNOSTIC_MODE",
-        ]
-        for env_var in env_vars_to_pass:
-            value = os.environ.get(env_var)
-            if value:
-                docker_cmd.extend(["-e", f"{env_var}={value}"])
-
-        # Add image and entrypoint
-        docker_cmd.extend([self._docker_image, "basedpyright-langserver", "--stdio"])
-
-        logger.debug("Starting Docker container: %s", " ".join(docker_cmd))
-
-        try:
-            self._docker_container = subprocess.Popen(
-                docker_cmd,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                cwd=str(self.root),
-            )
-            logger.info("Docker container started with PID: %s", self._docker_container.pid)
-        except Exception as exc:
-            raise RuntimeError(f"Failed to start Docker container: {exc}") from exc
-
-    def _stop_docker_container(self) -> None:
-        """Stop the Docker container."""
-        if not self._docker_container:
-            return
-
-        logger.debug("Stopping Docker container...")
-        try:
-            # Send shutdown signal to LSP server
-            if self._docker_container.stdin:
-                self._docker_container.stdin.close()
-            # Terminate the container (docker run --rm will clean up)
-            self._docker_container.terminate()
-            try:
-                _ = self._docker_container.wait(timeout=5)
-            except subprocess.TimeoutExpired:
-                logger.warning("Docker container did not stop gracefully, forcing...")
-                self._docker_container.kill()
-                _ = self._docker_container.wait()
-        except Exception as exc:
-            logger.warning("Error stopping Docker container: %s", exc)
-        finally:
-            self._docker_container = None
-            logger.debug("Docker container stopped")
-
-    def start(self):
-        """Start the LSP server process.
-
-        In Docker mode, starts a Docker container with the LSP server.
-        In native mode, starts the LSP server directly on the host.
-        """
-        if self.process:
-            return
-
-        if self.docker_mode:
-            self._start_docker_container()
-            self.process = self._docker_container
-        else:
-            self.process = subprocess.Popen(
-                self.server_cmd,
-                stdin=subprocess.PIPE,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                cwd=str(self.root),
-            )
-
-        self._stop_event.clear()
-        self._listener_thread = threading.Thread(target=self._listen, daemon=True)
-        self._listener_thread.start()
-        self._stderr_thread = threading.Thread(target=self._drain_stderr, daemon=True)
-        self._stderr_thread.start()
-
-        # Initialize
-        self.initialize()
-
-        # Configure diagnostic mode from config
-        diagnostic_mode = (
-            getattr(self.config, "diagnostic_mode", "openFilesOnly")
-            if self.config
-            else "openFilesOnly"
-        )
-        self.configure_diagnostic_mode(diagnostic_mode=diagnostic_mode)
-
-        # Configure language services (optimized for CLI context)
-        # Using faster defaults based on community research (Emacs lsp-mode optimization)
-        self.configure_language_services(
-            use_library_code_for_types=False,  # Skip expensive library parsing
-            auto_search_paths=True,
-            type_checking_mode="basic",  # Faster than "standard" for CLI response
-        )
-
-        # Configure auto-format strings (BasedPyright feature)
-        auto_format_strings = (
-            getattr(self.config, "auto_format_strings", True) if self.config else True
-        )
-        self.configure_auto_format_strings(enabled=auto_format_strings)
-
-        logger.info("LSP server started (mode: %s)", "docker" if self.docker_mode else "native")
-
-    def stop(self):
-        """Stop the LSP server.
-
-        In Docker mode, stops the Docker container.
-        In native mode, stops the native LSP server process.
-        """
-        if not self.process:
-            return
-
-        try:
-            self.request("shutdown")
-            self.notify("exit")
-        except Exception as exc:
-            logger.debug("LSP shutdown failed: %s", exc)
-
-        self._stop_event.set()
-        if self.process.stdin:
-            self.process.stdin.close()
-        if self.process.stderr:
-            self.process.stderr.close()
-
-        if self.docker_mode:
-            self._stop_docker_container()
-        else:
-            self.process.terminate()
-            try:
-                _ = self.process.wait(timeout=2)
-            except subprocess.TimeoutExpired:
-                logger.warning("LSP server did not stop gracefully, killing...")
-                self.process.kill()
-                _ = self.process.wait()
-
-        self.process = None
-        logger.info("LSP server stopped")
-
-    def _send(self, data: dict[str, Any]):
-        """Send JSON-RPC message."""
-        if not self.process or not self.process.stdin:
-            raise RuntimeError("LSP server not running")
-
-        body = json.dumps(data, separators=(",", ":"))
-        header = f"Content-Length: {len(body)}\r\n\r\n"
-        _ = self.process.stdin.write(header.encode("ascii"))
-        _ = self.process.stdin.write(body.encode("utf-8"))
-        self.process.stdin.flush()
-
-    def request(self, method: str, params: Any = None, retry_on_timeout: bool = True) -> Any:
-        """Send a request and wait for response.
-
-        Args:
-            method: LSP method name
-            params: LSP method parameters
-            retry_on_timeout: If True, retry once after timeout (helps with slow first-time requests)
-
-        Returns:
-            LSP response result
-
-        Raises:
-            RuntimeError: If request times out (even after retry if enabled)
-        """
-        if not self.process:
-            self.start()
-
-        request_id = self._request_id
-        self._request_id += 1
-
-        message = {
-            "jsonrpc": "2.0",
-            "id": request_id,
-            "method": method,
-        }
-        if params is not None:
-            message["params"] = params
-
-        future: Future[Any] = Future()
-        self._pending_requests[request_id] = future
-
-        logger.debug(
-            "LSP request: Sending %s (id=%s), pending: %s",
-            method,
-            request_id,
-            list(self._pending_requests.keys()),
-        )
-        self._send(message)
-
-        # Wait for response (timeout configurable)
-        try:
-            result = future.result(timeout=self.timeout)
-            logger.debug("LSP request: %s (id=%s) completed successfully", method, request_id)
-            return result
-        except TimeoutError:
-            # Clean up the pending request
-            if request_id in self._pending_requests:
-                del self._pending_requests[request_id]
-
-            # Retry once if enabled (helps with slow first-time LSP requests)
-            if retry_on_timeout:
-                logger.debug(
-                    "LSP request %s (id=%s) timed out after %ds, retrying...",
-                    method,
-                    request_id,
-                    self.timeout,
-                )
-                # Give the server a moment to finish processing
-                # time imported at module level
-                time.sleep(1.0)
-                # Retry the request
-                retry_id = self._request_id
-                self._request_id += 1
-                message["id"] = retry_id
-                retry_future: Future[Any] = Future()
-                self._pending_requests[retry_id] = retry_future
-                logger.debug(
-                    "LSP request: Retry %s (id=%s), pending: %s",
-                    method,
-                    retry_id,
-                    list(self._pending_requests.keys()),
-                )
-                self._send(message)
-                try:
-                    result = retry_future.result(timeout=self.timeout)
-                    logger.debug("LSP request: %s (id=%s retry) succeeded", method, retry_id)
-                    return result
-                except TimeoutError:
-                    if retry_id in self._pending_requests:
-                        del self._pending_requests[retry_id]
-                    logger.warning(
-                        "LSP request %s timed out after retry (%ds total)", method, self.timeout * 2
-                    )
-                    raise RuntimeError(f"LSP request timed out after {self.timeout * 2}s") from None
-
-            logger.warning("LSP request %s timed out after %ds", method, self.timeout)
-            raise RuntimeError(f"LSP request timed out after {self.timeout}s") from None
-        except Exception as e:
-            if request_id in self._pending_requests:
-                del self._pending_requests[request_id]
-            if isinstance(e, TimeoutError):
-                logger.warning("LSP request %s timed out after %ds", method, self.timeout)
-                raise RuntimeError(f"LSP request timed out after {self.timeout}s") from e
-            raise
-
-    def request_with_timeout(self, method: str, params: Any = None, timeout: float = 5.0) -> Any:
-        """Send a request with a custom timeout.
-
-        Args:
-            method: LSP method name
-            params: LSP method parameters
-            timeout: Custom timeout in seconds (default: 5.0 for language services)
-
-        Returns:
-            LSP response result
-
-        Raises:
-            RuntimeError: If request times out
-        """
-        if not self.process:
-            self.start()
-
-        request_id = self._request_id
-        self._request_id += 1
-
-        message = {
-            "jsonrpc": "2.0",
-            "id": request_id,
-            "method": method,
-        }
-        if params is not None:
-            message["params"] = params
-
-        future: Future[Any] = Future()
-        self._pending_requests[request_id] = future
-
-        self._send(message)
-
-        # Wait for response with custom timeout
-        try:
-            return future.result(timeout=timeout)
-        except TimeoutError:
-            # Clean up the pending request
-            if request_id in self._pending_requests:
-                del self._pending_requests[request_id]
-
-            # Retry once with a short delay (helps with slow first-time LSP requests)
-            logger.debug(
-                "LSP request %s timed out after %ds, retrying...",
-                method,
-                timeout,
-            )
-            # time imported at module level
-            time.sleep(1.0)
-
-            retry_id = self._request_id
-            self._request_id += 1
-            message["id"] = retry_id
-            retry_future: Future[Any] = Future()
-            self._pending_requests[retry_id] = retry_future
-            self._send(message)
-            try:
-                result = retry_future.result(timeout=timeout)
-                logger.debug("LSP request %s succeeded on retry", method)
-                return result
-            except TimeoutError:
-                if retry_id in self._pending_requests:
-                    del self._pending_requests[retry_id]
-                logger.warning(
-                    "LSP request %s timed out after retry (%ds total)", method, timeout * 2
-                )
-                raise RuntimeError(f"LSP request timed out after {timeout * 2}s") from None
-        except Exception as e:
-            if request_id in self._pending_requests:
-                del self._pending_requests[request_id]
-            if isinstance(e, TimeoutError):
-                logger.warning("LSP request %s timed out after %ds", method, timeout)
-                raise RuntimeError(f"LSP request timed out after {timeout}s") from e
-            raise
-
-    def notify(self, method: str, params: Any = None):
-        """Send a notification (no response expected)."""
-        if not self.process:
-            self.start()
-
-        message = {
-            "jsonrpc": "2.0",
-            "method": method,
-        }
-        if params is not None:
-            message["params"] = params
-
-        self._send(message)
-
-    def initialize(self):
-        """Send initialize request."""
-        root_uri = self.root.resolve().as_uri()
-        response = self.request(
-            "initialize",
-            {
-                "processId": os.getpid(),
-                "rootUri": root_uri,
-                "capabilities": {
-                    "textDocument": {
-                        "synchronization": {
-                            "dynamicRegistration": True,
-                            "willSave": True,
-                            "didSave": True,
-                            "willSaveWaitUntil": True,
-                        },
-                        "completion": {
-                            "dynamicRegistration": True,
-                            "completionItem": {"snippetSupport": True},
-                        },
-                        "hover": {
-                            "dynamicRegistration": True,
-                            "contentFormat": ["markdown", "plaintext"],
-                        },
-                        "signatureHelp": {
-                            "dynamicRegistration": True,
-                            "signatureInformation": {
-                                "documentationFormat": ["markdown", "plaintext"],
-                            },
-                        },
-                        "definition": {"dynamicRegistration": True},
-                        "references": {"dynamicRegistration": True},
-                        "documentHighlight": {"dynamicRegistration": True},
-                        "documentSymbol": {
-                            "dynamicRegistration": True,
-                            "hierarchicalDocumentSymbolSupport": True,
-                        },
-                        "codeAction": {
-                            "dynamicRegistration": True,
-                            "codeActionLiteralSupport": {
-                                "codeActionKind": {
-                                    "valueSet": [
-                                        "",
-                                        "quickfix",
-                                        "refactor",
-                                        "refactor.extract",
-                                        "refactor.inline",
-                                        "refactor.rewrite",
-                                        "source",
-                                        "source.organizeImports",
-                                    ],
-                                },
-                            },
-                        },
-                        "codeLens": {"dynamicRegistration": True},
-                        "formatting": {"dynamicRegistration": True},
-                        "rangeFormatting": {"dynamicRegistration": True},
-                        "onTypeFormatting": {"dynamicRegistration": True},
-                        "rename": {"dynamicRegistration": True},
-                        "publishDiagnostics": {"relatedInformation": True},
-                        "inlayHint": {"dynamicRegistration": True},
-                        "semanticTokens": {
-                            "dynamicRegistration": True,
-                            "requests": {"full": True},
-                            "formats": ["relative"],
-                            "tokenTypes": [],
-                            "tokenModifiers": [],
-                        },
-                    },
-                    "workspace": {
-                        "symbol": {"dynamicRegistration": True},
-                        "configuration": True,
-                        "workspaceEdit": {"changeAnnotationSupport": {"groupsOnLabel": True}},
-                    },
-                },
-                "workspaceFolders": [{"uri": root_uri, "name": self.root.name}],
-            },
-        )
-        self.notify("initialized", {})
-        return response
-
-    def configure_inlay_hints(
-        self,
-        *,
-        variable_types: bool = True,
-        function_return_types: bool = True,
-        call_argument_names: bool = True,
-        generic_types: bool = True,
-        call_argument_names_matching: bool = False,
-    ) -> None:
-        """Configure BasedPyright inlay hints settings via workspace/didChangeConfiguration.
-
-        Args:
-            variable_types: Show inlay hints on assignments to variables
-            function_return_types: Show inlay hints on function return types
-            call_argument_names: Show inlay hints on function arguments
-            generic_types: Show inlay hints on inferred generic types
-            call_argument_names_matching: Show hints when arg name matches param name
-        """
-        if not self.process:
-            return
-
-        settings = {
-            "basedpyright": {
-                "analysis": {
-                    "inlayHints": {
-                        "variableTypes": variable_types,
-                        "functionReturnTypes": function_return_types,
-                        "callArgumentNames": call_argument_names,
-                        "genericTypes": generic_types,
-                        "callArgumentNamesMatching": call_argument_names_matching,
-                    },
-                },
-            },
-        }
-
-        self.notify("workspace/didChangeConfiguration", {"settings": settings})
-        logger.debug("Configured inlay hints: %s", settings)
-
-    def configure_diagnostic_mode(
-        self,
-        diagnostic_mode: str = "openFilesOnly",
-    ) -> None:
-        """Configure BasedPyright diagnostic mode via workspace/didChangeConfiguration.
-
-        Args:
-            diagnostic_mode: Analysis scope - "openFilesOnly" (default) or "workspace"
-                - "openFilesOnly": Only analyze open files (faster, for large projects)
-                - "workspace": Analyze all files in workspace (slower, more thorough)
-        """
-        if not self.process:
-            return
-
-        settings = {
-            "basedpyright": {
-                "analysis": {
-                    "diagnosticMode": diagnostic_mode,
-                },
-            },
-        }
-
-        self.notify("workspace/didChangeConfiguration", {"settings": settings})
-        logger.debug("Configured diagnostic mode: %s", diagnostic_mode)
-
-    def configure_language_services(
-        self,
-        *,
-        use_library_code_for_types: bool = False,  # Optimized: False is faster for CLI context
-        auto_search_paths: bool = True,
-        type_checking_mode: str = "basic",  # Optimized: "basic" is faster than "standard"
-        disable_language_services: bool = False,
-    ) -> None:
-        """Configure BasedPyright language services via workspace/didChangeConfiguration.
-
-        This configuration is critical for hover, completion, and signature help to work properly.
-
-        Args:
-            use_library_code_for_types: Use library code for type information (False is faster - skips library parsing)
-            auto_search_paths: Enable automatic search path discovery for dependencies
-            type_checking_mode: Type checking mode - "off", "basic", "standard", or "strict" ("basic" for faster CLI response)
-            disable_language_services: Disable ALL language services (hover, completion, etc.)
-
-        Note: Based on community research (Emacs lsp-mode optimization), using "basic" mode
-        and disabling useLibraryCodeForTypes significantly improves hover/completion response times
-        in ephemeral CLI contexts where files are opened/closed quickly.
-        """
-        if not self.process:
-            return
-
-        settings = {
-            "basedpyright": {
-                "analysis": {
-                    "useLibraryCodeForTypes": use_library_code_for_types,
-                    "autoSearchPaths": auto_search_paths,
-                    "typeCheckingMode": type_checking_mode,
-                    "disableLanguageServices": disable_language_services,
-                },
-            },
-        }
-
-        self.notify("workspace/didChangeConfiguration", {"settings": settings})
-        logger.debug(
-            "Configured language services: useLibraryCodeForTypes=%s, autoSearchPaths=%s, typeCheckingMode=%s",
-            use_library_code_for_types,
-            auto_search_paths,
-            type_checking_mode,
-        )
-
-    def configure_auto_format_strings(
-        self,
-        *,
-        enabled: bool = True,
-    ) -> None:
-        """Configure BasedPyright auto-format strings setting via workspace/didChangeConfiguration.
-
-        When enabled, automatically converts strings to f-strings when typing { inside them.
-
-        Args:
-            enabled: Whether to enable auto-format strings (default: True)
-
-        Note: This is a BasedPyright-exclusive feature that improves developer experience
-        by automatically converting strings to f-strings when an opening brace is typed.
-        Setting path: basedpyright.analysis.autoFormatStrings
-        """
-        if not self.process:
-            return
-
-        settings = {
-            "basedpyright": {
-                "analysis": {
-                    "autoFormatStrings": enabled,
-                },
-            },
-        }
-
-        self.notify("workspace/didChangeConfiguration", {"settings": settings})
-        logger.debug("Configured auto-format strings: %s", enabled)
-
-    def reload_configuration(self, config: Any) -> None:
-        """Reload LSP configuration from config object.
-
-        This method is called when configuration files change (hot reload).
-        It re-applies all configuration settings to the running LSP server.
-
-        Args:
-            config: New LSP configuration object
-
-        Note:
-            This method gracefully handles configuration errors and logs warnings
-            without crashing the daemon process.
-        """
-        if not self.process:
-            logger.debug("LSP server not running, skipping config reload")
-            return
-
-        try:
-            # Build complete settings from new config
-            settings: dict[str, Any] = {}
-
-            # BasedPyright settings
-            basedpyright_settings: dict[str, Any] = {"analysis": {}}
-
-            # Diagnostic mode
-            diagnostic_mode = getattr(config, "diagnostic_mode", "openFilesOnly")
-            basedpyright_settings["analysis"]["diagnosticMode"] = diagnostic_mode
-
-            # Type checking mode
-            type_checking_mode = getattr(config, "type_checking_mode", "standard")
-            basedpyright_settings["analysis"]["typeCheckingMode"] = type_checking_mode
-
-            # Auto-format strings
-            auto_format_strings = getattr(config, "auto_format_strings", True)
-            basedpyright_settings["analysis"]["autoFormatStrings"] = auto_format_strings
-
-            # Language services (optimized for CLI context)
-            basedpyright_settings["analysis"]["useLibraryCodeForTypes"] = False
-            basedpyright_settings["analysis"]["autoSearchPaths"] = True
-            basedpyright_settings["analysis"]["disableLanguageServices"] = False
-
-            # Inlay hints
-            basedpyright_settings["analysis"]["inlayHints"] = {
-                "variableTypes": True,
-                "functionReturnTypes": True,
-                "callArgumentNames": True,
-                "genericTypes": True,
-                "callArgumentNamesMatching": False,
-            }
-
-            settings["basedpyright"] = basedpyright_settings
-
-            # Send configuration update to LSP server
-            self.notify("workspace/didChangeConfiguration", {"settings": settings})
-            logger.info(
-                "Configuration reloaded successfully: diagnostic_mode=%s, type_checking_mode=%s",
-                diagnostic_mode,
-                type_checking_mode,
-            )
-
-        except Exception as exc:
-            logger.warning("Failed to reload configuration: %s", exc)
-            # Don't crash the daemon on config errors
-            logger.debug("Config reload error details", exc_info=True)
-
-    def open_document(self, file_path: Path, wait_for_diagnostics: bool = False) -> str:
-        """Open a document in the LSP server and return its URI.
-
-        Args:
-            file_path: Path to the file to open
-            wait_for_diagnostics: If True, wait for publishDiagnostics (default: False)
-
-        Returns:
-            Document URI
-
-        Note:
-            By default, this does NOT wait for diagnostics because BasedPyright
-            with diagnosticMode='openFilesOnly' may not publish diagnostics for
-            clean files. Instead, the LSP request itself will trigger processing.
-
-            The wait_for_diagnostics option can be enabled for specific use cases
-            where you need to verify the file has been fully analyzed before making
-            additional requests.
-        """
-        if not self.process:
-            self.start()
-        uri = file_path.absolute().as_uri()
-
-        # Only send didOpen if document is not already open
-        # Based on LSP spec, sending didOpen multiple times for same document is allowed
-        # but some servers (like BasedPyright) may have issues with it
-        if uri not in self._open_documents:
-            text = file_path.read_text()
-            self.notify(
-                "textDocument/didOpen",
-                {
-                    "textDocument": {
-                        "uri": uri,
-                        "languageId": "python",
-                        "version": 1,
-                        "text": text,
-                    },
-                },
-            )
-            self._open_documents.add(uri)
-
-            if wait_for_diagnostics:
-                # Wait for diagnostics (only useful for files with errors)
-                ready = self.wait_for_document_ready(uri, timeout=5.0)
-                if not ready:
-                    logger.debug(
-                        "LSP server did not publish diagnostics for %s within 5s (file may be clean)",
-                        uri,
-                    )
-            else:
-                # Increased delay to let LSP server process the document
-                # 50ms was too short for BasedPyright on first open
-                # 200ms gives more time for the server to register the document
-                # time imported at module level
-                time.sleep(0.2)
-
-        return uri
-
-    def wait_for_document_ready(self, uri: str, timeout: float = 10.0) -> bool:
-        """Wait for the LSP server to finish processing a document.
-
-        This polls for published diagnostics, which indicates the LSP server
-        has finished analyzing the document.
-
-        Args:
-            uri: Document URI to wait for
-            timeout: Maximum time to wait in seconds (default: 10.0)
-
-        Returns:
-            True if diagnostics were received, False if timeout occurred
-
-        Note:
-            This is a critical synchronization mechanism. LSP servers process
-            documents asynchronously. When we open a document and immediately
-            make a request, the server may not have finished parsing yet. By waiting
-            for diagnostics (which are always published after analysis completes),
-            we ensure the server is ready to handle our request.
-
-            The timeout should be long enough for the LSP server to process even
-            large files with complex imports. Default 10 seconds is reasonable for
-            most files; consider increasing for very large projects.
-        """
-        # time imported at module level
-        start = time.time()
-        while time.time() - start < timeout:
-            if uri in self._diagnostics:
-                logger.debug("LSP server ready for %s (diagnostics received)", uri)
-                return True
-            time.sleep(0.05)
-        logger.warning("LSP server not ready for %s after %ds timeout", uri, timeout)
-        return False
-
-    def close_document(self, uri: str) -> None:
-        """Close a document in the LSP server."""
-        self.notify("textDocument/didClose", {"textDocument": {"uri": uri}})
-        # Remove from open documents tracking
-        self._open_documents.discard(uri)
-
-    def _listen(self):
-        """Listen for responses from stdout."""
-        if not self.process or not self.process.stdout:
-            return
-
-        logger.debug("LSP listener thread started")
-        while not self._stop_event.is_set():
-            try:
-                headers: dict[str, str] = {}
-                while True:
-                    line = self.process.stdout.readline()
-                    if not line:
-                        logger.debug("LSP listener: EOF received, stopping")
-                        return
-                    line = line.decode("ascii").strip()
-                    if not line:
-                        break
-                    if ":" in line:
-                        key, value = line.split(":", 1)
-                        headers[key.strip().lower()] = value.strip()
-
-                if "content-length" not in headers:
-                    logger.debug("LSP listener: No content-length in headers, skipping")
-                    continue
-
-                length = int(headers["content-length"])
-                logger.debug("LSP listener: Reading %d bytes", length)
-                body = self.process.stdout.read(length)
-                message = json.loads(body)
-                logger.debug(
-                    "LSP listener: Received message with id=%s, method=%s",
-                    message.get("id"),
-                    message.get("method"),
-                )
-
-                # CRITICAL: Check method is None FIRST before checking id
-                # This is the correct LSP/JSON-RPC pattern:
-                # - Responses have NO method field (they reply to our requests)
-                # - Notifications have a method but NO id (server-to-client one-way)
-                # - Server requests have BOTH method and id (server asking client something)
-                # We should ONLY match messages with no method field to pending requests
-                if message.get("method") is None and "id" in message:
-                    req_id = message["id"]
-                    if req_id in self._pending_requests:
-                        future = self._pending_requests.pop(req_id)
-                        if "error" in message:
-                            logger.debug("LSP listener: Setting error for request %s", req_id)
-                            future.set_exception(Exception(message["error"]))
-                        else:
-                            logger.debug("LSP listener: Setting result for request %s", req_id)
-                            future.set_result(message.get("result"))
-                    else:
-                        logger.debug(
-                            f"LSP: Response for unknown request ID {req_id} (duplicate or late message)"
-                        )
-                        logger.debug("  Pending requests: %s", list(self._pending_requests.keys()))
-                else:
-                    # Notification (no id) or server request (has both method and id)
-                    method = message.get("method")
-                    msg_id = message.get("id")
-
-                    if method == "textDocument/publishDiagnostics":
-                        params = message.get("params") or {}
-                        uri = params.get("uri")
-                        diagnostics = params.get("diagnostics") or []
-                        if uri:
-                            self._diagnostics[uri] = diagnostics
-                            logger.debug(
-                                "LSP diagnostics for %s: %d items",
-                                uri,
-                                len(diagnostics),
-                            )
-                    # Handle server-initiated requests
-                    elif method and msg_id is not None:
-                        logger.debug(
-                            "LSP server request (not implemented): %s (id=%s)", method, msg_id
-                        )
-                        # Send a generic error response to unblock the server
-                        # Some LSP servers may get stuck if they don't receive a response
-                        self._send(
-                            {
-                                "jsonrpc": "2.0",
-                                "id": msg_id,
-                                "error": {
-                                    "code": -32601,  # Method not implemented
-                                    "message": f"Server request '{method}' not supported by this client",
-                                },
-                            }
-                        )
-                    # Log other notifications for debugging
-                    elif method:
-                        logger.debug("LSP notification: %s", method)
-
-            except Exception as e:
-                logger.exception(f"LSP listener error: {e}")
-                logger.debug(
-                    "LSP listener: Pending requests at error: %s",
-                    list(self._pending_requests.keys()),
-                )
-                break
-
-        logger.debug("LSP listener thread stopped")
-
-    def _drain_stderr(self) -> None:
-        """Drain stderr to avoid blocking if the server logs heavily."""
-        if not self.process or not self.process.stderr:
-            return
-        while not self._stop_event.is_set():
-            line = self.process.stderr.readline()
-            if not line:
-                break
-            try:
-                text = line.decode("utf-8", errors="replace").rstrip()
-            except Exception:
-                text = repr(line)
-            if text:
-                logger.debug("LSP stderr: %s", text)
-
-    def get_published_diagnostics(self, uri: str) -> list[dict[str, Any]]:
-        """Return the last published diagnostics for a document URI."""
-        return self._diagnostics.get(uri, [])