A couple refinements to the window/didChangeActiveDocument notification

- Clarify that this must only be called with documents that are open in SourceKit-LSP and add a check for that.
- Allow sending `null` to indicate that no SourceKit-LSP document is currently active.
- Cancel preparation tasks for other workspaces that don’t contain the currently active document.

Author: ahoppen

Contributor Documentation/LSP Extensions.md

@@ -438,6 +438,8 @@ export interface DocumentTestsParams {
 
 New notification from the client to the server, telling SourceKit-LSP which document is the currently active primary document.
 
+This notification should only be called for documents that the editor has opened in SourceKit-LSP using the `textDocument/didOpen` notification.
+
 By default, SourceKit-LSP infers the currently active editor document from the last document that received a request.
 If the client supports active reporting of the currently active document, it should check for the
 `window/didChangeActiveDocument` experimental server capability. If that capability is present, it should respond with
@@ -449,9 +451,12 @@ active document changes.
 ```ts
 export interface DidChangeActiveDocumentParams {
   /**
-   * The document that is being displayed in the active editor.
+   * The document that is being displayed in the active editor or `null` to indicate that either no document is active
+   * or that the currently open document is not handled by SourceKit-LSP.
    */
-  textDocument: TextDocumentIdentifier;
+  textDocument?: TextDocumentIdentifier;
+}
+```
 
 ## `window/logMessage`
 

Sources/LanguageServerProtocol/Notifications/DidChangeActiveDocumentNotification.swift

@@ -13,10 +13,11 @@
 public struct DidChangeActiveDocumentNotification: NotificationType {
   public static let method: String = "window/didChangeActiveDocument"
 
-  /// The document that is being displayed in the active editor.
-  public var textDocument: TextDocumentIdentifier
+  /// The document that is being displayed in the active editor  or `null` to indicate that either no document is active
+  /// or that the currently open document is not handled by SourceKit-LSP.
+  public var textDocument: TextDocumentIdentifier?
 
-  public init(textDocument: TextDocumentIdentifier) {
+  public init(textDocument: TextDocumentIdentifier?) {
     self.textDocument = textDocument
   }
 }

Sources/SemanticIndex/SemanticIndexManager.swift

@@ -471,15 +471,8 @@ package final actor SemanticIndexManager {
         }
       }
     }
-    if let inProgressPrepareForEditorTask {
-      // Cancel the in progress prepare for editor task to indicate that we are no longer interested in it.
-      // This will cancel the preparation of `inProgressPrepareForEditorTask`'s target if it hasn't started yet.
-      // (see comment at the end of `SemanticIndexManager.prepare`).
-      logger.debug(
-        "Marking preparation of \(inProgressPrepareForEditorTask.document) as no longer relevant because \(uri) was opened"
-      )
-      inProgressPrepareForEditorTask.task.cancel()
-    }
+
+    markPreparationForEditorFunctionalityTaskAsIrrelevant()
     inProgressPrepareForEditorTask = InProgressPrepareForEditorTask(
       id: id,
       document: uri,
@@ -488,6 +481,18 @@ package final actor SemanticIndexManager {
     self.indexProgressStatusDidChange()
   }
 
+  /// If there is an in-progress prepare for editor task, cancel it to indicate that we are no longer interested in it.
+  /// This will cancel the preparation of `inProgressPrepareForEditorTask`'s target if it hasn't started yet. If the
+  /// preparation has already started, we don't cancel it to guarantee forward progress (see comment at the end of
+  /// `SemanticIndexManager.prepare`).
+  package func markPreparationForEditorFunctionalityTaskAsIrrelevant() {
+    guard let inProgressPrepareForEditorTask else {
+      return
+    }
+    logger.debug("Marking preparation of \(inProgressPrepareForEditorTask.document) as no longer relevant")
+    inProgressPrepareForEditorTask.task.cancel()
+  }
+
   /// Prepare the target that the given file is in, building all modules that the file depends on. Returns when
   /// preparation has finished.
   ///

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -1278,8 +1278,8 @@ extension SourceKitLSPServer {
       )
       return
     }
-    await self.clientInteractedWithDocument(uri)
     await openDocument(notification, workspace: workspace)
+    await self.clientInteractedWithDocument(uri)
   }
 
   private func openDocument(_ notification: DidOpenTextDocumentNotification, workspace: Workspace) async {
@@ -1403,9 +1403,22 @@ extension SourceKitLSPServer {
   }
 
   func didChangeActiveDocument(_ notification: DidChangeActiveDocumentNotification) async {
-    let workspace = await self.workspaceForDocument(uri: notification.textDocument.uri)
-    await workspace?.semanticIndexManager?
-      .schedulePreparationForEditorFunctionality(of: notification.textDocument.uri)
+    guard let activeDocument = notification.textDocument?.uri else {
+      // The client no longer has a SourceKit-LSP document open. Mark in-progress preparations as irrelevant to cancel
+      // them if they haven't started yet.
+      for workspace in workspaces {
+        await workspace.semanticIndexManager?.markPreparationForEditorFunctionalityTaskAsIrrelevant()
+      }
+      return
+    }
+    let documentWorkspace = await self.workspaceForDocument(uri: activeDocument)
+    for workspace in workspaces {
+      if workspace === documentWorkspace {
+        await workspace.semanticIndexManager?.schedulePreparationForEditorFunctionality(of: activeDocument)
+      } else {
+        await workspace.semanticIndexManager?.markPreparationForEditorFunctionalityTaskAsIrrelevant()
+      }
+    }
   }
 
   func willSaveDocument(