mcpls_core/lsp/

lifecycle.rs

//! LSP server lifecycle management.
//!
//! This module handles the complete lifecycle of an LSP server:
//! 1. Spawn server process
//! 2. Initialize → initialized handshake
//! 3. Capability negotiation
//! 4. Active request handling
//! 5. Graceful shutdown sequence

use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::process::Stdio;

use lsp_types::{
    ClientCapabilities, ClientInfo, ExitNotification, GeneralClientCapabilities, InitializeParams,
    InitializeRequest, InitializeResult, InitializedNotification, InitializedParams,
    PositionEncodingKind, Request, ServerCapabilities, ShutdownRequest, StaleRequestSupportOptions,
    SymbolKind, WorkspaceFolder,
};
use tokio::process::Command;
use tokio::sync::mpsc;
use tokio::time::Duration;
use tracing::{debug, info, warn};

use crate::bridge::try_path_to_uri;
use crate::config::{LspServerConfig, ServerId};
use crate::error::{Error, Result, ServerSpawnFailure};
use crate::lsp::CONTENT_MODIFIED_RETRY_METHODS;
use crate::lsp::client::LspClient;
use crate::lsp::transport::LspTransport;
use crate::lsp::types::LspNotification;

/// Environment variables passed through to a spawned LSP server even though
/// its environment is otherwise cleared.
///
/// `PATH` lets the server resolve its own toolchain (e.g. rustup shims, venv
/// binaries); `HOME`/`USERPROFILE` and `TMPDIR`/`TEMP`/`TMP` let it find user
/// config/cache and scratch directories.
///
/// This list is not exhaustive: session-specific values that cannot be
/// hardcoded into a static [`LspServerConfig::env`] table (e.g.
/// `SSH_AUTH_SOCK`, which changes every login session) have no way through
/// today. See [`LspServerConfig::env`] for the config-level override/addition
/// mechanism this list feeds into.
const ENV_PASSTHROUGH: &[&str] = &["PATH", "HOME", "USERPROFILE", "TMPDIR", "TEMP", "TMP"];

/// Upper bound [`LspServer::shutdown`] waits for the child process to exit on
/// its own after sending the LSP `exit` notification, before falling back to
/// `kill_on_drop`.
const CHILD_EXIT_GRACE: Duration = Duration::from_secs(3);

/// Capacity of the diagnostics/log/showMessage notification channel (P3).
///
/// Raised from the pre-#422 value of 64: P1 makes mcpls advertise
/// `window.workDoneProgress`, so a server may now attach progress reporting
/// to ordinary request capabilities too, raising overall notification
/// volume generally even though progress itself moved to its own
/// [`LIFECYCLE_CHANNEL_CAPACITY`] lane.
const NOTIFICATION_CHANNEL_CAPACITY: usize = 256;

/// Capacity of the lifecycle channel (P3): `$/progress` `begin`/`end`
/// frames plus `Other` (rust-analyzer's `experimental/serverStatus`).
///
/// O(phases), not O(reports): a `$/progress` `report` frame is filtered out
/// before it ever reaches this channel (see
/// `lsp::client::LspClient::message_loop_inner`), so this only needs to hold
/// a handful of `begin`/`end` transitions even for a server with several
/// concurrent operations, not a `report`-per-package stream like gopls can
/// produce.
const LIFECYCLE_CHANNEL_CAPACITY: usize = 128;

/// Every symbol kind defined by LSP 3.17 and understood by mcpls.
///
/// Single source of truth for both the `initialize` request's
/// `value_set` and the `workspace/symbol` `kind_filter` validation in
/// [`crate::bridge::translator::symbols`] — the latter derives its accepted
/// string names from this array via `format!("{:?}", kind)`.
pub const SUPPORTED_SYMBOL_KINDS: [SymbolKind; 26] = [
    SymbolKind::File,
    SymbolKind::Module,
    SymbolKind::Namespace,
    SymbolKind::Package,
    SymbolKind::Class,
    SymbolKind::Method,
    SymbolKind::Property,
    SymbolKind::Field,
    SymbolKind::Constructor,
    SymbolKind::Enum,
    SymbolKind::Interface,
    SymbolKind::Function,
    SymbolKind::Variable,
    SymbolKind::Constant,
    SymbolKind::String,
    SymbolKind::Number,
    SymbolKind::Boolean,
    SymbolKind::Array,
    SymbolKind::Object,
    SymbolKind::Key,
    SymbolKind::Null,
    SymbolKind::EnumMember,
    SymbolKind::Struct,
    SymbolKind::Event,
    SymbolKind::Operator,
    SymbolKind::TypeParameter,
];

/// Windows-only additions to [`ENV_PASSTHROUGH`].
///
/// `SystemRoot`/`SystemDrive`/`windir` are required by the Windows process
/// loader itself; `APPDATA`/`LOCALAPPDATA` are read by the Node-based default
/// servers (pyright, typescript-language-server) for global config and
/// cache; the rest are conventionally expected by Windows child processes.
#[cfg(windows)]
const ENV_PASSTHROUGH_WINDOWS: &[&str] = &[
    "SystemRoot",
    "SystemDrive",
    "windir",
    "APPDATA",
    "LOCALAPPDATA",
    "ProgramData",
    "ProgramFiles",
    "COMSPEC",
    "PATHEXT",
    "NUMBER_OF_PROCESSORS",
    "USERNAME",
];

/// State of an LSP server connection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ServerState {
    /// Server has not been initialized.
    Uninitialized,
    /// Server is currently initializing.
    Initializing,
    /// Server is ready to handle requests.
    Ready,
    /// Server is shutting down.
    ShuttingDown,
    /// Server has been shut down.
    Shutdown,
}

impl ServerState {
    /// Check if the server is ready to handle requests.
    #[must_use]
    pub const fn is_ready(&self) -> bool {
        matches!(self, Self::Ready)
    }

    /// Check if the server can accept new requests.
    #[must_use]
    pub const fn can_accept_requests(&self) -> bool {
        matches!(self, Self::Ready)
    }
}

/// Configuration for LSP server initialization.
#[derive(Debug, Clone)]
pub struct ServerInitConfig {
    /// LSP server configuration.
    pub server_config: LspServerConfig,
    /// Workspace root paths.
    pub workspace_roots: Vec<PathBuf>,
    /// Initialization options (server-specific JSON).
    pub initialization_options: Option<serde_json::Value>,
    /// Position encoding preference order from
    /// [`crate::config::WorkspaceConfig::position_encodings`].
    ///
    /// Sent as `capabilities.general.positionEncodings` during [`LspServer::spawn`]'s
    /// `initialize` handshake, in the configured order. Values that don't parse
    /// as a valid [`PositionEncodingKind`] are skipped with a warning rather than
    /// failing the handshake: `serve`/`serve_with` validate the top-level
    /// `ServerConfig` via [`crate::config::ServerConfig::validate`] before this
    /// is ever built, but `LspServer::spawn`/`spawn_batch` are `pub` and
    /// reachable directly by a library embedder bypassing that validation
    /// entirely (same reasoning as the `initialize` timeout clamp below), so
    /// this can't assume the value was already checked. If nothing parses,
    /// falls back to `config::default_position_encodings()`'s default.
    pub position_encodings: Vec<String>,
    /// Optional channel for forwarding LSP notifications to the notification cache.
    ///
    /// When `Some`, the spawned LSP client sends every notification it receives
    /// (publishDiagnostics, logMessage, showMessage, …) through this sender.
    /// The caller is responsible for draining the corresponding receiver and
    /// storing entries in [`crate::bridge::NotificationCache`].
    pub notification_tx: Option<mpsc::Sender<LspNotification>>,
}

/// Result of attempting to spawn multiple LSP servers.
///
/// This type enables graceful degradation by collecting both
/// successful initializations and failures. Use the helper methods
/// to inspect the outcome and make decisions about how to proceed.
///
/// # Examples
///
/// ```
/// use mcpls_core::lsp::ServerInitResult;
/// use mcpls_core::error::ServerSpawnFailure;
///
/// let mut result = ServerInitResult::new();
///
/// // Check for different scenarios
/// if result.all_failed() {
///     eprintln!("All servers failed to initialize");
/// } else if result.partial_success() {
///     println!("Some servers succeeded, some failed");
/// } else if result.has_servers() {
///     println!("All servers initialized successfully");
/// }
/// ```
#[derive(Debug)]
pub struct ServerInitResult {
    /// Successfully initialized servers, keyed by routing identity.
    pub servers: HashMap<ServerId, LspServer>,
    /// Failures that occurred during spawn attempts.
    pub failures: Vec<ServerSpawnFailure>,
}

impl ServerInitResult {
    /// Create a new empty result.
    #[must_use]
    pub fn new() -> Self {
        Self {
            servers: HashMap::new(),
            failures: Vec::new(),
        }
    }

    /// Check if any servers were successfully initialized.
    ///
    /// Returns `true` if at least one server is available for use.
    #[must_use]
    pub fn has_servers(&self) -> bool {
        !self.servers.is_empty()
    }

    /// Check if all attempted servers failed.
    ///
    /// Returns `true` only if there were failures and no servers succeeded.
    /// Returns `false` for empty results (no servers configured).
    #[must_use]
    pub fn all_failed(&self) -> bool {
        self.servers.is_empty() && !self.failures.is_empty()
    }

    /// Check if some but not all servers failed.
    ///
    /// Returns `true` if there are both successful servers and failures.
    #[must_use]
    pub fn partial_success(&self) -> bool {
        !self.servers.is_empty() && !self.failures.is_empty()
    }

    /// Get the number of successfully initialized servers.
    #[must_use]
    pub fn server_count(&self) -> usize {
        self.servers.len()
    }

    /// Get the number of failures.
    #[must_use]
    pub const fn failure_count(&self) -> usize {
        self.failures.len()
    }

    /// Add a successful server.
    ///
    /// If a server with the same [`ServerId`] already exists, it will be replaced.
    pub fn add_server(&mut self, id: impl Into<ServerId>, server: LspServer) {
        self.servers.insert(id.into(), server);
    }

    /// Add a failure.
    pub fn add_failure(&mut self, failure: ServerSpawnFailure) {
        self.failures.push(failure);
    }
}

impl Default for ServerInitResult {
    fn default() -> Self {
        Self::new()
    }
}

/// Managed LSP server instance with capabilities and encoding.
pub struct LspServer {
    client: LspClient,
    capabilities: ServerCapabilities,
    position_encoding: PositionEncodingKind,
    /// Receiver for push notifications from the LSP server: diagnostics,
    /// log messages, and show-message requests.
    ///
    /// Extract this before registering the server to receive real-time
    /// notifications (e.g., `textDocument/publishDiagnostics`).
    pub notification_rx: mpsc::Receiver<LspNotification>,
    /// Receiver for the lifecycle lane (P3): `$/progress` `begin`/`end`
    /// frames and unrecognized notifications (which carry e.g.
    /// rust-analyzer's `experimental/serverStatus`), kept separate from
    /// [`Self::notification_rx`] so a high-volume diagnostics publisher can
    /// never starve out a workspace-readiness signal, or vice versa.
    ///
    /// Extract this before registering the server, the same way as
    /// [`Self::notification_rx`] -- see [`Self::take_lifecycle_rx`].
    pub lifecycle_rx: mpsc::Receiver<LspNotification>,
    /// Child process handle. Kept alive for process lifetime management and
    /// queried by [`Self::has_exited`] to detect a crash. [`LspServer::shutdown`]
    /// waits for it to exit after sending `exit`; otherwise, or if that wait
    /// times out, dropping it terminates the process via SIGKILL
    /// (`kill_on_drop`).
    ///
    /// `None` only for test fixtures that never spawn a real server process
    /// (see `crate::test_lsp`, `Self::new_for_test_with_encoding`) --
    /// [`Self::spawn`] always populates this with `Some`.
    child: Option<tokio::process::Child>,
}

impl std::fmt::Debug for LspServer {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("LspServer")
            .field("client", &self.client)
            .field("capabilities", &self.capabilities)
            .field("position_encoding", &self.position_encoding)
            .field("notification_rx", &"<channel>")
            .field("lifecycle_rx", &"<channel>")
            .field("child", &"<process>")
            .finish()
    }
}

impl LspServer {
    /// Take the notification receiver out of this server, replacing it with a dummy channel.
    ///
    /// Use this to extract the receiver for a background pump task before registering
    /// the server with the translator. After this call, the server's `notification_rx`
    /// will never receive messages.
    pub fn take_notification_rx(&mut self) -> tokio::sync::mpsc::Receiver<LspNotification> {
        let (_, dummy) = tokio::sync::mpsc::channel(1);
        std::mem::replace(&mut self.notification_rx, dummy)
    }

    /// Take the lifecycle receiver out of this server, replacing it with a
    /// dummy channel -- the lifecycle-lane counterpart to
    /// [`Self::take_notification_rx`]. Extract this before registering the
    /// server for a background pump task to drain, the same way as
    /// [`Self::notification_rx`].
    pub fn take_lifecycle_rx(&mut self) -> tokio::sync::mpsc::Receiver<LspNotification> {
        let (_, dummy) = tokio::sync::mpsc::channel(1);
        std::mem::replace(&mut self.lifecycle_rx, dummy)
    }

    /// Spawn and initialize LSP server.
    ///
    /// This performs the complete initialization sequence:
    /// 1. Spawns the LSP server as a child process
    /// 2. Sends initialize request with client capabilities
    /// 3. Receives server capabilities from initialize response
    /// 4. Sends initialized notification
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Server process fails to spawn
    /// - Initialize request fails or times out
    /// - Server returns error during initialization
    pub async fn spawn(config: ServerInitConfig) -> Result<Self> {
        info!(
            "Spawning LSP server: {} {:?}",
            config.server_config.command, config.server_config.args
        );

        let mut command = Self::build_command(&config.server_config, |key| std::env::var_os(key));

        // Log allowlist presence and an override count only — never the
        // configured keys themselves, since `config.server_config.env` may
        // hold secret-bearing names (e.g. `AWS_SECRET_ACCESS_KEY`) whose
        // mere presence in a debug log would be its own disclosure.
        let passthrough_present = {
            let base = ENV_PASSTHROUGH
                .iter()
                .filter(|key| std::env::var_os(key).is_some())
                .count();
            #[cfg(windows)]
            let windows = ENV_PASSTHROUGH_WINDOWS
                .iter()
                .filter(|key| std::env::var_os(key).is_some())
                .count();
            #[cfg(not(windows))]
            let windows = 0;
            base + windows
        };
        debug!(
            "Effective LSP server env: {passthrough_present} allowlisted key(s) present, \
             {} configured override(s) applied",
            config.server_config.env.len()
        );

        let mut child = command.spawn().map_err(|e| Error::ServerSpawnFailed {
            command: config.server_config.command.clone(),
            source: e,
        })?;

        let stdin = child
            .stdin
            .take()
            .ok_or_else(|| Error::Transport("Failed to capture stdin".to_string()))?;
        let stdout = child
            .stdout
            .take()
            .ok_or_else(|| Error::Transport("Failed to capture stdout".to_string()))?;

        let transport = LspTransport::new(stdin, stdout);
        let (notification_tx, notification_rx) = mpsc::channel(NOTIFICATION_CHANNEL_CAPACITY);
        let (lifecycle_tx, lifecycle_rx) = mpsc::channel(LIFECYCLE_CHANNEL_CAPACITY);
        let client = LspClient::from_transport_with_notifications(
            config.server_config.clone(),
            transport,
            notification_tx,
            lifecycle_tx,
        );

        let (capabilities, position_encoding) = Self::initialize(&client, &config).await?;

        info!("LSP server initialized successfully");

        Ok(Self {
            client,
            capabilities,
            position_encoding,
            notification_rx,
            lifecycle_rx,
            child: Some(child),
        })
    }

    /// Build the child `Command` for a spawned LSP server, without spawning it.
    ///
    /// The child's environment is cleared, then [`ENV_PASSTHROUGH`] (plus
    /// [`ENV_PASSTHROUGH_WINDOWS`] under `cfg(windows)`) is copied in from
    /// `parent_env` for whichever of those keys it returns `Some` for, then
    /// `config.env` is applied last so it can override any passthrough
    /// value. `parent_env` is injected (production passes
    /// `std::env::var_os`) so tests can supply a fixed environment without
    /// racing on real process-global state.
    fn build_command(
        config: &LspServerConfig,
        parent_env: impl Fn(&str) -> Option<std::ffi::OsString>,
    ) -> Command {
        let mut command = Command::new(&config.command);
        command.args(&config.args).env_clear();

        for key in ENV_PASSTHROUGH {
            if let Some(value) = parent_env(key) {
                command.env(key, value);
            }
        }
        #[cfg(windows)]
        for key in ENV_PASSTHROUGH_WINDOWS {
            if let Some(value) = parent_env(key) {
                command.env(key, value);
            }
        }

        command
            .envs(&config.env)
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .stderr(Stdio::null())
            .kill_on_drop(true);

        command
    }

    /// Build the `capabilities` mcpls advertises in the `initialize`
    /// request, given the configured position-encoding preference order.
    ///
    /// Extracted from [`Self::initialize`] (S2) so a unit test can assert
    /// directly on the returned value -- in particular that
    /// `window.work_done_progress == Some(true)` (P1), without which no
    /// spec-compliant LSP server may ever initiate `$/progress` at all (see
    /// the matching `window/workDoneProgress/create` allowlist entry in
    /// [`crate::lsp::client::LspClient::server_request_result`]). Before
    /// this existed, deleting those capability lines would silently no-op
    /// the whole feature with an otherwise-green test suite.
    #[allow(clippy::too_many_lines)]
    fn client_capabilities(position_encodings: &[String]) -> ClientCapabilities {
        ClientCapabilities {
            general: Some(GeneralClientCapabilities {
                position_encodings: Some(resolve_position_encodings(position_encodings)),
                stale_request_support: Some(StaleRequestSupportOptions {
                    // mcpls does not implement active in-flight request
                    // cancellation.
                    cancel: false,
                    retry_on_content_modified: CONTENT_MODIFIED_RETRY_METHODS
                        .iter()
                        .map(ToString::to_string)
                        .collect(),
                }),
                ..Default::default()
            }),
            text_document: Some(lsp_types::TextDocumentClientCapabilities {
                document_symbol: Some(lsp_types::DocumentSymbolClientCapabilities {
                    dynamic_registration: Some(false),
                    symbol_kind: Some(lsp_types::ClientSymbolKindOptions {
                        value_set: Some(SUPPORTED_SYMBOL_KINDS.to_vec()),
                    }),
                    hierarchical_document_symbol_support: Some(true),
                    ..Default::default()
                }),
                hover: Some(lsp_types::HoverClientCapabilities {
                    dynamic_registration: Some(false),
                    content_format: Some(vec![
                        lsp_types::MarkupKind::Markdown,
                        lsp_types::MarkupKind::PlainText,
                    ]),
                }),
                definition: Some(lsp_types::DefinitionClientCapabilities {
                    dynamic_registration: Some(false),
                    link_support: Some(true),
                }),
                references: Some(lsp_types::ReferenceClientCapabilities {
                    dynamic_registration: Some(false),
                }),
                code_action: Some(lsp_types::CodeActionClientCapabilities {
                    dynamic_registration: Some(false),
                    data_support: Some(true),
                    resolve_support: Some(lsp_types::ClientCodeActionResolveOptions {
                        properties: vec!["edit".to_string()],
                    }),
                    // Declare supported action kinds so the server returns
                    // CodeAction objects (not just legacy Command objects).
                    code_action_literal_support: Some(lsp_types::ClientCodeActionLiteralOptions {
                        code_action_kind: lsp_types::ClientCodeActionKindOptions {
                            value_set: vec![
                                lsp_types::CodeActionKind::Empty,
                                lsp_types::CodeActionKind::QuickFix,
                                lsp_types::CodeActionKind::Refactor,
                                lsp_types::CodeActionKind::RefactorExtract,
                                lsp_types::CodeActionKind::RefactorInline,
                                lsp_types::CodeActionKind::RefactorRewrite,
                                lsp_types::CodeActionKind::Source,
                                lsp_types::CodeActionKind::SourceOrganizeImports,
                            ],
                        },
                    }),
                    ..Default::default()
                }),
                ..Default::default()
            }),
            workspace: Some(lsp_types::WorkspaceClientCapabilities {
                workspace_folders: Some(true),
                ..Default::default()
            }),
            // Required per LSP 3.17 before a server may send $/progress at all -- see this fn's doc.
            window: Some(lsp_types::WindowClientCapabilities {
                work_done_progress: Some(true),
                ..Default::default()
            }),
            // Required for rust-analyzer to ever emit experimental/serverStatus; other servers ignore this unrecognized key.
            experimental: Some(serde_json::json!({ "serverStatusNotification": true })),
            ..Default::default()
        }
    }

    /// Perform LSP initialization handshake.
    ///
    /// Sends initialize request and waits for response, then sends initialized notification.
    async fn initialize(
        client: &LspClient,
        config: &ServerInitConfig,
    ) -> Result<(ServerCapabilities, PositionEncodingKind)> {
        debug!("Sending initialize request");

        let workspace_folders: Vec<WorkspaceFolder> = config
            .workspace_roots
            .iter()
            .map(|root| workspace_folder(root))
            .collect::<Result<Vec<_>>>()?;

        let params = InitializeParams {
            process_id: Some(i32::try_from(std::process::id()).unwrap_or(i32::MAX)),
            #[allow(deprecated)]
            root_uri: None,
            initialization_options: config.initialization_options.clone(),
            capabilities: Self::client_capabilities(&config.position_encodings),
            client_info: Some(ClientInfo {
                name: "mcpls".to_string(),
                version: Some(env!("CARGO_PKG_VERSION").to_string()),
            }),
            workspace_folders_initialize_params: lsp_types::WorkspaceFoldersInitializeParams {
                workspace_folders: Some(lsp_types::WorkspaceFolders::WorkspaceFolderList(
                    workspace_folders,
                )),
            },
            ..Default::default()
        };

        // Use the server's configured timeout for the initialize handshake too,
        // not a hardcoded 30s: large solutions (e.g. a 130-project Unity .sln via
        // OmniSharp) take minutes to respond to `initialize`.
        let result: InitializeResult = client
            .request_typed::<InitializeRequest>(
                params,
                // Clamped for the same reason as `LspClient::request_timeout`:
                // `serve()`/`serve_with()` now validate the top-level
                // `ServerConfig` via `ServerConfig::validate()`, but this call
                // operates on the per-server `config.server_config` reached
                // through `LspServer::spawn`/`spawn_batch`, which bypass that
                // top-level validation entirely, so an out-of-range value (0,
                // or an unbounded one that would silently disable the timeout
                // via tokio's `Instant::far_future()` fallback) is still
                // reachable here and needs a last-line-of-defense clamp.
                Duration::from_secs(
                    config
                        .server_config
                        .timeout_seconds
                        .clamp(1, crate::config::MAX_TIMEOUT_SECONDS),
                ),
            )
            .await
            .map_err(|e| Error::LspInitFailed {
                message: format!("Initialize request failed: {e}"),
            })?;

        let position_encoding = result
            .capabilities
            .position_encoding
            .clone()
            .unwrap_or(PositionEncodingKind::UTF16);

        debug!(
            "Server capabilities received, encoding: {:?}",
            position_encoding
        );

        client
            .notify_typed::<InitializedNotification>(InitializedParams {})
            .await
            .map_err(|e| Error::LspInitFailed {
                message: format!("Initialized notification failed: {e}"),
            })?;

        Ok((result.capabilities, position_encoding))
    }

    /// Get server capabilities.
    #[must_use]
    pub const fn capabilities(&self) -> &ServerCapabilities {
        &self.capabilities
    }

    /// Get negotiated position encoding.
    #[must_use]
    pub fn position_encoding(&self) -> PositionEncodingKind {
        self.position_encoding.clone()
    }

    /// Get client for making requests.
    #[must_use]
    pub const fn client(&self) -> &LspClient {
        &self.client
    }

    /// Non-blocking check for whether the child process has already exited.
    ///
    /// Uses [`tokio::process::Child::try_wait`], which never blocks waiting
    /// for the process: `true` means it is gone (crashed, killed, or exited
    /// on its own), and any [`LspClient`] obtained from [`Self::client`] is
    /// now permanently disconnected -- new requests through it fail with
    /// [`crate::error::Error::ServerTerminated`]. Callers that want to
    /// recover substitute a freshly [`Self::spawn`]ed replacement.
    ///
    /// Always returns `Ok(false)` for a test fixture with no real backing
    /// process (`self.child` is `None`) -- there is nothing to have exited.
    /// [`Self::spawn`] always populates `child`, so production code never
    /// observes this case.
    ///
    /// # Errors
    ///
    /// Returns an error if the OS fails to report the process's status.
    pub fn has_exited(&mut self) -> Result<bool> {
        match &mut self.child {
            Some(child) => Ok(child.try_wait()?.is_some()),
            None => Ok(false),
        }
    }

    /// Shutdown server gracefully.
    ///
    /// Sends the LSP `shutdown` request, waits for the response, sends the
    /// `exit` notification, then waits up to a fixed grace period for the
    /// child process to exit on its own. If it hasn't by then, or if the
    /// `shutdown`/`exit` handshake itself fails, the child is simply dropped
    /// here — `kill_on_drop` terminates it via SIGKILL (a no-op if it has
    /// already exited). A test fixture with no real backing process (`child`
    /// is `None`) skips this step entirely -- there is nothing to wait for or
    /// kill.
    ///
    /// # Errors
    ///
    /// Returns an error if the `shutdown`/`exit` handshake fails. The child
    /// process is still torn down (gracefully if it exits in time, killed
    /// otherwise) regardless of whether this returns `Ok` or `Err`.
    pub async fn shutdown(self) -> Result<()> {
        debug!("Shutting down LSP server");

        let handshake: Result<()> = async move {
            let _: serde_json::Value = self
                .client
                .request(ShutdownRequest::METHOD.as_str(), (), Duration::from_secs(5))
                .await?;
            self.client.notify_typed::<ExitNotification>(()).await?;
            self.client.shutdown().await
        }
        .await;

        if let Some(mut child) = self.child {
            match tokio::time::timeout(CHILD_EXIT_GRACE, child.wait()).await {
                Ok(Ok(status)) => {
                    debug!(
                        ?status,
                        "LSP server process exited after `exit` notification"
                    );
                }
                Ok(Err(e)) => warn!(error = %e, "failed to wait for LSP server process exit"),
                Err(_) => warn!(
                    timeout = ?CHILD_EXIT_GRACE,
                    "LSP server process did not exit within grace period after `exit` \
                     notification, killing it"
                ),
            }
            // `child` drops here: `kill_on_drop` kills it if still running, and is a
            // no-op if `wait()` above already reaped it.
        }

        handshake?;
        info!("LSP server shut down successfully");
        Ok(())
    }

    /// Spawn multiple LSP servers in batch mode with graceful degradation.
    ///
    /// Attempts to spawn and initialize all configured servers. If some servers
    /// fail to spawn, the successful servers are still returned. This enables
    /// graceful degradation where the system can continue to operate with
    /// partial functionality.
    ///
    /// # Behavior
    ///
    /// - Attempts to spawn each server sequentially
    /// - Logs success (info) and failure (error) for each server
    /// - Accumulates successful servers and failures
    /// - Never panics or returns early - attempts all servers
    ///
    /// # Examples
    ///
    /// ```
    /// use mcpls_core::lsp::{LspServer, ServerInitConfig};
    /// use mcpls_core::config::LspServerConfig;
    /// use std::path::PathBuf;
    ///
    /// # async fn example() {
    /// let configs = vec![
    ///     ServerInitConfig {
    ///         server_config: LspServerConfig::rust_analyzer(),
    ///         workspace_roots: vec![PathBuf::from("/workspace")],
    ///         initialization_options: None,
    ///         position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
    ///         notification_tx: None,
    ///     },
    ///     ServerInitConfig {
    ///         server_config: LspServerConfig::pyright(),
    ///         workspace_roots: vec![PathBuf::from("/workspace")],
    ///         initialization_options: None,
    ///         position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
    ///         notification_tx: None,
    ///     },
    /// ];
    ///
    /// let result = LspServer::spawn_batch(&configs).await;
    ///
    /// if result.has_servers() {
    ///     println!("Successfully spawned {} servers", result.server_count());
    /// }
    ///
    /// if result.partial_success() {
    ///     eprintln!("Warning: {} servers failed", result.failure_count());
    /// }
    /// # }
    /// ```
    pub async fn spawn_batch(configs: &[ServerInitConfig]) -> ServerInitResult {
        let mut result = ServerInitResult::new();

        for config in configs {
            let server_id = config.server_config.id();
            let language_id = config.server_config.language_id.clone();
            let command = config.server_config.command.clone();

            match Self::spawn(config.clone()).await {
                Ok(server) => {
                    info!(
                        "Successfully spawned LSP server: {} ({})",
                        server_id, command
                    );
                    result.add_server(server_id, server);
                }
                Err(e) => {
                    tracing::error!(
                        "Failed to spawn LSP server: {} ({}): {}",
                        server_id,
                        command,
                        e
                    );
                    result.add_failure(ServerSpawnFailure {
                        server_id,
                        language_id,
                        command,
                        message: e.to_string(),
                    });
                }
            }
        }

        result
    }
}

/// Convert configured position-encoding strings into the ordered
/// [`PositionEncodingKind`] list offered during the `initialize` handshake.
///
/// Values that don't parse are skipped with a warning instead of failing the
/// handshake (see [`ServerInitConfig::position_encodings`] for why this can't
/// assume [`crate::config::ServerConfig::validate`] already ran). Falls back
/// to `config::default_position_encodings()` -- the same default used when
/// nothing is configured at all -- if no configured value parses.
fn resolve_position_encodings(configured: &[String]) -> Vec<PositionEncodingKind> {
    let encodings: Vec<PositionEncodingKind> = configured
        .iter()
        .filter_map(|value| {
            let kind = crate::config::parse_position_encoding(value);
            if kind.is_none() {
                warn!(value = %value, "ignoring invalid configured position encoding");
            }
            kind
        })
        .collect();

    if encodings.is_empty() {
        crate::config::default_position_encodings()
            .iter()
            .filter_map(|value| crate::config::parse_position_encoding(value))
            .collect()
    } else {
        encodings
    }
}

/// Build the `workspace/workspaceFolders` entry for one configured root.
///
/// Reserved characters have to be percent-encoded here: an unencoded `#`
/// would truncate the path into a URI fragment, and `[` / `]` are rejected
/// outright by `Uri`.
fn workspace_folder(root: &Path) -> Result<WorkspaceFolder> {
    let uri = try_path_to_uri(root).ok_or_else(|| {
        let root_display = root.display();
        Error::InvalidUri(format!("Invalid workspace root: {root_display}"))
    })?;
    Ok(WorkspaceFolder {
        uri,
        name: root
            .file_name()
            .and_then(|n| n.to_str())
            .unwrap_or("workspace")
            .to_string(),
    })
}

/// Builds an `LspServer` that can be registered without a real language
/// server: an inert, in-memory transport (see `crate::test_lsp`) and no
/// backing child process (`child: None`) -- neither is ever read from or
/// written to.
///
/// `pub` rather than private to this module's own `tests` (`lifecycle` is a
/// private module, so this stays crate-scoped in practice, per the
/// `redundant_pub_crate` clippy lint): it constructs `LspServer` via a
/// struct literal, which only code inside this module can do (all its
/// fields are private), so this is the one place other modules'
/// shutdown-path tests (`bridge::translator`, `lib.rs`) can get a real,
/// registerable `LspServer` from.
#[cfg(test)]
pub fn fake_lsp_server() -> LspServer {
    let transport = crate::test_lsp::inert_transport();
    let client = LspClient::from_transport(LspServerConfig::pyright(), transport);
    let (_, mock_notification_rx) = mpsc::channel(1);
    let (_, mock_lifecycle_rx) = mpsc::channel(1);
    LspServer {
        client,
        capabilities: lsp_types::ServerCapabilities::default(),
        position_encoding: PositionEncodingKind::UTF8,
        notification_rx: mock_notification_rx,
        lifecycle_rx: mock_lifecycle_rx,
        child: None,
    }
}

#[cfg(test)]
impl LspServer {
    /// Construct an `LspServer` fixture carrying the given capabilities, for
    /// tests elsewhere in the crate that need to drive capability-gated
    /// dispatch paths in `Translator` without spawning a real language server.
    ///
    /// The underlying client and child process (`child: None`) are inert
    /// placeholders — only `capabilities()` is meaningful on the returned
    /// value.
    ///
    /// Uses `LspClient::new` (uninitialized, no background task) rather than
    /// `LspClient::from_transport`, so this does not depend on the Tokio
    /// message loop or a real process at all.
    pub(crate) fn new_for_test(capabilities: ServerCapabilities) -> Self {
        Self::new_for_test_with_encoding(capabilities, PositionEncodingKind::UTF16)
    }

    /// As [`Self::new_for_test`], but with a caller-chosen negotiated
    /// encoding -- for tests exercising a non-UTF-16 conversion path (e.g.
    /// `EncodingCtx`-driven range conversion) without spawning a real
    /// process.
    pub(crate) fn new_for_test_with_encoding(
        capabilities: ServerCapabilities,
        position_encoding: PositionEncodingKind,
    ) -> Self {
        let client = LspClient::new(LspServerConfig::rust_analyzer());
        let (_, notification_rx) = mpsc::channel(1);
        let (_, lifecycle_rx) = mpsc::channel(1);

        Self {
            client,
            capabilities,
            position_encoding,
            notification_rx,
            lifecycle_rx,
            child: None,
        }
    }
}

#[cfg(test)]
#[allow(clippy::unwrap_used)]
mod tests {
    use super::*;

    #[test]
    fn test_resolve_position_encodings_preserves_configured_order() {
        let result = resolve_position_encodings(&["utf-32".to_string(), "utf-8".to_string()]);
        assert_eq!(
            result,
            vec![PositionEncodingKind::UTF32, PositionEncodingKind::UTF8]
        );
    }

    #[test]
    fn test_resolve_position_encodings_skips_invalid_and_keeps_valid() {
        let result = resolve_position_encodings(&["utf-7".to_string(), "utf-16".to_string()]);
        assert_eq!(result, vec![PositionEncodingKind::UTF16]);
    }

    #[test]
    fn test_resolve_position_encodings_falls_back_when_all_invalid() {
        let result = resolve_position_encodings(&["utf-7".to_string(), "bogus".to_string()]);
        assert_eq!(
            result,
            vec![PositionEncodingKind::UTF8, PositionEncodingKind::UTF16]
        );
    }

    #[test]
    fn test_resolve_position_encodings_falls_back_when_empty() {
        let result = resolve_position_encodings(&[]);
        assert_eq!(
            result,
            vec![PositionEncodingKind::UTF8, PositionEncodingKind::UTF16]
        );
    }

    /// P1/S2: without `window.work_done_progress == Some(true)`, no
    /// spec-compliant LSP server may ever initiate `$/progress` at all.
    /// Regression guard: deleting the capability lines in
    /// `client_capabilities` must fail this test, not silently no-op the
    /// whole feature with an otherwise-green suite.
    #[test]
    fn test_client_capabilities_advertises_work_done_progress() {
        let capabilities =
            LspServer::client_capabilities(&["utf-8".to_string(), "utf-16".to_string()]);

        assert_eq!(
            capabilities.window.and_then(|w| w.work_done_progress),
            Some(true)
        );
    }

    #[test]
    fn test_server_state_ready() {
        assert!(ServerState::Ready.is_ready());
        assert!(ServerState::Ready.can_accept_requests());
    }

    #[test]
    fn test_server_state_uninitialized() {
        assert!(!ServerState::Uninitialized.is_ready());
        assert!(!ServerState::Uninitialized.can_accept_requests());
    }

    #[test]
    fn test_server_state_initializing() {
        assert!(!ServerState::Initializing.is_ready());
        assert!(!ServerState::Initializing.can_accept_requests());
    }

    #[test]
    fn test_workspace_folder_encodes_fragment_char() {
        // An unencoded `#` parses as a fragment, silently handing the server
        // the parent directory as its root.
        #[cfg(windows)]
        let (root, expected) = (
            Path::new(r"C:\home\me\dev\#work"),
            "file:///C:/home/me/dev/%23work",
        );
        #[cfg(not(windows))]
        let (root, expected) = (
            Path::new("/home/me/dev/#work"),
            "file:///home/me/dev/%23work",
        );

        let folder = workspace_folder(root).unwrap();

        assert_eq!(folder.uri.as_ref(), expected);
        assert_eq!(folder.name, "#work");
    }

    #[test]
    fn test_workspace_folder_encodes_bracket_chars() {
        #[cfg(windows)]
        let (root, expected) = (
            Path::new(r"C:\home\me\dev\[env]"),
            "file:///C:/home/me/dev/%5Benv%5D",
        );
        #[cfg(not(windows))]
        let (root, expected) = (
            Path::new("/home/me/dev/[env]"),
            "file:///home/me/dev/%5Benv%5D",
        );

        let folder = workspace_folder(root).unwrap();

        assert_eq!(folder.uri.as_ref(), expected);
        assert_eq!(folder.name, "[env]");
    }

    #[test]
    fn test_workspace_folder_rejects_relative_root() {
        let err = workspace_folder(Path::new("relative/root")).unwrap_err();
        assert!(matches!(err, Error::InvalidUri(_)), "got {err:?}");
    }

    #[test]
    fn test_server_state_shutting_down() {
        assert!(!ServerState::ShuttingDown.is_ready());
        assert!(!ServerState::ShuttingDown.can_accept_requests());
    }

    #[test]
    fn test_server_state_shutdown() {
        assert!(!ServerState::Shutdown.is_ready());
        assert!(!ServerState::Shutdown.can_accept_requests());
    }

    #[test]
    fn test_server_state_equality() {
        assert_eq!(ServerState::Ready, ServerState::Ready);
        assert_ne!(ServerState::Ready, ServerState::Uninitialized);
        assert_eq!(ServerState::Shutdown, ServerState::Shutdown);
    }

    #[test]
    fn test_server_state_clone() {
        let state = ServerState::Ready;
        let cloned = state;
        assert_eq!(state, cloned);
    }

    #[test]
    fn test_server_state_debug() {
        let state = ServerState::Ready;
        let debug_str = format!("{state:?}");
        assert!(debug_str.contains("Ready"));
    }

    #[test]
    fn test_server_init_config_clone() {
        let config = ServerInitConfig {
            server_config: LspServerConfig::rust_analyzer(),
            workspace_roots: vec![PathBuf::from("/tmp/workspace")],
            initialization_options: Some(serde_json::json!({"key": "value"})),
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        };

        #[allow(clippy::redundant_clone)]
        let cloned = config.clone();
        assert_eq!(cloned.server_config.language_id, "rust");
        assert_eq!(cloned.workspace_roots.len(), 1);
    }

    #[test]
    fn test_server_init_config_debug() {
        let config = ServerInitConfig {
            server_config: LspServerConfig::pyright(),
            workspace_roots: vec![],
            initialization_options: None,
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        };

        let debug_str = format!("{config:?}");
        assert!(debug_str.contains("python"));
        assert!(debug_str.contains("pyright"));
    }

    #[test]
    fn test_server_init_config_with_options() {
        use std::collections::HashMap;

        let init_opts = serde_json::json!({
            "settings": {
                "python": {
                    "analysis": {
                        "typeCheckingMode": "strict"
                    }
                }
            }
        });

        let mut env = HashMap::new();
        env.insert("PYTHONPATH".to_string(), "/usr/lib".to_string());

        let config = ServerInitConfig {
            server_config: LspServerConfig {
                language_id: "python".to_string(),
                command: "pyright-langserver".to_string(),
                args: vec!["--stdio".to_string()],
                env,
                file_patterns: vec!["**/*.py".to_string()],
                initialization_options: Some(init_opts.clone()),
                timeout_seconds: 10,
                request_timeout_seconds: 10,
                heuristics: None,
                name: None,
                handles: None,
                indexing: crate::bridge::IndexingPolicy::Auto,
            },
            workspace_roots: vec![PathBuf::from("/workspace")],
            initialization_options: Some(init_opts),
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        };

        assert!(config.initialization_options.is_some());
        assert_eq!(config.workspace_roots.len(), 1);
    }

    #[test]
    fn test_server_init_config_empty_workspace() {
        let config = ServerInitConfig {
            server_config: LspServerConfig::typescript(),
            workspace_roots: vec![],
            initialization_options: None,
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        };

        assert!(config.workspace_roots.is_empty());
    }

    #[test]
    fn test_server_init_config_multiple_workspaces() {
        let config = ServerInitConfig {
            server_config: LspServerConfig::rust_analyzer(),
            workspace_roots: vec![
                PathBuf::from("/workspace1"),
                PathBuf::from("/workspace2"),
                PathBuf::from("/workspace3"),
            ],
            initialization_options: None,
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        };

        assert_eq!(config.workspace_roots.len(), 3);
    }

    /// #249: `has_exited` must distinguish a live child from one that has
    /// already exited, since this is the signal the respawn path relies on
    /// to detect a crashed LSP server.
    ///
    /// Unix-only: spawns a real `sleep` subprocess, which is unavailable on
    /// the Windows CI runner.
    #[cfg(unix)]
    #[tokio::test]
    async fn test_has_exited_reflects_child_process_state() {
        use lsp_types::ServerCapabilities;

        let mut mock_child = tokio::process::Command::new("sleep")
            .arg("2")
            .stdin(Stdio::piped())
            .stdout(Stdio::piped())
            .kill_on_drop(true)
            .spawn()
            .unwrap();

        let mock_stdin = mock_child.stdin.take().unwrap();
        let mock_stdout = mock_child.stdout.take().unwrap();

        let transport = LspTransport::new(mock_stdin, mock_stdout);
        let client = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport);
        let (_, mock_notification_rx) = mpsc::channel(1);
        let (_, mock_lifecycle_rx) = mpsc::channel(1);

        let mut server = LspServer {
            client,
            capabilities: ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF8,
            notification_rx: mock_notification_rx,
            lifecycle_rx: mock_lifecycle_rx,
            child: Some(mock_child),
        };

        assert!(
            !server.has_exited().unwrap(),
            "freshly spawned `sleep 2` should still be running"
        );

        server.child.as_mut().unwrap().kill().await.unwrap();
        // `kill().await` waits for the process to actually exit, so the
        // very next `try_wait` reliably observes it as gone.
        assert!(
            server.has_exited().unwrap(),
            "killed child must report as exited"
        );
    }

    #[tokio::test]
    async fn test_lsp_server_getters() {
        use lsp_types::ServerCapabilities;

        let transport = crate::test_lsp::inert_transport();
        let client = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport);
        let (_, mock_notification_rx) = mpsc::channel(1);
        let (_, mock_lifecycle_rx) = mpsc::channel(1);

        let server = LspServer {
            client,
            capabilities: ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF8,
            notification_rx: mock_notification_rx,
            lifecycle_rx: mock_lifecycle_rx,
            child: None,
        };

        assert_eq!(server.position_encoding(), PositionEncodingKind::UTF8);
        assert!(server.capabilities().text_document_sync.is_none());

        let debug_str = format!("{server:?}");
        assert!(debug_str.contains("LspServer"));
        assert!(debug_str.contains("<process>"));
    }

    #[test]
    fn test_server_init_result_new_empty() {
        let result = ServerInitResult::new();
        assert!(!result.has_servers());
        assert!(!result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 0);
    }

    #[test]
    fn test_server_init_result_default() {
        let result = ServerInitResult::default();
        assert!(!result.has_servers());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 0);
    }

    #[test]
    fn test_server_init_result_all_failures() {
        let mut result = ServerInitResult::new();

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("rust"),
            language_id: "rust".to_string(),
            command: "rust-analyzer".to_string(),
            message: "not found".to_string(),
        });

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("python"),
            language_id: "python".to_string(),
            command: "pyright".to_string(),
            message: "permission denied".to_string(),
        });

        assert!(!result.has_servers());
        assert!(result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 2);
    }

    #[tokio::test]
    async fn test_server_init_result_all_success() {
        let mut result = ServerInitResult::new();

        let transport1 = crate::test_lsp::inert_transport();
        let client1 = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport1);
        let (_, mock_notification_rx1) = mpsc::channel(1);
        let (_, mock_lifecycle_rx1) = mpsc::channel(1);

        let server1 = LspServer {
            client: client1,
            capabilities: lsp_types::ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF8,
            notification_rx: mock_notification_rx1,
            lifecycle_rx: mock_lifecycle_rx1,
            child: None,
        };

        result.add_server("rust".to_string(), server1);

        assert!(result.has_servers());
        assert!(!result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 1);
        assert_eq!(result.failure_count(), 0);
    }

    #[tokio::test]
    async fn test_server_init_result_partial_success() {
        let mut result = ServerInitResult::new();

        let transport = crate::test_lsp::inert_transport();
        let client = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport);
        let (_, mock_notification_rx) = mpsc::channel(1);
        let (_, mock_lifecycle_rx) = mpsc::channel(1);

        let server = LspServer {
            client,
            capabilities: lsp_types::ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF8,
            notification_rx: mock_notification_rx,
            lifecycle_rx: mock_lifecycle_rx,
            child: None,
        };

        result.add_server("rust".to_string(), server);

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("python"),
            language_id: "python".to_string(),
            command: "pyright".to_string(),
            message: "not found".to_string(),
        });

        assert!(result.has_servers());
        assert!(!result.all_failed());
        assert!(result.partial_success());
        assert_eq!(result.server_count(), 1);
        assert_eq!(result.failure_count(), 1);
    }

    #[tokio::test]
    async fn test_server_init_result_multiple_servers() {
        let mut result = ServerInitResult::new();

        for i in 0..3 {
            let transport = crate::test_lsp::inert_transport();
            let config = if i == 0 {
                LspServerConfig::rust_analyzer()
            } else if i == 1 {
                LspServerConfig::pyright()
            } else {
                LspServerConfig::typescript()
            };
            let client = LspClient::from_transport(config.clone(), transport);
            let (_, mock_notification_rx) = mpsc::channel(1);
            let (_, mock_lifecycle_rx) = mpsc::channel(1);

            let server = LspServer {
                client,
                capabilities: lsp_types::ServerCapabilities::default(),
                position_encoding: PositionEncodingKind::UTF8,
                notification_rx: mock_notification_rx,
                lifecycle_rx: mock_lifecycle_rx,
                child: None,
            };

            result.add_server(config.language_id, server);
        }

        assert!(result.has_servers());
        assert!(!result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 3);
        assert_eq!(result.failure_count(), 0);
    }

    #[tokio::test]
    async fn test_server_init_result_replace_server() {
        let mut result = ServerInitResult::new();

        let transport1 = crate::test_lsp::inert_transport();
        let client1 = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport1);
        let (_, mock_notification_rx1) = mpsc::channel(1);
        let (_, mock_lifecycle_rx1) = mpsc::channel(1);

        let server1 = LspServer {
            client: client1,
            capabilities: lsp_types::ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF8,
            notification_rx: mock_notification_rx1,
            lifecycle_rx: mock_lifecycle_rx1,
            child: None,
        };

        result.add_server("rust".to_string(), server1);
        assert_eq!(result.server_count(), 1);

        let transport2 = crate::test_lsp::inert_transport();
        let client2 = LspClient::from_transport(LspServerConfig::rust_analyzer(), transport2);
        let (_, mock_notification_rx2) = mpsc::channel(1);
        let (_, mock_lifecycle_rx2) = mpsc::channel(1);

        let server2 = LspServer {
            client: client2,
            capabilities: lsp_types::ServerCapabilities::default(),
            position_encoding: PositionEncodingKind::UTF16,
            notification_rx: mock_notification_rx2,
            lifecycle_rx: mock_lifecycle_rx2,
            child: None,
        };

        result.add_server("rust".to_string(), server2);
        assert_eq!(result.server_count(), 1);
    }

    #[test]
    fn test_server_init_result_debug() {
        let mut result = ServerInitResult::new();

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("rust"),
            language_id: "rust".to_string(),
            command: "rust-analyzer".to_string(),
            message: "not found".to_string(),
        });

        let debug_str = format!("{result:?}");
        assert!(debug_str.contains("ServerInitResult"));
    }

    #[test]
    fn test_server_init_result_multiple_failures() {
        let mut result = ServerInitResult::new();

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("python"),
            language_id: "python".to_string(),
            command: "pyright".to_string(),
            message: "not found".to_string(),
        });

        result.add_failure(ServerSpawnFailure {
            server_id: ServerId::from("typescript"),
            language_id: "typescript".to_string(),
            command: "tsserver".to_string(),
            message: "command not found".to_string(),
        });

        assert_eq!(result.failure_count(), 2);
        assert_eq!(result.server_count(), 0);
        assert!(result.all_failed());
        assert!(!result.partial_success());
    }

    #[tokio::test]
    async fn test_spawn_batch_empty_configs() {
        let configs: &[ServerInitConfig] = &[];
        let result = LspServer::spawn_batch(configs).await;

        assert!(!result.has_servers());
        assert!(!result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 0);
    }

    #[tokio::test]
    async fn test_spawn_batch_single_invalid_config() {
        let configs = vec![ServerInitConfig {
            server_config: LspServerConfig {
                language_id: "rust".to_string(),
                command: "nonexistent-command-12345".to_string(),
                args: vec![],
                env: std::collections::HashMap::new(),
                file_patterns: vec!["**/*.rs".to_string()],
                initialization_options: None,
                timeout_seconds: 10,
                request_timeout_seconds: 10,
                heuristics: None,
                name: None,
                handles: None,
                indexing: crate::bridge::IndexingPolicy::Auto,
            },
            workspace_roots: vec![],
            initialization_options: None,
            position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
            notification_tx: None,
        }];

        let result = LspServer::spawn_batch(&configs).await;

        assert!(!result.has_servers());
        assert!(result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 1);

        let failure = &result.failures[0];
        assert_eq!(failure.language_id, "rust");
        assert_eq!(failure.command, "nonexistent-command-12345");
        assert!(failure.message.contains("spawn"));
    }

    #[tokio::test]
    async fn test_spawn_batch_all_invalid_configs() {
        let configs = vec![
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "rust".to_string(),
                    command: "nonexistent-rust-analyzer".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec!["**/*.rs".to_string()],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "python".to_string(),
                    command: "nonexistent-pyright".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec!["**/*.py".to_string()],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "typescript".to_string(),
                    command: "nonexistent-tsserver".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec!["**/*.ts".to_string()],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
        ];

        let result = LspServer::spawn_batch(&configs).await;

        assert!(!result.has_servers());
        assert!(result.all_failed());
        assert!(!result.partial_success());
        assert_eq!(result.server_count(), 0);
        assert_eq!(result.failure_count(), 3);

        let failure_languages: Vec<_> = result
            .failures
            .iter()
            .map(|f| f.language_id.as_str())
            .collect();
        assert!(failure_languages.contains(&"rust"));
        assert!(failure_languages.contains(&"python"));
        assert!(failure_languages.contains(&"typescript"));
    }

    #[tokio::test]
    async fn test_spawn_batch_multiple_invalid_configs_ordering() {
        let configs = vec![
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "lang1".to_string(),
                    command: "cmd1-nonexistent".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec![],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "lang2".to_string(),
                    command: "cmd2-nonexistent".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec![],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
        ];

        let result = LspServer::spawn_batch(&configs).await;

        assert_eq!(result.failure_count(), 2);

        assert_eq!(result.failures[0].language_id, "lang1");
        assert_eq!(result.failures[0].command, "cmd1-nonexistent");

        assert_eq!(result.failures[1].language_id, "lang2");
        assert_eq!(result.failures[1].command, "cmd2-nonexistent");
    }

    /// Wire-level regressions for the `initialize` request. The tests
    /// capture the real bytes `LspServer::initialize` writes over an
    /// in-memory duplex pipe standing in for the LSP server. Mirrors the
    /// `fake_lsp_client`/`FakeServer` pattern in
    /// `client.rs::tests::retry_behavior`.
    mod initialize_wire {
        use tempfile::TempDir;
        use tokio::io::BufReader;

        use super::*;
        use crate::test_lsp::{
            fake_lsp_client, read_framed_message, write_response as write_success_response,
        };

        #[tokio::test]
        async fn test_initialize_sends_configured_position_encodings() {
            let (client, mut server) = fake_lsp_client();

            let config = ServerInitConfig {
                server_config: LspServerConfig::rust_analyzer(),
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-32".to_string(), "utf-8".to_string()],
                notification_tx: None,
            };

            let init_task =
                tokio::spawn(async move { LspServer::initialize(&client, &config).await });

            let mut reader = BufReader::new(&mut server.write_stdout);
            let request = read_framed_message(&mut reader).await;

            assert_eq!(request["method"], "initialize");
            assert_eq!(
                request["params"]["capabilities"]["general"]["positionEncodings"],
                serde_json::json!(["utf-32", "utf-8"]),
                "initialize request must carry the configured encoding order, not the \
                 hardcoded [UTF8, UTF16] default"
            );

            write_success_response(
                &mut server.read_half_stdin,
                &request["id"].clone(),
                serde_json::json!({ "capabilities": {} }),
            )
            .await;

            // The response written above must let `initialize` complete successfully.
            init_task.await.unwrap().unwrap();
        }

        #[tokio::test]
        async fn test_initialize_advertises_stale_request_support() {
            let (client, mut server) = fake_lsp_client();

            let config = ServerInitConfig {
                server_config: LspServerConfig::rust_analyzer(),
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            };

            let init_task =
                tokio::spawn(async move { LspServer::initialize(&client, &config).await });

            let mut reader = BufReader::new(&mut server.write_stdout);
            let request = read_framed_message(&mut reader).await;
            let params: InitializeParams =
                serde_json::from_value(request["params"].clone()).unwrap();
            let stale_request_support = params
                .capabilities
                .general
                .unwrap()
                .stale_request_support
                .unwrap();

            assert_eq!(request["method"], "initialize");
            assert!(
                !stale_request_support.cancel,
                "mcpls does not implement active in-flight request cancellation"
            );
            assert_eq!(
                stale_request_support.retry_on_content_modified,
                CONTENT_MODIFIED_RETRY_METHODS
                    .iter()
                    .map(ToString::to_string)
                    .collect::<Vec<_>>(),
                "the wire-advertised capability must match the methods LspClient::request \
                 actually retries -32801 for, not drift from it"
            );

            write_success_response(
                &mut server.read_half_stdin,
                &request["id"].clone(),
                serde_json::json!({ "capabilities": {} }),
            )
            .await;

            init_task.await.unwrap().unwrap();
        }

        #[tokio::test]
        async fn test_initialize_advertises_server_status_notification_support() {
            let (client, mut server) = fake_lsp_client();

            let config = ServerInitConfig {
                server_config: LspServerConfig::rust_analyzer(),
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            };

            let init_task =
                tokio::spawn(async move { LspServer::initialize(&client, &config).await });

            let mut reader = BufReader::new(&mut server.write_stdout);
            let request = read_framed_message(&mut reader).await;

            assert_eq!(request["method"], "initialize");
            assert_eq!(
                request["params"]["capabilities"]["experimental"]["serverStatusNotification"],
                serde_json::json!(true),
                "without this, rust-analyzer never emits experimental/serverStatus and the \
                 indexing-readiness gate in Translator::wait_for_indexing_ready is a \
                 permanent no-op"
            );

            write_success_response(
                &mut server.read_half_stdin,
                &request["id"].clone(),
                serde_json::json!({ "capabilities": {} }),
            )
            .await;

            init_task.await.unwrap().unwrap();
        }

        #[tokio::test]
        async fn test_initialize_advertises_hierarchical_document_symbols() {
            let (client, mut server) = fake_lsp_client();

            let config = ServerInitConfig {
                server_config: LspServerConfig::rust_analyzer(),
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            };

            let init_task =
                tokio::spawn(async move { LspServer::initialize(&client, &config).await });

            let mut reader = BufReader::new(&mut server.write_stdout);
            let request = read_framed_message(&mut reader).await;
            let params: InitializeParams =
                serde_json::from_value(request["params"].clone()).unwrap();
            let document_symbol = params
                .capabilities
                .text_document
                .unwrap()
                .document_symbol
                .unwrap();

            assert_eq!(request["method"], "initialize");
            assert_eq!(document_symbol.dynamic_registration, Some(false));
            assert_eq!(
                document_symbol.hierarchical_document_symbol_support,
                Some(true)
            );
            assert_eq!(
                document_symbol.symbol_kind.unwrap().value_set,
                Some(SUPPORTED_SYMBOL_KINDS.to_vec())
            );

            write_success_response(
                &mut server.read_half_stdin,
                &request["id"].clone(),
                serde_json::json!({ "capabilities": {} }),
            )
            .await;

            init_task.await.unwrap().unwrap();
        }

        #[tokio::test]
        async fn test_initialize_accepts_resolved_dot_workspace_root() {
            let temp_dir = TempDir::new().unwrap();
            let base = dunce::canonicalize(temp_dir.path()).unwrap();
            let workspace_roots =
                crate::resolve_workspace_roots(&[PathBuf::from(".")], &base).unwrap();
            assert_eq!(workspace_roots, vec![base.clone()]);

            let (client, mut server) = fake_lsp_client();
            let config = ServerInitConfig {
                server_config: LspServerConfig::rust_analyzer(),
                workspace_roots,
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            };

            let init_task =
                tokio::spawn(async move { LspServer::initialize(&client, &config).await });

            let mut reader = BufReader::new(&mut server.write_stdout);
            let request = read_framed_message(&mut reader).await;
            let expected_uri = try_path_to_uri(&base).unwrap();
            assert_eq!(
                request["params"]["workspaceFolders"][0]["uri"],
                expected_uri.as_ref()
            );

            write_success_response(
                &mut server.read_half_stdin,
                &request["id"].clone(),
                serde_json::json!({ "capabilities": {} }),
            )
            .await;

            init_task.await.unwrap().unwrap();
        }
    }

    #[tokio::test]
    async fn test_spawn_batch_logs_each_failure() {
        let configs = vec![
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "test1".to_string(),
                    command: "nonexistent-test1".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec![],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
            ServerInitConfig {
                server_config: LspServerConfig {
                    language_id: "test2".to_string(),
                    command: "nonexistent-test2".to_string(),
                    args: vec![],
                    env: std::collections::HashMap::new(),
                    file_patterns: vec![],
                    initialization_options: None,
                    timeout_seconds: 10,
                    request_timeout_seconds: 10,
                    heuristics: None,
                    name: None,
                    handles: None,
                    indexing: crate::bridge::IndexingPolicy::Auto,
                },
                workspace_roots: vec![],
                initialization_options: None,
                position_encodings: vec!["utf-8".to_string(), "utf-16".to_string()],
                notification_tx: None,
            },
        ];

        let result = LspServer::spawn_batch(&configs).await;

        assert_eq!(result.failure_count(), 2);
        assert_eq!(result.failures[0].language_id, "test1");
        assert_eq!(result.failures[1].language_id, "test2");
    }

    /// Minimal [`LspServerConfig`] for `build_command` tests, where only
    /// `command`/`args`/`env` matter.
    fn bare_server_config(env: HashMap<String, String>) -> LspServerConfig {
        LspServerConfig {
            language_id: "test".to_string(),
            command: "irrelevant-for-build-command".to_string(),
            args: vec![],
            env,
            file_patterns: vec![],
            initialization_options: None,
            timeout_seconds: 5,
            request_timeout_seconds: 5,
            heuristics: None,
            name: None,
            handles: None,
            indexing: crate::bridge::IndexingPolicy::Auto,
        }
    }

    /// Collects the env vars a `Command` would set, resolving `env_clear`
    /// removals (`None` values from `get_envs`) away so the map reflects
    /// what the child process would actually see.
    fn effective_envs(command: &Command) -> HashMap<String, String> {
        command
            .as_std()
            .get_envs()
            .filter_map(|(k, v)| {
                v.map(|v| {
                    (
                        k.to_string_lossy().into_owned(),
                        v.to_string_lossy().into_owned(),
                    )
                })
            })
            .collect()
    }

    /// Regression test for #236/#246: a spawned LSP server used to inherit
    /// mcpls's entire environment. `build_command` must only pass through
    /// `ENV_PASSTHROUGH` keys from `parent_env`, not arbitrary ones.
    #[test]
    fn test_build_command_excludes_non_allowlisted_parent_env_vars() {
        let config = bare_server_config(HashMap::new());
        let command = LspServer::build_command(&config, |key| match key {
            "PATH" => Some("/parent/bin".into()),
            "MCPLS_TEST_LEAK_CANARY" => Some("should-not-reach-child".into()),
            _ => None,
        });

        let envs = effective_envs(&command);

        assert!(
            !envs.contains_key("MCPLS_TEST_LEAK_CANARY"),
            "non-allowlisted parent env var leaked into child command: {envs:?}"
        );

        // The assertion above is provably vacuous on its own:
        // `Command::get_envs()` only reports explicit `.env()`/`.envs()`
        // modifications and is blind to whether `.env_clear()` was called,
        // and `build_command`'s passthrough loop never even queries
        // `parent_env` for a key outside `ENV_PASSTHROUGH`, so it would
        // pass unchanged even if `.env_clear()` were deleted from
        // `build_command` entirely. `std::process::Command`'s `Debug` impl
        // does encode clearing, prefixing the formatted command with
        // `env -i ` on Unix once `.env_clear()` has run; assert on that to
        // actually guard against the clear being removed.
        #[cfg(unix)]
        assert!(
            format!("{:?}", command.as_std()).starts_with("env -i "),
            "build_command must call .env_clear() so the child doesn't inherit the full parent environment"
        );
    }

    /// Regression test for #236/#246: allowlisted vars present in the parent
    /// (e.g. `PATH`) must still reach the child.
    #[test]
    fn test_build_command_passes_through_allowlisted_env_vars() {
        let config = bare_server_config(HashMap::new());
        let command =
            LspServer::build_command(&config, |key| (key == "PATH").then(|| "/parent/bin".into()));

        let envs = effective_envs(&command);

        assert_eq!(envs.get("PATH"), Some(&"/parent/bin".to_string()));
    }

    /// Regression test for #247: `LspServerConfig::env` entries must reach
    /// the spawned child (previously dead configuration).
    #[test]
    fn test_build_command_includes_configured_env_vars() {
        let mut env = HashMap::new();
        env.insert(
            "MCPLS_TEST_CONFIGURED".to_string(),
            "from-server-config".to_string(),
        );
        let config = bare_server_config(env);
        let command = LspServer::build_command(&config, |_| None);

        let envs = effective_envs(&command);

        assert_eq!(
            envs.get("MCPLS_TEST_CONFIGURED"),
            Some(&"from-server-config".to_string())
        );
    }

    /// Regression test for #247: a `LspServerConfig::env` entry must be able
    /// to override an allowlisted passthrough value, since `config.env` is
    /// applied after the passthrough loop in `build_command`.
    #[test]
    fn test_build_command_configured_env_overrides_allowlisted_var() {
        let mut env = HashMap::new();
        env.insert("PATH".to_string(), "/configured/override/path".to_string());
        let config = bare_server_config(env);
        let command =
            LspServer::build_command(&config, |key| (key == "PATH").then(|| "/parent/bin".into()));

        let envs = effective_envs(&command);

        assert_eq!(
            envs.get("PATH"),
            Some(&"/configured/override/path".to_string())
        );
    }

    /// #174 §8/S2 regression: `register_servers`'s diagnostics-cache flags
    /// must be computed from the *rebound* router, not the pre-rebind view.
    /// Sets up a `python` config where a narrow "diagnostics-only" server
    /// (`pyright-diag`) is configured but never actually registers (as if
    /// it failed to spawn), leaving only a catch-all (`pylsp`) live. Before
    /// the fix, computing the flags from the pre-rebind router would resolve
    /// `Diagnostics` to the dead `pyright-diag` for every survivor, so
    /// `pylsp` would be flagged `false` and the diagnostics cache would go
    /// silently dark for `python` despite a live server being available.
    #[tokio::test]
    async fn test_register_servers_computes_diagnostics_flags_from_rebound_router() {
        use crate::bridge::Translator;
        use crate::config::{ServerId, ToolKind, ToolRouter};

        let pylsp_id = ServerId::from("pylsp");
        let configs = vec![
            LspServerConfig {
                language_id: "python".to_string(),
                command: "pyright-langserver".to_string(),
                args: vec![],
                env: std::collections::HashMap::new(),
                file_patterns: vec![],
                initialization_options: None,
                timeout_seconds: 30,
                request_timeout_seconds: 30,
                heuristics: None,
                name: Some("pyright-diag".to_string()),
                handles: Some(vec![ToolKind::Diagnostics]),
                indexing: crate::bridge::IndexingPolicy::Auto,
            },
            LspServerConfig {
                language_id: "python".to_string(),
                command: "pylsp".to_string(),
                args: vec![],
                env: std::collections::HashMap::new(),
                file_patterns: vec![],
                initialization_options: None,
                timeout_seconds: 30,
                request_timeout_seconds: 30,
                heuristics: None,
                name: Some("pylsp".to_string()),
                handles: None,
                indexing: crate::bridge::IndexingPolicy::Auto,
            },
        ];
        let router = ToolRouter::from_configs(&configs).unwrap();
        let translator = Translator::new().with_router(router);

        // Only pylsp actually registers; pyright-diag never spawned.
        let mut result = ServerInitResult::new();
        result.add_server(pylsp_id.clone(), fake_lsp_server());

        let registered = crate::register_servers(result, &translator, &HashMap::new());

        assert_eq!(
            registered.diagnostics_flags.get(&pylsp_id),
            Some(&true),
            "pylsp must inherit the diagnostics route once pyright-diag is \
             known dead, and the flag must reflect that post-rebind state"
        );
    }
}