Generalize PollIndexRequest and BarrierRequest into a single SynchronizeRequest

This new request also allows us to wait for build system updates without waiting for background indexing to finish.

Author: ahoppen

Contributor Documentation/LSP Extensions.md

@@ -546,20 +546,6 @@ export interface StructuredLogEnd {
 }
 ```
 
-## `workspace/_pollIndex`
-
-New request to wait until the index is up-to-date.
-
-> [!IMPORTANT]
-> This request is experimental and may be modified or removed in future versions of SourceKit-LSP without notice. Do not rely on it.
-
-- params: `PollIndexParams`
-- result: `void`
-
-```ts
-export interface PollIndexParams {}
-```
-
 ## `workspace/_setOptions`
 
 New request to modify runtime options of SourceKit-LSP.
@@ -678,6 +664,33 @@ export interface SourceKitOptionsResult {
 }
 ```
 
+## `workspace/_synchronize`
+
+New request from the client to the server to wait for SourceKit-LSP to handle all ongoing requests and, optionally, wait for background activity to finish.
+
+> [!IMPORTANT]
+> This request is experimental, guarded behind the `synchronize-request` experimental feature and may be modified or removed in future versions of SourceKit-LSP without notice. Do not rely on it.
+
+- params: `SynchronizeParams`
+- result: `void`
+
+```ts
+export interface SynchronizeParams {
+  /**
+   * Wait for the build server to have an up-to-date build graph by sending a `workspace/waitForBuildSystemUpdates` to 
+   * it.
+   */
+  buildServerUpdates?: bool
+
+  /**
+   * Wait for background indexing to finish and all index unit files to be loaded into indexstore-db.
+   * 
+   * Implies `buildServerUpdates = true`.
+   */
+  index?: bool
+}
+```
+
 ## `workspace/_outputPaths`
 
 New request from the client to the server to retrieve the output paths of a target (see the `buildTarget/outputPaths` BSP request).

Documentation/Configuration File.md

@@ -54,7 +54,7 @@ The structure of the file is currently not guaranteed to be stable. Options may
   - `noLazy`: Prepare a target without generating object files but do not do lazy type checking and function body skipping. This uses SwiftPM's `--experimental-prepare-for-indexing-no-lazy` flag.
   - `enabled`: Prepare a target without generating object files.
 - `cancelTextDocumentRequestsOnEditAndClose: boolean`: Whether sending a `textDocument/didChange` or `textDocument/didClose` notification for a document should cancel all pending requests for that document.
-- `experimentalFeatures: ("on-type-formatting"|"set-options-request"|"sourcekit-options-request"|"is-indexing-request"|"structured-logs"|"output-paths-request")[]`: Experimental features that are enabled.
+- `experimentalFeatures: ("on-type-formatting"|"structured-logs")[]`: Experimental features that are enabled.
 - `swiftPublishDiagnosticsDebounceDuration: number`: The time that `SwiftLanguageService` should wait after an edit before starting to compute diagnostics and sending a `PublishDiagnosticsNotification`.
 - `workDoneProgressDebounceDuration: number`: When a task is started that should be displayed to the client as a work done progress, how many milliseconds to wait before actually starting the work done progress. This prevents flickering of the work done progress in the client for short-lived index tasks which end within this duration.
 - `sourcekitdRequestTimeout: number`: The maximum duration that a sourcekitd request should be allowed to execute before being declared as timed out. In general, editors should cancel requests that they are no longer interested in, but in case editors don't cancel requests, this ensures that a long-running non-cancelled request is not blocking sourcekitd and thus most semantic functionality. In particular, VS Code does not cancel the semantic tokens request, which can cause a long-running AST build that blocks sourcekitd.

SourceKitLSPDevUtils/Sources/ConfigSchemaGen/OptionSchema.swift

@@ -150,7 +150,7 @@ struct OptionSchemaContext {
       guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
         return []
       }
-      return try caseDecl.elements.map {
+      return try caseDecl.elements.compactMap {
         guard $0.parameterClause == nil else {
           throw ConfigSchemaGenError("Associated values in enum cases are not supported: \(caseDecl)")
         }
@@ -168,7 +168,11 @@ struct OptionSchemaContext {
         } else {
           name = $0.name.text
         }
-        return OptionTypeSchama.Case(name: name, description: Self.extractDocComment(caseDecl.leadingTrivia))
+        let description = Self.extractDocComment(caseDecl.leadingTrivia)
+        if description?.contains("- Note: Internal option") ?? false {
+          return nil
+        }
+        return OptionTypeSchama.Case(name: name, description: description)
       }
     }
     let typeName = node.name.text

Sources/Diagnose/IndexCommand.swift

@@ -103,7 +103,7 @@ package struct IndexCommand: AsyncParsableCommand {
       messageHandler: messageHandler
     )
     let start = ContinuousClock.now
-    _ = try await inProcessClient.send(PollIndexRequest())
+    _ = try await inProcessClient.send(SynchronizeRequest(index: true))
     print("Indexing finished in \(start.duration(to: .now))")
     if await messageHandler.hasSeenError {
       throw ExitCode(1)

Sources/LanguageServerProtocol/CMakeLists.txt

@@ -27,7 +27,6 @@ add_library(LanguageServerProtocol STATIC
   Notifications/WorkDoneProgress.swift
 
   Requests/ApplyEditRequest.swift
-  Requests/BarrierRequest.swift
   Requests/CallHierarchyIncomingCallsRequest.swift
   Requests/CallHierarchyOutgoingCallsRequest.swift
   Requests/CallHierarchyPrepareRequest.swift
@@ -72,7 +71,6 @@ add_library(LanguageServerProtocol STATIC
   Requests/MonikersRequest.swift
   Requests/OutputPathsRequest.swift
   Requests/PeekDocumentsRequest.swift
-  Requests/PollIndexRequest.swift
   Requests/PrepareRenameRequest.swift
   Requests/ReferencesRequest.swift
   Requests/RegisterCapabilityRequest.swift
@@ -85,6 +83,7 @@ add_library(LanguageServerProtocol STATIC
   Requests/SignatureHelpRequest.swift
   Requests/SourceKitOptionsRequest.swift
   Requests/SymbolInfoRequest.swift
+  Requests/SynchronizeRequest.swift
   Requests/TriggerReindexRequest.swift
   Requests/TypeDefinitionRequest.swift
   Requests/TypeHierarchyPrepareRequest.swift

Sources/LanguageServerProtocol/Messages.swift

@@ -17,7 +17,6 @@
 /// `MessageRegistry._register()` which allows you to avoid bloating the real server implementation.
 public let builtinRequests: [_RequestType.Type] = [
   ApplyEditRequest.self,
-  BarrierRequest.self,
   CallHierarchyIncomingCallsRequest.self,
   CallHierarchyOutgoingCallsRequest.self,
   CallHierarchyPrepareRequest.self,
@@ -63,7 +62,7 @@ public let builtinRequests: [_RequestType.Type] = [
   MonikersRequest.self,
   OutputPathsRequest.self,
   PeekDocumentsRequest.self,
-  PollIndexRequest.self,
+  SynchronizeRequest.self,
   PrepareRenameRequest.self,
   ReferencesRequest.self,
   RegisterCapabilityRequest.self,

Sources/LanguageServerProtocol/Requests/BarrierRequest.swift

@@ -0,0 +1,33 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2019 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+/// Wait for SourceKit-LSP to handle all ongoing requests and, optionally, wait for background activity to finish.
+///
+/// **LSP Extension, For Testing**.
+public struct SynchronizeRequest: RequestType {
+  public static let method: String = "workspace/_synchronize"
+  public typealias Response = VoidResponse
+
+  /// Wait for the build server to have an up-to-date build graph by sending a `workspace/waitForBuildSystemUpdates` to
+  /// it.
+  public var buildServerUpdates: Bool?
+
+  /// Wait for background indexing to finish and all index unit files to be loaded into indexstore-db.
+  ///
+  /// Implies `buildServerUpdates = true`.
+  public var index: Bool?
+
+  public init(buildServerUpdates: Bool? = nil, index: Bool? = nil) {
+    self.buildServerUpdates = buildServerUpdates
+    self.index = index
+  }
+}

Sources/LanguageServerProtocol/Requests/PollIndexRequest.swift

@@ -18,17 +18,30 @@ public enum ExperimentalFeature: String, Codable, Sendable, CaseIterable {
   case onTypeFormatting = "on-type-formatting"
 
   /// Enable support for the `workspace/_setOptions` request.
+  ///
+  /// - Note: Internal option
   case setOptionsRequest = "set-options-request"
 
   /// Enable the `workspace/_sourceKitOptions` request.
+  ///
+  /// - Note: Internal option
   case sourceKitOptionsRequest = "sourcekit-options-request"
 
   /// Enable the `sourceKit/_isIndexing` request.
+  ///
+  /// - Note: Internal option
   case isIndexingRequest = "is-indexing-request"
 
   /// Indicate that the client can handle the experimental `structure` field in the `window/logMessage` notification.
   case structuredLogs = "structured-logs"
 
   /// Enable the `workspace/_outputPaths` request.
+  ///
+  /// - Note: Internal option
   case outputPathsRequest = "output-paths-request"
+
+  /// Enable the `workspace/_synchronize` request.
+  ///
+  /// - Note: Internal option, for testing only
+  case synchronizeRequest = "synchronize-request"
 }