[ty] Initial support for workspace diagnostics (#18939)

## Summary

This PR adds initial support for workspace diagnostics in the ty server.

Reference spec:
https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_diagnostic

This is currently implemented via the **pull diagnostics method** which
was added in the current version (3.17) and the server advertises it via
the `diagnosticProvider.workspaceDiagnostics` server capability.

**Note:** This might be a bit confusing but a workspace diagnostics is
not for a single workspace but for all the workspaces that the server
handles. These are the ones that the server received during
initialization. Currently, the ty server doesn't support multiple
workspaces so this capability is also limited to provide diagnostics
only for a single workspace (the first one if the client provided
multiple).

A new `ty.diagnosticMode` server setting is added which can be either
`workspace` (for workspace diagnostics) or `openFilesOnly` (for checking
only open files) (default). This is same as
`python.analysis.diagnosticMode` that Pyright / Pylance utilizes. In the
future, we could use the value under `python.*` namespace as fallback to
improve the experience on user side to avoid setting the value multiple
times.

Part of: astral-sh/ty#81

## Test Plan

This capability was introduced in the current LSP version (~3 years) and
the way it's implemented by various clients are a bit different. I've
provided notes on what I've noticed and what would need to be done on
our side to further improve the experience.

### VS Code

VS Code sends the `workspace/diagnostic` requests every ~2 second:

```
[Trace - 12:12:32 PM] Sending request 'workspace/diagnostic - (403)'.
[Trace - 12:12:32 PM] Received response 'workspace/diagnostic - (403)' in 2ms.
[Trace - 12:12:34 PM] Sending request 'workspace/diagnostic - (404)'.
[Trace - 12:12:34 PM] Received response 'workspace/diagnostic - (404)' in 2ms.
[Trace - 12:12:36 PM] Sending request 'workspace/diagnostic - (405)'.
[Trace - 12:12:36 PM] Received response 'workspace/diagnostic - (405)' in 2ms.
[Trace - 12:12:38 PM] Sending request 'workspace/diagnostic - (406)'.
[Trace - 12:12:38 PM] Received response 'workspace/diagnostic - (406)' in 3ms.
[Trace - 12:12:40 PM] Sending request 'workspace/diagnostic - (407)'.
[Trace - 12:12:40 PM] Received response 'workspace/diagnostic - (407)' in 2ms.
...
```

I couldn't really find any resource that explains this behavior. But,
this does mean that we'd need to implement the caching layer via the
previous result ids sooner. This will allow the server to avoid sending
all the diagnostics on every request and instead just send a response
stating that the diagnostics hasn't changed yet. This could possibly be
achieved by using the salsa ID.

If we switch from workspace diagnostics to open-files diagnostics, the
server would send the diagnostics only via the `textDocument/diagnostic`
endpoint. Here, when a document containing the diagnostic is closed, the
server would send a publish diagnostics notification with an empty list
of diagnostics to clear the diagnostics from that document. The issue is
the VS Code doesn't seem to be clearing the diagnostics in this case
even though it receives the notification. (I'm going to open an issue on
VS Code side for this today.)


https://github.com/user-attachments/assets/b0c0833d-386c-49f5-8a15-0ac9133e15ed

### Zed

Zed's implementation works by refreshing the workspace diagnostics
whenever the content of the documents are changed. This seems like a
very reasonable behavior and I was a bit surprised that VS Code didn't
use this heuristic.


https://github.com/user-attachments/assets/71c7b546-7970-434a-9ba0-4fa620647f6c

### Neovim

Neovim only recently added support for workspace diagnostics
(neovim/neovim#34262, merged ~3 weeks ago) so
it's only available on nightly versions.

The initial support is limited and requires fetching the workspace
diagnostics manually as demonstrated in the video. It doesn't support
refreshing the workspace diagnostics either, so that would need to be
done manually as well. I'm assuming that these are just a temporary
limitation and will be implemented before the stable release.


https://github.com/user-attachments/assets/25b4a0e5-9833-4877-88ad-279904fffaf9

Author: dhruvmanila

crates/ty_project/src/db.rs

@@ -83,15 +83,20 @@ impl ProjectDatabase {
 
     /// Checks all open files in the project and its dependencies.
     pub fn check(&self) -> Vec<Diagnostic> {
-        let mut reporter = DummyReporter;
-        let reporter = AssertUnwindSafe(&mut reporter as &mut dyn Reporter);
-        self.project().check(self, reporter)
+        self.check_with_mode(CheckMode::OpenFiles)
     }
 
     /// Checks all open files in the project and its dependencies, using the given reporter.
     pub fn check_with_reporter(&self, reporter: &mut dyn Reporter) -> Vec<Diagnostic> {
         let reporter = AssertUnwindSafe(reporter);
-        self.project().check(self, reporter)
+        self.project().check(self, CheckMode::OpenFiles, reporter)
+    }
+
+    /// Check the project with the given mode.
+    pub fn check_with_mode(&self, mode: CheckMode) -> Vec<Diagnostic> {
+        let mut reporter = DummyReporter;
+        let reporter = AssertUnwindSafe(&mut reporter as &mut dyn Reporter);
+        self.project().check(self, mode, reporter)
     }
 
     #[tracing::instrument(level = "debug", skip(self))]
@@ -157,6 +162,17 @@ impl std::fmt::Debug for ProjectDatabase {
     }
 }
 
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum CheckMode {
+    /// Checks only the open files in the project.
+    OpenFiles,
+
+    /// Checks all files in the project, ignoring the open file set.
+    ///
+    /// This includes virtual files, such as those created by the language server.
+    AllFiles,
+}
+
 /// Stores memory usage information.
 pub struct SalsaMemoryDump {
     total_fields: usize,

crates/ty_project/src/lib.rs

@@ -1,7 +1,7 @@
 use crate::glob::{GlobFilterCheckMode, IncludeResult};
 use crate::metadata::options::{OptionDiagnostic, ToSettingsError};
 use crate::walk::{ProjectFilesFilter, ProjectFilesWalker};
-pub use db::{Db, ProjectDatabase, SalsaMemoryDump};
+pub use db::{CheckMode, Db, ProjectDatabase, SalsaMemoryDump};
 use files::{Index, Indexed, IndexedFiles};
 use metadata::settings::Settings;
 pub use metadata::{ProjectMetadata, ProjectMetadataError};
@@ -214,6 +214,7 @@ impl Project {
     pub(crate) fn check(
         self,
         db: &ProjectDatabase,
+        mode: CheckMode,
         mut reporter: AssertUnwindSafe<&mut dyn Reporter>,
     ) -> Vec<Diagnostic> {
         let project_span = tracing::debug_span!("Project::check");
@@ -228,7 +229,11 @@ impl Project {
                 .map(OptionDiagnostic::to_diagnostic),
         );
 
-        let files = ProjectFiles::new(db, self);
+        let files = match mode {
+            CheckMode::OpenFiles => ProjectFiles::new(db, self),
+            // TODO: Consider open virtual files as well
+            CheckMode::AllFiles => ProjectFiles::Indexed(self.files(db)),
+        };
         reporter.set_files(files.len());
 
         diagnostics.extend(

crates/ty_server/src/server.rs

@@ -173,6 +173,7 @@ impl Server {
             diagnostic_provider: Some(DiagnosticServerCapabilities::Options(DiagnosticOptions {
                 identifier: Some(crate::DIAGNOSTIC_NAME.into()),
                 inter_file_dependencies: true,
+                workspace_diagnostics: true,
                 ..Default::default()
             })),
             text_document_sync: Some(TextDocumentSyncCapability::Options(

crates/ty_server/src/server/api.rs

@@ -33,6 +33,11 @@ pub(super) fn request(req: server::Request) -> Task {
         >(
             req, BackgroundSchedule::Worker
         ),
+        requests::WorkspaceDiagnosticRequestHandler::METHOD => background_request_task::<
+            requests::WorkspaceDiagnosticRequestHandler,
+        >(
+            req, BackgroundSchedule::Worker
+        ),
         requests::GotoTypeDefinitionRequestHandler::METHOD => background_document_request_task::<
             requests::GotoTypeDefinitionRequestHandler,
         >(
@@ -135,7 +140,6 @@ where
     }))
 }
 
-#[expect(dead_code)]
 fn background_request_task<R: traits::BackgroundRequestHandler>(
     req: server::Request,
     schedule: BackgroundSchedule,

crates/ty_server/src/server/api/diagnostics.rs

@@ -166,7 +166,7 @@ pub(super) fn compute_diagnostics(
 
 /// Converts the tool specific [`Diagnostic`][ruff_db::diagnostic::Diagnostic] to an LSP
 /// [`Diagnostic`].
-fn to_lsp_diagnostic(
+pub(super) fn to_lsp_diagnostic(
     db: &dyn Db,
     diagnostic: &ruff_db::diagnostic::Diagnostic,
     encoding: PositionEncoding,

crates/ty_server/src/server/api/notifications/did_close.rs

@@ -41,7 +41,12 @@ impl SyncNotificationHandler for DidCloseTextDocumentHandler {
             );
         }
 
-        clear_diagnostics(&key, client);
+        if !session.global_settings().diagnostic_mode().is_workspace() {
+            // The server needs to clear the diagnostics regardless of whether the client supports
+            // pull diagnostics or not. This is because the client only has the capability to fetch
+            // the diagnostics but does not automatically clear them when a document is closed.
+            clear_diagnostics(&key, client);
+        }
 
         Ok(())
     }

crates/ty_server/src/server/api/requests.rs

@@ -4,10 +4,12 @@ mod goto_type_definition;
 mod hover;
 mod inlay_hints;
 mod shutdown;
+mod workspace_diagnostic;
 
 pub(super) use completion::CompletionRequestHandler;
 pub(super) use diagnostic::DocumentDiagnosticRequestHandler;
 pub(super) use goto_type_definition::GotoTypeDefinitionRequestHandler;
 pub(super) use hover::HoverRequestHandler;
 pub(super) use inlay_hints::InlayHintRequestHandler;
 pub(super) use shutdown::ShutdownHandler;
+pub(super) use workspace_diagnostic::WorkspaceDiagnosticRequestHandler;

crates/ty_server/src/server/api/requests/workspace_diagnostic.rs

@@ -0,0 +1,108 @@
+use lsp_types::request::WorkspaceDiagnosticRequest;
+use lsp_types::{
+    FullDocumentDiagnosticReport, Url, WorkspaceDiagnosticParams, WorkspaceDiagnosticReport,
+    WorkspaceDiagnosticReportResult, WorkspaceDocumentDiagnosticReport,
+    WorkspaceFullDocumentDiagnosticReport,
+};
+use rustc_hash::FxHashMap;
+use ty_project::CheckMode;
+
+use crate::server::Result;
+use crate::server::api::diagnostics::to_lsp_diagnostic;
+use crate::server::api::traits::{
+    BackgroundRequestHandler, RequestHandler, RetriableRequestHandler,
+};
+use crate::session::WorkspaceSnapshot;
+use crate::session::client::Client;
+use crate::system::file_to_url;
+
+pub(crate) struct WorkspaceDiagnosticRequestHandler;
+
+impl RequestHandler for WorkspaceDiagnosticRequestHandler {
+    type RequestType = WorkspaceDiagnosticRequest;
+}
+
+impl BackgroundRequestHandler for WorkspaceDiagnosticRequestHandler {
+    fn run(
+        snapshot: WorkspaceSnapshot,
+        _client: &Client,
+        _params: WorkspaceDiagnosticParams,
+    ) -> Result<WorkspaceDiagnosticReportResult> {
+        let index = snapshot.index();
+
+        if !index.global_settings().diagnostic_mode().is_workspace() {
+            tracing::debug!("Workspace diagnostics is disabled; returning empty report");
+            return Ok(WorkspaceDiagnosticReportResult::Report(
+                WorkspaceDiagnosticReport { items: vec![] },
+            ));
+        }
+
+        let mut items = Vec::new();
+
+        for db in snapshot.projects() {
+            let diagnostics = db.check_with_mode(CheckMode::AllFiles);
+
+            // Group diagnostics by URL
+            let mut diagnostics_by_url: FxHashMap<Url, Vec<_>> = FxHashMap::default();
+
+            for diagnostic in diagnostics {
+                if let Some(span) = diagnostic.primary_span() {
+                    let file = span.expect_ty_file();
+                    let Some(url) = file_to_url(db, file) else {
+                        tracing::debug!("Failed to convert file to URL at {}", file.path(db));
+                        continue;
+                    };
+                    diagnostics_by_url.entry(url).or_default().push(diagnostic);
+                }
+            }
+
+            items.reserve(diagnostics_by_url.len());
+
+            // Convert to workspace diagnostic report format
+            for (url, file_diagnostics) in diagnostics_by_url {
+                let version = index
+                    .key_from_url(url.clone())
+                    .ok()
+                    .and_then(|key| index.make_document_ref(&key))
+                    .map(|doc| i64::from(doc.version()));
+
+                // Convert diagnostics to LSP format
+                let lsp_diagnostics = file_diagnostics
+                    .into_iter()
+                    .map(|diagnostic| {
+                        to_lsp_diagnostic(db, &diagnostic, snapshot.position_encoding())
+                    })
+                    .collect::<Vec<_>>();
+
+                items.push(WorkspaceDocumentDiagnosticReport::Full(
+                    WorkspaceFullDocumentDiagnosticReport {
+                        uri: url,
+                        version,
+                        full_document_diagnostic_report: FullDocumentDiagnosticReport {
+                            // TODO: We don't implement result ID caching yet
+                            result_id: None,
+                            items: lsp_diagnostics,
+                        },
+                    },
+                ));
+            }
+        }
+
+        Ok(WorkspaceDiagnosticReportResult::Report(
+            WorkspaceDiagnosticReport { items },
+        ))
+    }
+}
+
+impl RetriableRequestHandler for WorkspaceDiagnosticRequestHandler {
+    fn salsa_cancellation_error() -> lsp_server::ResponseError {
+        lsp_server::ResponseError {
+            code: lsp_server::ErrorCode::ServerCancelled as i32,
+            message: "server cancelled the request".to_owned(),
+            data: serde_json::to_value(lsp_types::DiagnosticServerCancellationData {
+                retrigger_request: true,
+            })
+            .ok(),
+        }
+    }
+}

crates/ty_server/src/session.rs

@@ -383,6 +383,10 @@ impl Session {
     pub(crate) fn client_capabilities(&self) -> &ResolvedClientCapabilities {
         &self.resolved_client_capabilities
     }
+
+    pub(crate) fn global_settings(&self) -> Arc<ClientSettings> {
+        self.index().global_settings()
+    }
 }
 
 /// A guard that holds the only reference to the index and allows modifying it.
@@ -469,7 +473,6 @@ pub(crate) struct WorkspaceSnapshot {
     position_encoding: PositionEncoding,
 }
 
-#[expect(dead_code)]
 impl WorkspaceSnapshot {
     pub(crate) fn projects(&self) -> &[ProjectDatabase] {
         &self.projects

crates/ty_server/src/session/options.rs

@@ -46,6 +46,26 @@ pub(crate) struct ClientOptions {
     /// Settings under the `python.*` namespace in VS Code that are useful for the ty language
     /// server.
     python: Option<Python>,
+    /// Diagnostic mode for the language server.
+    diagnostic_mode: Option<DiagnosticMode>,
+}
+
+/// Diagnostic mode for the language server.
+#[derive(Clone, Copy, Debug, Default, Deserialize)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[serde(rename_all = "camelCase")]
+pub(crate) enum DiagnosticMode {
+    /// Check only currently open files.
+    #[default]
+    OpenFilesOnly,
+    /// Check all files in the workspace.
+    Workspace,
+}
+
+impl DiagnosticMode {
+    pub(crate) fn is_workspace(self) -> bool {
+        matches!(self, DiagnosticMode::Workspace)
+    }
 }
 
 impl ClientOptions {
@@ -57,6 +77,7 @@ impl ClientOptions {
                 .and_then(|python| python.ty)
                 .and_then(|ty| ty.disable_language_services)
                 .unwrap_or_default(),
+            diagnostic_mode: self.diagnostic_mode.unwrap_or_default(),
         }
     }
 }