fix(lsp): debounce diagnostics after rapid changes (#10770)

ematipico · web-flow · commit dd1429c604f5 · 2026-06-29T08:59:40.000+01:00
diff --git a/.changeset/six-wasps-do.md b/.changeset/six-wasps-do.md
@@ -0,0 +1,5 @@
+---
+"@biomejs/biome": patch
+---
+
+Improved the Biome Language Server DX by orchestrating certain operations, so that they won't block the editor during typing. This improvement is more visible in large documents.
diff --git a/crates/biome_lsp/Cargo.toml b/crates/biome_lsp/Cargo.toml
@@ -37,7 +37,7 @@ parking_lot          = { workspace = true }
 rustc-hash           = { workspace = true }
 serde                = { workspace = true, features = ["derive"] }
 serde_json           = { workspace = true }
-tokio                = { workspace = true, features = ["io-std", "rt"] }
+tokio                = { workspace = true, features = ["io-std", "rt", "time"] }
 tower-lsp-server     = { workspace = true }
 tracing              = { workspace = true, features = ["attributes"] }
 url                  = { workspace = true }
diff --git a/crates/biome_lsp/src/handlers/text_document.rs b/crates/biome_lsp/src/handlers/text_document.rs
@@ -71,9 +71,7 @@ pub(crate) async fn did_open(
 
     session.insert_document(url.clone(), doc);
 
-    if let Err(err) = session.update_diagnostics(url).await {
-        error!("Failed to update diagnostics: {}", err);
-    }
+    session.schedule_diagnostics(url, version);
 
     Ok(())
 }
@@ -186,7 +184,7 @@ fn resolve_workspace_base_path(session: &Session, project_path: &Utf8Path) -> Ut
 /// Handler for `textDocument/didChange` LSP notification
 #[tracing::instrument(level = "debug", skip_all, fields(url = field::display(&params.text_document.uri.as_str()), version = params.text_document.version), err)]
 pub(crate) async fn did_change(
-    session: &Session,
+    session: &Arc<Session>,
     params: lsp::DidChangeTextDocumentParams,
 ) -> Result<(), LspError> {
     let url = params.text_document.uri;
@@ -234,9 +232,7 @@ pub(crate) async fn did_change(
         editor_features: None,
     })?;
 
-    if let Err(err) = session.update_diagnostics(url).await {
-        error!("Failed to update diagnostics: {}", err);
-    }
+    session.schedule_diagnostics(url, version);
 
     Ok(())
 }
@@ -287,6 +283,7 @@ pub(crate) async fn did_close(
     params: lsp::DidCloseTextDocumentParams,
 ) -> Result<(), LspError> {
     let uri = params.text_document.uri;
+    session.close_diagnostics(&uri);
     let path = session.file_path(&uri)?;
     let Some(project_key) = session.remove_document(&uri) else {
         debug!("Document wasn't open: {}", uri.as_str());
diff --git a/crates/biome_lsp/src/server.tests.rs b/crates/biome_lsp/src/server.tests.rs
@@ -122,6 +122,14 @@ fn create_document_content_change_event() -> Vec<TextDocumentContentChangeEvent>
     ]
 }
 
+fn full_document_change(text: impl Into<String>) -> Vec<TextDocumentContentChangeEvent> {
+    vec![TextDocumentContentChangeEvent {
+        range: None,
+        range_length: None,
+        text: text.into(),
+    }]
+}
+
 const EXPECTED_CST: &str = "0: JS_MODULE@0..57
   0: (empty)
   1: (empty)
@@ -566,6 +574,88 @@ async fn pull_diagnostics() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+async fn debounces_diagnostics_after_rapid_changes() -> Result<()> {
+    let factory = ServerFactory::default();
+    let (service, client) = factory.create().into_inner();
+    let (stream, sink) = client.split();
+    let mut server = Server::new(service);
+
+    let (sender, mut receiver) = channel(CHANNEL_BUFFER_SIZE);
+    let reader = tokio::spawn(client_handler(stream, sink, sender));
+
+    server.initialize().await?;
+    server.initialized().await?;
+
+    server.open_document("const a = 1; a = 2;").await?;
+    let _ = wait_for_notification(&mut receiver, |n| n.is_publish_diagnostics()).await;
+
+    server
+        .change_document(1, full_document_change("const b = 1; b = 2;"))
+        .await?;
+    server
+        .change_document(2, full_document_change("const c = 1; c = 2;"))
+        .await?;
+
+    let notification = wait_for_notification(&mut receiver, |n| n.is_publish_diagnostics()).await;
+    let Some(ServerNotification::PublishDiagnostics(params)) = notification else {
+        panic!("expected publishDiagnostics notification");
+    };
+
+    assert_eq!(params.version, Some(2));
+
+    server.close_document().await?;
+
+    server.shutdown().await?;
+    reader.abort();
+
+    Ok(())
+}
+
+#[tokio::test]
+async fn does_not_publish_debounced_diagnostics_after_close() -> Result<()> {
+    let factory = ServerFactory::default();
+    let (service, client) = factory.create().into_inner();
+    let (stream, sink) = client.split();
+    let mut server = Server::new(service);
+
+    let (sender, mut receiver) = channel(CHANNEL_BUFFER_SIZE);
+    let reader = tokio::spawn(client_handler(stream, sink, sender));
+
+    server.initialize().await?;
+    server.initialized().await?;
+
+    server.open_document("const a = 1; a = 2;").await?;
+    let _ = wait_for_notification(&mut receiver, |n| n.is_publish_diagnostics()).await;
+
+    server
+        .change_document(1, full_document_change("const b = 1; b = 2;"))
+        .await?;
+    server.close_document().await?;
+
+    let notification = wait_for_notification(&mut receiver, |n| n.is_publish_diagnostics()).await;
+    assert_eq!(
+        notification,
+        Some(ServerNotification::PublishDiagnostics(
+            PublishDiagnosticsParams {
+                uri: uri!("document.js"),
+                version: None,
+                diagnostics: vec![],
+            }
+        ))
+    );
+
+    wait_for_no_notification(&mut receiver, Duration::from_millis(750), |n| {
+        n.is_publish_diagnostics()
+    })
+    .await;
+
+    server.shutdown().await?;
+    reader.abort();
+
+    Ok(())
+}
+
 #[tokio::test]
 async fn pull_diagnostics_of_syntax_rules() -> Result<()> {
     let factory = ServerFactory::default();
diff --git a/crates/biome_lsp/src/server_test_utils.rs b/crates/biome_lsp/src/server_test_utils.rs
@@ -432,6 +432,22 @@ pub(crate) async fn wait_for_notification(
     }
 }
 
+pub(crate) async fn wait_for_no_notification(
+    receiver: &mut (impl Stream<Item = ServerNotification> + Unpin),
+    duration: Duration,
+    check: impl Fn(&ServerNotification) -> bool,
+) {
+    loop {
+        match tokio::time::timeout(duration, receiver.next()).await {
+            Ok(Some(notification)) if check(&notification) => {
+                panic!("unexpected server notification: {notification:?}");
+            }
+            Ok(Some(_)) => {}
+            Ok(None) | Err(_) => return,
+        }
+    }
+}
+
 /// Basic handler for requests and notifications coming from the server for tests
 pub(crate) async fn client_handler<I, O>(
     stream: I,
diff --git a/crates/biome_lsp/src/session.rs b/crates/biome_lsp/src/session.rs

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@biomejs/biome": patch
 +---
++
 +Improved the Biome Language Server DX by orchestrating certain operations, so that they won't block the editor during typing. This improvement is more visible in large documents.