Add structure to the index logs

When the client supports it, communicate the structure of tasks that were stared during background indexing or by the build server to the client. If there are multiple operations happening in parallel, this allows the client to display them in separate log tracks instead of interspersing them with the emoji prefixes like we do today.

Author: ahoppen

Contributor Documentation/LSP Extensions.md

@@ -481,7 +481,7 @@ export interface DidChangeActiveDocumentParams {
 
 ## `window/logMessage`
 
-Added field:
+Added fields:
 
 ```ts
 /**
@@ -490,6 +490,60 @@ Added field:
  * Clients may ignore this parameter and add the message to the global log
  */
 logName?: string;
+
+
+/**
+ * If specified, allows grouping log messages that belong to the same originating task together instead of logging
+ * them in chronological order in which they were produced.
+ *
+ * LSP Extension guarded by the experimental `structured-logs` feature.
+ */
+structure?: StructuredLogBegin | StructuredLogReport | StructuredLogEnd;
+```
+
+With
+
+```ts
+/**
+ * Indicates the beginning of a new task that may receive updates with `StructuredLogReport` or `StructuredLogEnd`
+ * payloads.
+ */
+export interface StructuredLogBegin {
+  kind: 'begin'
+
+  /**
+   * A succinct title that can be used to describe the task that started this structured.
+   */
+  title: string;
+
+  /**
+   * A unique identifier, identifying the task this structured log message belongs to.
+   */
+  taskID: string;
+}
+
+
+/**
+ * Adds a new log message to a structured log without ending it.
+ */
+export interface StructuredLogReport {
+  /*
+   * A unique identifier, identifying the task this structured log message belongs to.
+   */
+  taskID: string;
+}
+
+/**
+ * Ends a structured log. No more `StructuredLogReport` updates should be sent for this task ID.
+ *
+ * The task ID may be re-used for new structured logs by beginning a new structured log for that task.
+ */
+export interface StructuredLogEnd {
+  /*
+   * A unique identifier, identifying the task this structured log message belongs to.
+   */
+  taskID: string;
+}
 ```
 
 ## `workspace/_pollIndex`

Documentation/Configuration File.md

@@ -53,7 +53,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")[]`: Experimental features that are enabled.
+- `experimentalFeatures: ("on-type-formatting"|"set-options-request"|"sourcekit-options-request"|"is-indexing-request"|"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.

Sources/BuildServerProtocol/Messages/OnBuildLogMessageNotification.swift

@@ -18,22 +18,23 @@ import LanguageServerProtocol
 
 /// The log message notification is sent from a server to a client to ask the client to log a particular message in its console.
 ///
-/// A `build/logMessage`` notification is similar to LSP's `window/logMessage``, except for a few additions like id and originId.
+/// A `build/logMessage`` notification is similar to LSP's `window/logMessage``.
 public struct OnBuildLogMessageNotification: NotificationType {
   public static let method: String = "build/logMessage"
 
   /// The message type.
   public var type: MessageType
 
-  /// The task id if any.
-  public var task: TaskId?
-
   /// The actual message.
   public var message: String
 
-  public init(type: MessageType, task: TaskId? = nil, message: String) {
+  /// If specified, allows grouping log messages that belong to the same originating task together instead of logging
+  /// them in chronological order in which they were produced.
+  public var structure: StructuredLogKind?
+
+  public init(type: MessageType, message: String, structure: StructuredLogKind?) {
     self.type = type
-    self.task = task
     self.message = message
+    self.structure = structure
   }
 }

Sources/BuildSystemIntegration/BuildSystemManager.swift

@@ -631,15 +631,18 @@ package actor BuildSystemManager: QueueBasedMessageHandler {
   }
 
   private func logMessage(notification: BuildServerProtocol.OnBuildLogMessageNotification) async {
-    let message =
-      if let taskID = notification.task?.id {
-        prefixMessageWithTaskEmoji(taskID: taskID, message: notification.message)
-      } else {
-        notification.message
-      }
     await connectionToClient.waitUntilInitialized()
-    connectionToClient.send(
-      LanguageServerProtocol.LogMessageNotification(type: .info, message: message, logName: "SourceKit-LSP: Indexing")
+    let type: WindowMessageType =
+      switch notification.type {
+      case .error: .error
+      case .warning: .warning
+      case .info: .info
+      case .log: .log
+      }
+    connectionToClient.logMessageToIndexLog(
+      message: notification.message,
+      type: type,
+      structure: notification.structure
     )
   }
 

Sources/BuildSystemIntegration/BuildSystemManagerDelegate.swift

@@ -53,4 +53,7 @@ package protocol BuildSystemManagerConnectionToClient: Sendable, Connection {
 
   /// Start watching for file changes with the given glob patterns.
   func watchFiles(_ fileWatchers: [FileSystemWatcher]) async
+
+  /// Log a message in the client's index log.
+  func logMessageToIndexLog(message: String, type: WindowMessageType, structure: StructuredLogKind?)
 }

Sources/BuildSystemIntegration/CMakeLists.txt

@@ -18,7 +18,6 @@ add_library(BuildSystemIntegration STATIC
   JSONCompilationDatabaseBuildSystem.swift
   LegacyBuildServerBuildSystem.swift
   MainFilesProvider.swift
-  PrefixMessageWithTaskEmoji.swift
   SplitShellCommand.swift
   SwiftPMBuildSystem.swift
   TestBuildSystem.swift)

Sources/BuildSystemIntegration/SwiftPMBuildSystem.swift

@@ -188,9 +188,23 @@ package actor SwiftPMBuildSystem: BuiltInBuildSystem {
     self.testHooks = testHooks
     self.connectionToSourceKitLSP = connectionToSourceKitLSP
 
+    // Start an open-ended log for messages that we receive during package loading. We never end this log.
+    let logTaskID = "swiftpm-log-\(UUID())"
+    connectionToSourceKitLSP.send(
+      OnBuildLogMessageNotification(
+        type: .info,
+        message: "",
+        structure: .begin(StructuredLogBegin(title: "SwiftPM log for \(projectRoot.path)", taskID: logTaskID))
+      )
+    )
+
     self.observabilitySystem = ObservabilitySystem({ scope, diagnostic in
       connectionToSourceKitLSP.send(
-        OnBuildLogMessageNotification(type: .info, task: TaskId(id: "swiftpm-log"), message: diagnostic.description)
+        OnBuildLogMessageNotification(
+          type: .info,
+          message: diagnostic.description,
+          structure: .report(StructuredLogReport(taskID: logTaskID))
+        )
       )
       logger.log(level: diagnostic.severity.asLogLevel, "SwiftPM log: \(diagnostic.description)")
     })
@@ -638,12 +652,6 @@ package actor SwiftPMBuildSystem: BuiltInBuildSystem {
     return VoidResponse()
   }
 
-  private nonisolated func logMessageToIndexLog(_ taskID: TaskId, _ message: String) {
-    connectionToSourceKitLSP.send(
-      BuildServerProtocol.OnBuildLogMessageNotification(type: .info, task: taskID, message: message)
-    )
-  }
-
   private func prepare(singleTarget target: BuildTargetIdentifier) async throws {
     if target == .forPackageManifest {
       // Nothing to prepare for package manifests.
@@ -698,15 +706,36 @@ package actor SwiftPMBuildSystem: BuiltInBuildSystem {
     let start = ContinuousClock.now
 
     let taskID: TaskId = TaskId(id: "preparation-\(preparationTaskID.fetchAndIncrement())")
-    logMessageToIndexLog(
-      taskID,
-      """
-      Preparing \(self.swiftPMTargets[target]?.name ?? target.uri.stringValue)
-      \(arguments.joined(separator: " "))
-      """
+    connectionToSourceKitLSP.send(
+      BuildServerProtocol.OnBuildLogMessageNotification(
+        type: .info,
+        message: "\(arguments.joined(separator: " "))",
+        structure: .begin(
+          StructuredLogBegin(
+            title: "Preparing \(self.swiftPMTargets[target]?.name ?? target.uri.stringValue)",
+            taskID: taskID.id
+          )
+        )
+      )
     )
-    let stdoutHandler = PipeAsStringHandler { self.logMessageToIndexLog(taskID, $0) }
-    let stderrHandler = PipeAsStringHandler { self.logMessageToIndexLog(taskID, $0) }
+    let stdoutHandler = PipeAsStringHandler { message in
+      self.connectionToSourceKitLSP.send(
+        BuildServerProtocol.OnBuildLogMessageNotification(
+          type: .info,
+          message: message,
+          structure: .report(StructuredLogReport(taskID: taskID.id))
+        )
+      )
+    }
+    let stderrHandler = PipeAsStringHandler { message in
+      self.connectionToSourceKitLSP.send(
+        BuildServerProtocol.OnBuildLogMessageNotification(
+          type: .info,
+          message: message,
+          structure: .report(StructuredLogReport(taskID: taskID.id))
+        )
+      )
+    }
 
     let result = try await Process.run(
       arguments: arguments,
@@ -717,7 +746,13 @@ package actor SwiftPMBuildSystem: BuiltInBuildSystem {
       )
     )
     let exitStatus = result.exitStatus.exhaustivelySwitchable
-    logMessageToIndexLog(taskID, "Finished with \(exitStatus.description) in \(start.duration(to: .now))")
+    self.connectionToSourceKitLSP.send(
+      BuildServerProtocol.OnBuildLogMessageNotification(
+        type: exitStatus.isSuccess ? .info : .error,
+        message: "Finished with \(exitStatus.description) in \(start.duration(to: .now))",
+        structure: .end(StructuredLogEnd(taskID: taskID.id))
+      )
+    )
     switch exitStatus {
     case .terminated(code: 0):
       break