php_lsp/backend/

mod.rs

use std::future::Future;
use std::path::PathBuf;
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};

#[allow(unused_imports)]
use self::helpers::*;

use arc_swap::ArcSwap;
use futures::future::Either;
use tower::Service;
use tower_lsp_server::jsonrpc::{Request as JsonRpcRequest, Response as JsonRpcResponse};

/// Sent to the client once Phase 3 (reference index build) finishes.
/// Allows tests and tooling to wait for the codebase fast path to be active.
enum IndexReadyNotification {}
impl tower_lsp_server::ls_types::notification::Notification for IndexReadyNotification {
    type Params = ();
    const METHOD: &'static str = "$/php-lsp/indexReady";
}

/// A `$/progress` partial-result batch for `textDocument/references`.
///
/// `lsp_types::ProgressParamsValue` only has a `WorkDone` variant (it can't
/// carry an arbitrary partial-result payload), so partial results use this
/// hand-rolled notification instead — same `$/progress` method, but `value`
/// is the request's own result type unwrapped, per the LSP spec's
/// partial-result shape.
enum ReferencesPartialResult {}
#[derive(serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct ReferencesPartialResultParams {
    token: tower_lsp_server::ls_types::NumberOrString,
    value: Vec<tower_lsp_server::ls_types::Location>,
}
impl tower_lsp_server::ls_types::notification::Notification for ReferencesPartialResult {
    type Params = ReferencesPartialResultParams;
    const METHOD: &'static str = "$/progress";
}

/// Stream a batch of reference locations to the client as a `$/progress`
/// partial result. Best-effort: the final response is always sent
/// separately and is unaffected if the client ignores this.
pub(crate) async fn send_references_partial_result(
    client: &Client,
    token: tower_lsp_server::ls_types::NumberOrString,
    locations: Vec<tower_lsp_server::ls_types::Location>,
) {
    client
        .send_notification::<ReferencesPartialResult>(ReferencesPartialResultParams {
            token,
            value: locations,
        })
        .await;
}

use tower_lsp_server::Client;
use tower_lsp_server::ls_types::*;

/// Response for the `$/php-lsp/debugStats` custom request.
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct DebugStats {
    /// Cumulative count of real `ParsedDoc` parses (cache misses).
    pub parses: u64,
    /// Times mir's reference index was locked. Reads are per-key posting
    /// lookups and edits commit one file's postings, so this grows by a
    /// small bounded amount per operation — never per candidate file.
    pub ref_index_locks: u64,
    /// Analysis warm sweeps run to completion (not cancelled). Lets benches
    /// and tests wait for the post-index sweep before baselining.
    pub warm_sweeps_completed: u64,
    /// Whether mir's workspace symbol index singleton is populated (seeded
    /// from the disk cache at warm start, or built by the first sweep).
    pub workspace_symbol_index_ready: bool,
    /// Executions of mir's tracked O(all-files) symbol-index walk. A
    /// cache-warm session must keep this at zero — the regression tests
    /// assert it.
    pub workspace_index_walks: u64,
    /// Workspace-wide FQN/text-needle scan passes for reference-scope
    /// narrowing (`DocumentStore::resolve_reachability_queries`). A request
    /// with many narrowing-requiring declarations (e.g. code lens on a file
    /// with several classes/public-static-methods) must pay one pass per
    /// request, not one per declaration — the regression tests assert the
    /// delta across such a request.
    pub reachability_scan_passes: u64,
    /// Real `FileAnalyzer::analyze` runs (never a cache hit). Concurrent
    /// callers racing for the same uncached file's analysis (e.g. `did_open`
    /// diagnostics vs. a fast-following hover) must serialize onto one run,
    /// not one per caller — the regression test asserts the delta.
    pub analysis_compute_count: u64,
    /// `DocumentStore::warm_start_indexes` calls that replayed at least one
    /// file. A runtime-added workspace folder runs this in the same spawned
    /// task as its scan, before the refresh-request notifications go out —
    /// tests await a count bump here instead of guessing a fixed delay.
    pub warm_start_replays_completed: u64,
    /// Section currently parked at the debug gate (see `debug_gate.rs`), if
    /// any. The responsiveness tests poll this to prove a handler's blocking
    /// work is both off the serve future and genuinely in flight.
    pub debug_gate_held: Option<String>,
    /// Lifecycle notifications currently executing. Used by race tests as a
    /// completion barrier; settled URIs must not remain retained here.
    pub lifecycle_intents: u64,
    /// Files mirrored into the salsa workspace. Denominator for the per-file
    /// cache sizes below.
    pub workspace_file_count: u64,
    /// Entries in the semantic-tokens delta cache.
    pub token_cache_len: u64,
    /// Entries in the mirrored-source-text cache. Expected to track
    /// `workspace_file_count`.
    pub text_cache_len: u64,
    /// Entries in the read-through `ParsedDoc` cache (LRU-capped).
    pub parsed_cache_len: u64,
    /// Entries in the per-file `FileAnalysis` cache (LRU-capped).
    pub analysis_cache_len: u64,
    /// Entries in the owned-`Program` cache (LRU-capped).
    pub owned_program_cache_len: u64,
    /// Hits served from mir's `indexed_references_to` memoization cache
    /// (see `mir_analyzer::AnalysisSession::ref_query_cache_hits`).
    pub mir_ref_query_cache_hits: u64,
    /// Hits served from mir's `indexed_subtype_classes` memoization cache
    /// (see `mir_analyzer::AnalysisSession::subtype_query_cache_hits`).
    pub mir_subtype_query_cache_hits: u64,
    /// Per-file text scans recorded in mir's own `ClassMentionIndex` — the
    /// single shared backend every `resolve_reachability_queries` needle is
    /// answered by. The ratio against `reachability_scan_passes` is the
    /// per-file mention cache's hit rate — a warm, unedited repeat query
    /// should not move this at all.
    pub mir_mention_scans_recorded: u64,
}

/// Params for the `$/php-lsp/debugHoldGate` custom request.
#[cfg(feature = "test-hooks")]
#[derive(Debug, serde::Serialize, serde::Deserialize)]
pub struct DebugHoldGateParams {
    /// One of the `GATE_*` constants in `debug_gate`.
    pub section: String,
}

/// The one place custom methods are registered — `main` and the test harness
/// both build the service here so their method tables can never drift. The
/// gate methods exist only under `test-hooks` (test targets); a production
/// build answers them with MethodNotFound like any unknown method.
pub fn build_lsp_service() -> (LifecycleService, tower_lsp_server::ClientSocket) {
    let builder = tower_lsp_server::LspService::build(Backend::new)
        .custom_method("$/php-lsp/debugStats", Backend::debug_stats);
    #[cfg(feature = "test-hooks")]
    let builder = builder
        .custom_method("$/php-lsp/debugHoldGate", Backend::debug_hold_gate)
        .custom_method("$/php-lsp/debugReleaseGate", Backend::debug_release_gate);
    let (service, socket) = builder.finish();
    (LifecycleService { inner: service }, socket)
}

/// Records document lifecycle order before tower starts polling notification
/// futures. The transport deliberately runs up to four messages concurrently,
/// so handler start order alone is not the order in which the client sent them.
pub struct LifecycleService {
    inner: tower_lsp_server::LspService<Backend>,
}

tokio::task_local! {
    static LIFECYCLE_GENERATION: u64;
}

fn lifecycle_generation() -> u64 {
    LIFECYCLE_GENERATION
        .try_with(|generation| *generation)
        .expect("document lifecycle handler called outside LifecycleService")
}

struct LifecycleIntentGuard {
    open_files: OpenFiles,
    uri: Uri,
    generation: u64,
}

impl Drop for LifecycleIntentGuard {
    fn drop(&mut self) {
        self.open_files.finish_lifecycle_intent(&self.uri);
    }
}

impl Service<JsonRpcRequest> for LifecycleService {
    type Response = Option<JsonRpcResponse>;
    type Error = tower_lsp_server::ExitedError;
    type Future = Either<
        Pin<
            Box<
                dyn Future<Output = Result<Option<JsonRpcResponse>, tower_lsp_server::ExitedError>>
                    + Send,
            >,
        >,
        <tower_lsp_server::LspService<Backend> as Service<JsonRpcRequest>>::Future,
    >;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, request: JsonRpcRequest) -> Self::Future {
        let lifecycle = self.inner.inner().note_lifecycle_intent(&request);
        let future = self.inner.call(request);
        match lifecycle {
            Some(guard) => {
                let generation = guard.generation;
                Either::Left(Box::pin(LIFECYCLE_GENERATION.scope(
                    generation,
                    async move {
                        let _guard = guard;
                        future.await
                    },
                )))
            }
            None => Either::Right(future),
        }
    }
}

use crate::document::ast::ParsedDoc;
use crate::document::document_store::DocumentStore;
use crate::document::open_files::OpenFiles;
use crate::lang::autoload::Psr4Map;
use crate::lang::config::LspConfig;
use crate::laravel::LaravelIndex;

use crate::analysis::diagnostics::merge_file_diagnostics;
use crate::document::open_files::compute_open_file_diagnostics;

pub struct Backend {
    client: Client,
    docs: Arc<DocumentStore>,
    /// Open-file state: text, version token, parse diagnostics.
    /// Files that are only background-indexed (never opened in the editor)
    /// do not appear here; they live only in `DocumentStore`'s salsa layer.
    open_files: OpenFiles,
    root_paths: Arc<ArcSwap<Vec<PathBuf>>>,
    psr4: Arc<ArcSwap<Psr4Map>>,
    laravel: Arc<ArcSwap<LaravelIndex>>,
    config: Arc<ArcSwap<LspConfig>>,
    /// Capabilities the client declared in `initialize`. Consulted in
    /// `initialized` to decide which capabilities are safe to register
    /// dynamically (e.g. a client that didn't declare
    /// `typeHierarchy.dynamicRegistration` won't understand a
    /// `client/registerCapability` call for it).
    client_capabilities: Arc<ArcSwap<ClientCapabilities>>,
    /// Test-only hold points for the responsiveness regression tests.
    debug_gate: Arc<debug_gate::DebugGate>,
}

impl Backend {
    pub fn new(client: Client) -> Self {
        // No imperative Codebase field anymore — analysis reads the
        // salsa-memoized `codebase` query, which composes bundled stubs + every
        // file's StubSlice and returns a fresh `Arc<Codebase>` (or the memoized
        // one when inputs are unchanged).
        let docs = Arc::new(DocumentStore::new());
        let psr4 = docs.psr4_arc();
        Backend {
            client,
            docs,
            open_files: OpenFiles::new(),
            root_paths: Arc::new(ArcSwap::from_pointee(Vec::new())),
            psr4,
            laravel: Arc::new(ArcSwap::from_pointee(LaravelIndex::default())),
            config: Arc::new(ArcSwap::from_pointee(LspConfig::default())),
            client_capabilities: Arc::new(ArcSwap::from_pointee(ClientCapabilities::default())),
            debug_gate: Arc::new(debug_gate::DebugGate::new()),
        }
    }

    /// Capture `didOpen`/`didClose` state as soon as it enters the service,
    /// rather than when its async handler happens to be polled.
    fn note_lifecycle_intent(&self, request: &JsonRpcRequest) -> Option<LifecycleIntentGuard> {
        let is_open = match request.method() {
            "textDocument/didOpen" => true,
            "textDocument/didClose" => false,
            _ => return None,
        };
        let uri = request
            .params()
            .and_then(|params| serde_json::to_value(params).ok())
            .and_then(|params| {
                params
                    .pointer("/textDocument/uri")?
                    .as_str()
                    .map(str::to_owned)
            })
            .and_then(|uri| uri.parse::<Uri>().ok())?;
        let generation = self.open_files.note_lifecycle_intent(uri.clone(), is_open);
        Some(LifecycleIntentGuard {
            open_files: self.open_files.clone(),
            uri,
            generation,
        })
    }

    /// `$/php-lsp/debugStats` — internal observability counters, used by the
    /// stress tests to assert the read path doesn't parse the whole workspace
    /// and that reference-index lock traffic stays bounded per operation.
    pub async fn debug_stats(&self) -> tower_lsp_server::jsonrpc::Result<DebugStats> {
        Ok(DebugStats {
            parses: self.docs.parse_count(),
            ref_index_locks: self.docs.ref_index_lock_count(),
            warm_sweeps_completed: self.docs.warm_sweeps_completed(),
            workspace_symbol_index_ready: self.docs.workspace_symbol_index_ready(),
            workspace_index_walks: self.docs.workspace_index_walks(),
            reachability_scan_passes: self.docs.reachability_scan_passes(),
            analysis_compute_count: self.docs.analysis_compute_count(),
            warm_start_replays_completed: self.docs.warm_start_replays_completed(),
            debug_gate_held: self.debug_gate.held_section(),
            lifecycle_intents: self.open_files.lifecycle_intent_count() as u64,
            workspace_file_count: self.docs.workspace_file_count(),
            token_cache_len: self.docs.token_cache_len(),
            text_cache_len: self.docs.text_cache_len(),
            parsed_cache_len: self.docs.parsed_cache_len(),
            analysis_cache_len: self.docs.analysis_cache_len(),
            owned_program_cache_len: self.docs.owned_program_cache_len(),
            mir_ref_query_cache_hits: self.docs.mir_ref_query_cache_hits(),
            mir_subtype_query_cache_hits: self.docs.mir_subtype_query_cache_hits(),
            mir_mention_scans_recorded: self.docs.mir_mention_scans_recorded(),
        })
    }

    /// `$/php-lsp/debugHoldGate` — test-only: park the next blocking-pool
    /// passage through the named section until `debugReleaseGate`.
    #[cfg(feature = "test-hooks")]
    pub async fn debug_hold_gate(
        &self,
        params: DebugHoldGateParams,
    ) -> tower_lsp_server::jsonrpc::Result<()> {
        self.debug_gate.arm(&params.section);
        Ok(())
    }

    /// `$/php-lsp/debugReleaseGate` — release a passage parked by
    /// `debugHoldGate` (and disarm the gate).
    #[cfg(feature = "test-hooks")]
    pub async fn debug_release_gate(&self) -> tower_lsp_server::jsonrpc::Result<()> {
        self.debug_gate.release();
        Ok(())
    }

    fn set_open_text(&self, uri: Uri, text: String) -> u64 {
        self.open_files.set_open_text(&self.docs, uri, text)
    }

    fn close_open_file(&self, uri: &Uri) {
        self.open_files.close(&self.docs, uri);
    }

    /// Background-index a file from disk, but only if it isn't currently
    /// open in the editor — the editor's buffer is authoritative while a
    /// file is open, and we must not overwrite it with disk contents.
    fn ingest_if_not_open(&self, uri: Uri, text: &str) {
        if !self.open_files.contains(&uri) {
            self.docs.ingest(uri, text);
        }
    }

    fn get_open_text(&self, uri: &Uri) -> Option<Arc<str>> {
        self.open_files.text(uri)
    }

    /// See [`offload::run`]. The sanctioned way for a handler to leave the
    /// async runtime worker for CPU-bound work with no debug-gated test.
    async fn blocking<F, R>(&self, label: &'static str, f: F) -> Option<R>
    where
        F: FnOnce() -> R + Send + 'static,
        R: Send + 'static,
    {
        offload::run(label, f).await
    }

    /// See [`offload::run_gated`]. Use when a responsiveness regression
    /// test needs to pin this closure in flight via a `GATE_*` section.
    async fn blocking_gated<F, R>(&self, section: &'static str, f: F) -> Option<R>
    where
        F: FnOnce() -> R + Send + 'static,
        R: Send + 'static,
    {
        offload::run_gated(&self.debug_gate, section, f).await
    }

    fn set_parse_diagnostics(&self, uri: &Uri, diagnostics: Vec<Diagnostic>) {
        self.open_files.set_parse_diagnostics(uri, diagnostics);
    }

    fn all_open_files_with_diagnostic_versions(&self) -> Vec<(Uri, Option<i64>)> {
        self.open_files.all_with_versions()
    }

    fn open_urls(&self) -> Vec<Uri> {
        self.open_files.urls()
    }

    fn get_doc(&self, uri: &Uri) -> Option<Arc<ParsedDoc>> {
        self.open_files.get_doc(&self.docs, uri)
    }

    fn get_doc_stale(&self, uri: &Uri) -> Option<Arc<ParsedDoc>> {
        self.open_files.get_doc_stale(&self.docs, uri)
    }

    /// Re-mirror every open buffer's live text into `self.docs`.
    ///
    /// Needed after anything that rebuilds the analysis session's salsa db
    /// (`DocumentStore::set_session_cache_dir` / `set_php_version`, when
    /// they report a drop): the workspace scan that normally repopulates
    /// `lsp_ws_files` explicitly skips files already open, so an open file
    /// whose entry was cleared by the drop would otherwise stay unresolvable
    /// (`get_doc` returning `None`) until the next edit.
    pub(crate) fn remirror_open_files(&self) {
        for uri in self.open_files.urls() {
            if let Some(text) = self.open_files.text(&uri) {
                self.docs.mirror_text_arc(&uri, text);
            }
        }
    }

    /// `use Foo as Bar;` map for a single file, read directly from the AST.
    /// Memoized per `ParsedDoc` (see `ParsedDoc::file_imports`) — cheap to
    /// call repeatedly within or across requests against the same revision.
    fn file_imports(&self, uri: &Uri) -> Arc<std::collections::HashMap<String, String>> {
        self.docs
            .get_doc_salsa(uri)
            .map(|doc| doc.file_imports())
            .unwrap_or_default()
    }

    /// Resolve the PHP version to use. See `autoload::resolve_php_version_from_roots`
    /// for the full priority order.
    fn resolve_php_version(&self, explicit: Option<&str>) -> (String, &'static str) {
        let roots = self.root_paths.load();
        crate::lang::autoload::resolve_php_version_from_roots(&roots, explicit)
    }
}

/// Refine the cursor's `(word, kind)` for a references request using
/// declaration-aware heuristics, returning the (possibly rewritten) word, its
/// symbol kind, and — for class constants — the owning class short name.
///
/// Checks, in order: promoted constructor property params (so `$name` in
/// `__construct(public string $name)` resolves to the `->name` property, not
/// `$name` variable occurrences), then property / constant
/// declarations, falling back to the character-based `symbol_kind_at` heuristic.
fn resolve_reference_symbol(
    doc_opt: Option<&Arc<ParsedDoc>>,
    source: &str,
    position: Position,
    word: String,
) -> (
    String,
    Option<crate::navigation::references::SymbolKind>,
    Option<String>,
) {
    use crate::navigation::references::SymbolKind;
    let mut constant_owner: Option<String> = None;
    let (word, kind) = if let Some(doc) = doc_opt
        && let Some(prop_name) =
            promoted_property_at_cursor(doc.source(), &doc.program().stmts, position)
    {
        (prop_name, Some(SymbolKind::Property))
    } else if let Some(doc) = doc_opt {
        let stmts = &doc.program().stmts;
        if let Some(prop_name) = cursor_is_on_property_decl(doc.source(), stmts, position) {
            (prop_name, Some(SymbolKind::Property))
        } else if let Some((const_name, owner)) =
            cursor_is_on_constant_decl(doc.source(), stmts, position)
        {
            constant_owner = owner;
            (const_name, Some(SymbolKind::Constant))
        } else {
            let k = symbol_kind_at(source, position, &word);
            // For constant access sites (`ClassName::CONST`, `self::CONST`),
            // extract the owning class so the constant walker is scoped to
            // the right class rather than falling back to the global-constant
            // path (which would look for a top-level constant named `CONST`).
            if matches!(k, Some(SymbolKind::Constant))
                && let Some(raw) = class_before_double_colon(source, position)
            {
                constant_owner = Some(match raw.as_str() {
                    "self" | "static" => {
                        crate::types::type_map::enclosing_class_at(doc.source(), doc, position)
                            .unwrap_or(raw)
                    }
                    // `parent::CONST` is compile-time resolved to the literal
                    // `extends` class, never subject to late static binding —
                    // same semantics `resolve_parent_construct_class` and
                    // `type_definition.rs::param_decl_type` already apply.
                    // Without this, the owner stayed the literal string
                    // `"parent"`, which can never match a real class.
                    "parent" => {
                        crate::types::type_map::enclosing_class_at(doc.source(), doc, position)
                            .and_then(|child| {
                                crate::types::type_map::parent_class_name(doc, &child)
                            })
                            .unwrap_or(raw)
                    }
                    _ => raw,
                });
            }
            (word, k)
        }
    } else {
        let k = symbol_kind_at(source, position, &word);
        (word, k)
    };
    (word, kind, constant_owner)
}

/// Extract the class name (or pseudo-keyword) immediately to the left of `::` at
/// the cursor position. Returns `None` when the cursor is not on an identifier
/// preceded by `::`.
///
/// Used to populate `constant_owner` for constant access sites so that
/// `Status::ACTIVE` (cursor on `ACTIVE`) scopes the constant walker to `Status`
/// rather than treating `ACTIVE` as a global constant.
fn class_before_double_colon(source: &str, position: Position) -> Option<String> {
    let line = source.lines().nth(position.line as usize)?;
    let chars: Vec<char> = line.chars().collect();
    let col = position.character as usize;

    let mut utf16_col = 0usize;
    let mut char_idx = 0usize;
    for ch in &chars {
        if utf16_col >= col {
            break;
        }
        utf16_col += ch.len_utf16();
        char_idx += 1;
    }

    let is_word = |c: char| c.is_alphanumeric() || c == '_';
    while char_idx > 0 && is_word(chars[char_idx - 1]) {
        char_idx -= 1;
    }

    if char_idx < 2 || chars[char_idx - 1] != ':' || chars[char_idx - 2] != ':' {
        return None;
    }

    let class_end = char_idx - 2;
    let mut class_start = class_end;
    while class_start > 0 && (is_word(chars[class_start - 1]) || chars[class_start - 1] == '\\') {
        class_start -= 1;
    }

    let name: String = chars[class_start..class_end].iter().collect();
    if name.is_empty() { None } else { Some(name) }
}

/// Takes `docs`/`open_files` by owned clone rather than `&Backend` because
/// did_change's blocking republish runs inside a detached `tokio::spawn`,
/// which requires a `'static` future — a borrow of `self` wouldn't live
/// long enough.
async fn compute_dependent_publishes_owned(
    docs: Arc<DocumentStore>,
    open_files: OpenFiles,
    changed_uri: Uri,
    diag_cfg: crate::lang::config::DiagnosticsConfig,
    is_laravel: bool,
) -> Vec<(Uri, Vec<Diagnostic>)> {
    tokio::task::spawn_blocking(move || {
        // A dependent sweep started during the initial scan can deadlock the
        // shared rayon pool: reanalysis retains salsa snapshots while a scan
        // writer waits for them to drop. Defer the sweep until readiness;
        // post-scan republishing covers every open file.
        if !docs.is_index_ready() {
            return Vec::new();
        }

        // rust-analyzer model: we only ever publish for files the editor has
        // open, so re-analyze exactly that set and let salsa memoization make
        // the unaffected ones ~free. No dependent set is computed at all —
        // the old path rebuilt mir's dependency_graph() on every keystroke,
        // an O(all-ingested-files) walk whose cost grew with session age.
        let open_set: Vec<std::sync::Arc<str>> = open_files
            .urls()
            .into_iter()
            .filter(|u| u != &changed_uri)
            .map(|u| std::sync::Arc::from(u.as_str()))
            .collect();
        if open_set.is_empty() {
            return Vec::new();
        }

        // The user is typing: pause the background scan's write storm so this
        // sweep's snapshots aren't repeatedly cancelled while indexing runs.
        let _interactive = docs.interactive_read_guard();
        // Cancel any older in-flight sweep and take a fresh token: when the
        // next edit starts its own sweep, this one stops at its next file
        // boundary instead of blocking typing behind the previous sweep.
        let cancel = docs.begin_reanalyze();
        // A newer edit that flipped `cancel` mid-sweep is now authoritative and
        // will republish; drop this sweep's partial results so they can't land
        // out of order and leave stale diagnostics as the final state.
        let Some(analyses) = docs.reanalyze_files(&open_set, &cancel) else {
            return Vec::new();
        };
        if cancel.is_cancelled() || analyses.is_empty() {
            return Vec::new();
        }

        let dependents: Vec<(Uri, mir_analyzer::FileAnalysis)> = analyses
            .into_iter()
            .filter_map(|(file, analysis)| {
                let url = (file.as_ref()).parse::<Uri>().ok()?;
                Some((url, analysis))
            })
            .collect();
        if dependents.is_empty() {
            return Vec::new();
        }

        // Workspace-level class issues (circular inheritance, override
        // violations, abstract-method gaps) aren't in `FileAnalysis` —
        // pull them in one batched call covering every affected file.
        let dep_files: Vec<Arc<str>> = dependents
            .iter()
            .map(|(u, _)| Arc::from(u.as_str()))
            .collect();
        let Ok(class_issues) = docs.with_snapshot(
            |session| session.prepare_for_query(None),
            |snap| snap.class_issues(&dep_files),
        ) else {
            return Vec::new();
        };
        let mut class_issues_by_file: std::collections::HashMap<Arc<str>, Vec<mir_issues::Issue>> =
            std::collections::HashMap::new();
        for issue in class_issues {
            if issue.suppressed {
                continue;
            }
            let file = issue.location.file.clone();
            class_issues_by_file.entry(file).or_default().push(issue);
        }

        let mut out: Vec<(Uri, Vec<Diagnostic>)> = Vec::with_capacity(dependents.len());
        for (url, analysis) in dependents {
            let parse = open_files.parse_diagnostics(&url).unwrap_or_default();
            let mut issues: Vec<mir_issues::Issue> = analysis
                .issues
                .into_iter()
                .filter(|i| !i.suppressed)
                .collect();
            if let Some(extra) = class_issues_by_file.remove(&Arc::<str>::from(url.as_str())) {
                issues.extend(extra);
            }
            let semantic =
                crate::semantic_diagnostics::issues_to_diagnostics(&issues, &url, &diag_cfg);
            let mut diags = merge_file_diagnostics(parse, semantic);
            diags.extend(crate::laravel::unguarded_model_diagnostics(
                &docs, &url, is_laravel,
            ));
            diags.extend(open_files.external_diagnostics(&url));
            out.push((url, diags));
        }
        out
    })
    .await
    .unwrap_or_default()
}

/// Republish diagnostics for every currently open file once the initial
/// workspace index finishes.
///
/// `compute_open_file_diagnostics` holds back workspace-symbol-dependent
/// issues (`UndefinedClass` and friends, see `issue_needs_workspace_index`)
/// until `docs.is_index_ready()`, so a file opened during the scan may be
/// first published missing some of those. Push-diagnostics clients (the
/// common case) have no other trigger to re-request them — pull clients get
/// `send_refresh_requests`'s `WorkspaceDiagnosticRefresh`, but push clients
/// would otherwise carry a stale view until the user's next edit. Skips
/// files whose recomputed diagnostics are identical to what was already
/// published.
pub(super) async fn republish_after_index_ready(
    client: Client,
    docs: Arc<DocumentStore>,
    open_files: OpenFiles,
    diag_cfg: crate::lang::config::DiagnosticsConfig,
    is_laravel: bool,
) {
    let uris = open_files.urls();
    if uris.is_empty() {
        return;
    }
    let docs_ref = Arc::clone(&docs);
    let open_files_ref = open_files.clone();
    let all: Vec<(Uri, Vec<Diagnostic>)> = tokio::task::spawn_blocking(move || {
        uris.into_iter()
            .map(|uri| {
                let diags = compute_open_file_diagnostics(
                    &docs_ref,
                    &open_files_ref,
                    &uri,
                    &diag_cfg,
                    is_laravel,
                );
                (uri, diags)
            })
            .collect()
    })
    .await
    .unwrap_or_default();
    for (uri, diags) in all {
        let hash = diagnostics_content_hash(&diags);
        if open_files.published_hash(&uri) == Some(hash) {
            continue;
        }
        open_files.note_published(&uri, hash);
        client.publish_diagnostics(uri, diags, None).await;
    }
}

/// Content hash of a diagnostics set, for skipping republishes the client
/// already displays. In-process only — never persisted.
pub(super) fn diagnostics_content_hash(diagnostics: &[Diagnostic]) -> u64 {
    use std::collections::hash_map::DefaultHasher;
    use std::hash::{Hash, Hasher};
    let mut hasher = DefaultHasher::new();
    serde_json::to_string(diagnostics)
        .unwrap_or_default()
        .hash(&mut hasher);
    hasher.finish()
}

/// Compute and publish diagnostics for `uri`, then republish any open files
/// that depend on it. Requires `open_files.set_parse_diagnostics` to be up to
/// date for `uri` before this is called.
///
/// The edited file always publishes (editors rely on one publish per change).
/// Dependents publish only when their content differs from the last publish —
/// the sweep re-analyzes every open file on every edit, and unchanged results
/// would otherwise flood the client with no-op notifications.
pub(super) enum DiagnosticPublish {
    Open { version: i32, generation: u64 },
    Other(Option<i32>),
}

pub(super) async fn publish_with_dependents(
    client: Client,
    docs: Arc<DocumentStore>,
    open_files: OpenFiles,
    uri: Uri,
    publish: DiagnosticPublish,
    diag_cfg: crate::lang::config::DiagnosticsConfig,
    is_laravel: bool,
) {
    let (version, expected_open_generation) = match publish {
        DiagnosticPublish::Open {
            version,
            generation,
        } => (Some(version), Some(generation)),
        DiagnosticPublish::Other(version) => (version, None),
    };
    let docs_ref = Arc::clone(&docs);
    let open_files_ref = open_files.clone();
    let uri_ref = uri.clone();
    let diag_cfg_ref = diag_cfg.clone();
    let all_diags = tokio::task::spawn_blocking(move || {
        compute_open_file_diagnostics(
            &docs_ref,
            &open_files_ref,
            &uri_ref,
            &diag_cfg_ref,
            is_laravel,
        )
    })
    .await
    .unwrap_or_default();
    if expected_open_generation
        .is_some_and(|generation| !open_files.should_apply_lifecycle(&uri, generation, true))
    {
        return;
    }
    open_files.note_published(&uri, diagnostics_content_hash(&all_diags));
    client
        .publish_diagnostics(uri.clone(), all_diags, version)
        .await;
    let dependents =
        compute_dependent_publishes_owned(docs, open_files.clone(), uri, diag_cfg, is_laravel)
            .await;
    for (dep_uri, dep_diags) in dependents {
        let hash = diagnostics_content_hash(&dep_diags);
        if open_files.published_hash(&dep_uri) == Some(hash) {
            continue;
        }
        open_files.note_published(&dep_uri, hash);
        client.publish_diagnostics(dep_uri, dep_diags, None).await;
    }
}

/// Generate a stable result_id for diagnostics. Uses the count and position of diagnostics
/// to create a stable identifier. Same diagnostics = same result_id.
fn compute_diagnostic_result_id(diagnostics: &[Diagnostic], uri: &str) -> String {
    use std::collections::hash_map::DefaultHasher;
    use std::hash::{Hash, Hasher};

    let mut hasher = DefaultHasher::new();
    uri.hash(&mut hasher);
    diagnostics.len().hash(&mut hasher);

    for diag in diagnostics {
        diag.range.start.line.hash(&mut hasher);
        diag.range.start.character.hash(&mut hasher);
        diag.range.end.line.hash(&mut hasher);
        diag.range.end.character.hash(&mut hasher);
        diag.message.hash(&mut hasher);
        let severity_val = match diag.severity {
            Some(tower_lsp_server::ls_types::DiagnosticSeverity::ERROR) => 1,
            Some(tower_lsp_server::ls_types::DiagnosticSeverity::WARNING) => 2,
            Some(tower_lsp_server::ls_types::DiagnosticSeverity::INFORMATION) => 3,
            Some(tower_lsp_server::ls_types::DiagnosticSeverity::HINT) => 4,
            None => 0,
            _ => 5, // Unknown variants
        };
        severity_val.hash(&mut hasher);
        if let Some(code) = &diag.code {
            format!("{:?}", code).hash(&mut hasher);
        }
        if let Some(source) = &diag.source {
            source.hash(&mut hasher);
        }
        if let Some(tags) = &diag.tags {
            for tag in tags {
                let tag_val = match *tag {
                    tower_lsp_server::ls_types::DiagnosticTag::UNNECESSARY => 1,
                    tower_lsp_server::ls_types::DiagnosticTag::DEPRECATED => 2,
                    _ => 3,
                };
                tag_val.hash(&mut hasher);
            }
        }
    }

    format!("v1:{:x}", hasher.finish())
}

pub mod debug_gate;
mod handlers;
mod helpers;
pub mod offload;
pub mod panic_guard;
mod server;
#[cfg(test)]
mod tests;