Implement PeekDocumentsRequest and update ShowDocumentRequest.

-------------------------------------------------------------------------------

This implements an LSP Extension `PeekDocumentsRequest` to let `ExpandMacroCommand` to open the macro expansions in a "peeked" editor window.
For this to work, the client has to pass "workspace/peekDocuments" enabled to `ClientCapabilities.experimental` and the client should handle the `PeekDocumentsRequest` and show the expansions in a "peeked" editor window.

PR to support the above capability in the "Swift for VS Code" Extension: swiftlang/vscode-swift#945
The "Swift for VS Code" extension cannot send the client capability, so it instead passes the same through `initializationOptions` in the `InitializeRequest`.

For editors which doesn't support this capability, `sourcekit-lsp` sends a `ShowDocumentRequest`.
The `ShowDocumentRequest` is updated to show all the macro expansions in a single generated file. Moreover, its folder structure is updated to use hex string of MD5 hash of concatenation of buffer names of expansions.

Fixes swiftlang/vscode-swift#564
Fixes #1498 ( rdar://130207754 )

Author: lokesh-tr

Documentation/LSP Extensions.md

@@ -436,3 +436,40 @@ Users should not need to rely on this request. The index should always be update
 ```ts
 export interface TriggerReindexParams {}
 ```
+
+## `workspace/peekDocuments`
+
+Request from the server to the client to show the given documents in a "peeked" editor.
+
+This request is handled by the client to show the given documents in a "peeked" editor (i.e. inline with / inside the editor canvas).
+
+It requires the experimental client capability `"workspace/peekDocuments"` to use.
+
+- params: `PeekDocumentsParams`
+- result: `PeekDocumentsResult`
+
+```ts
+export interface PeekDocumentsParams {
+  /**
+   * The `DocumentUri` of the text document in which to show the "peeked" editor
+   */
+  uri: DocumentUri;
+
+  /**
+   * The `Position` in the given text document in which to show the "peeked editor"
+   */
+  position: Position;
+
+  /**
+   * An array `DocumentUri` of the documents to appear inside the "peeked" editor
+   */
+  locations: DocumentUri[];
+}
+
+/**
+ * Response to indicate the `success` of the `PeekDocumentsRequest`
+ */
+export interface PeekDocumentsResult {
+  success: boolean;
+}
+```

Package.swift

@@ -380,6 +380,7 @@ let package = Package(
         "SwiftExtensions",
         .product(name: "IndexStoreDB", package: "indexstore-db"),
         .product(name: "SwiftBasicFormat", package: "swift-syntax"),
+        .product(name: "Crypto", package: "swift-crypto"),
         .product(name: "SwiftDiagnostics", package: "swift-syntax"),
         .product(name: "SwiftIDEUtils", package: "swift-syntax"),
         .product(name: "SwiftParser", package: "swift-syntax"),

Sources/LanguageServerProtocol/CMakeLists.txt

@@ -66,6 +66,7 @@ add_library(LanguageServerProtocol STATIC
   Requests/InlineValueRequest.swift
   Requests/LinkedEditingRangeRequest.swift
   Requests/MonikersRequest.swift
+  Requests/PeekDocumentsRequest.swift
   Requests/PollIndexRequest.swift
   Requests/PrepareRenameRequest.swift
   Requests/ReferencesRequest.swift

Sources/LanguageServerProtocol/Messages.swift

@@ -58,6 +58,7 @@ public let builtinRequests: [_RequestType.Type] = [
   InlineValueRequest.self,
   LinkedEditingRangeRequest.self,
   MonikersRequest.self,
+  PeekDocumentsRequest.self,
   PollIndexRequest.self,
   PrepareRenameRequest.self,
   ReferencesRequest.self,

Sources/LanguageServerProtocol/Requests/PeekDocumentsRequest.swift

@@ -0,0 +1,57 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2024 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
+//
+//===----------------------------------------------------------------------===//
+
+/// Request from the server to the client to show the given documents in a "peeked" editor **(LSP Extension)**
+///
+/// This request is handled by the client to show the given documents in a
+/// "peeked" editor (i.e. inline with / inside the editor canvas). This is
+/// similar to VS Code's built-in "editor.action.peekLocations" command.
+///
+/// - Parameters:
+///   - uri: The DocumentURI of the text document in which to show the "peeked" editor
+///   - position: The position in the given text document in which to show the "peeked editor"
+///   - locations: The DocumentURIs of documents to appear inside the "peeked" editor
+///
+/// - Returns: `PeekDocumentsResponse` which indicates the `success` of the request.
+///
+/// ### LSP Extension
+///
+/// This request is an extension to LSP supported by SourceKit-LSP.
+/// It requires the experimental client capability `"workspace/peekDocuments"` to use.
+/// It also needs the client to handle the request and present the "peeked" editor.
+public struct PeekDocumentsRequest: RequestType {
+  public static let method: String = "workspace/peekDocuments"
+  public typealias Response = PeekDocumentsResponse
+
+  public var uri: DocumentURI
+  public var position: Position
+  public var locations: [DocumentURI]
+
+  public init(
+    uri: DocumentURI,
+    position: Position,
+    locations: [DocumentURI]
+  ) {
+    self.uri = uri
+    self.position = position
+    self.locations = locations
+  }
+}
+
+/// Response to indicate the `success` of the `PeekDocumentsRequest`
+public struct PeekDocumentsResponse: ResponseType {
+  public var success: Bool
+
+  public init(success: Bool) {
+    self.success = success
+  }
+}

Sources/LanguageServerProtocol/SupportTypes/WorkspaceEdit.swift

@@ -303,35 +303,3 @@ public struct DeleteFile: Codable, Hashable, Sendable {
     try container.encodeIfPresent(self.annotationId, forKey: .annotationId)
   }
 }
-
-extension WorkspaceEdit: LSPAnyCodable {
-  public init?(fromLSPDictionary dictionary: [String: LSPAny]) {
-    guard case .dictionary(let lspDict) = dictionary[CodingKeys.changes.stringValue] else {
-      return nil
-    }
-    var dictionary = [DocumentURI: [TextEdit]]()
-    for (key, value) in lspDict {
-      guard
-        let uri = try? DocumentURI(string: key),
-        let edits = [TextEdit](fromLSPArray: value)
-      else {
-        return nil
-      }
-      dictionary[uri] = edits
-    }
-    self.changes = dictionary
-  }
-
-  public func encodeToLSPAny() -> LSPAny {
-    guard let changes = changes else {
-      return nil
-    }
-    let values = changes.map {
-      ($0.key.stringValue, $0.value.encodeToLSPAny())
-    }
-    let dictionary = Dictionary(uniqueKeysWithValues: values)
-    return .dictionary([
-      CodingKeys.changes.stringValue: .dictionary(dictionary)
-    ])
-  }
-}

Sources/SourceKitLSP/CMakeLists.txt

@@ -47,7 +47,7 @@ target_sources(SourceKitLSP PRIVATE
   Swift/FoldingRange.swift
   Swift/MacroExpansion.swift
   Swift/OpenInterface.swift
-  Swift/Refactoring.swift
+  Swift/RefactoringResponse.swift
   Swift/RefactoringEdit.swift
   Swift/RefactorCommand.swift
   Swift/RelatedIdentifiers.swift

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -956,7 +956,25 @@ extension SourceKitLSPServer {
   }
 
   func initialize(_ req: InitializeRequest) async throws -> InitializeResult {
-    capabilityRegistry = CapabilityRegistry(clientCapabilities: req.capabilities)
+    // If the client can handle `PeekDocumentsRequest`, they can enable the
+    // experimental client capability `"workspace/peekDocuments"` through the `req.capabilities.experimental`.
+    //
+    // The below is a workaround for the vscode-swift extension since it cannot set client capabilities.
+    // It passes "workspace/peekDocuments" through the `initializationOptions`.
+    var clientCapabilities = req.capabilities
+    if case .dictionary(let initializationOptions) = req.initializationOptions,
+      let peekDocuments = initializationOptions["workspace/peekDocuments"]
+    {
+      if case .dictionary(var experimentalCapabilities) = clientCapabilities.experimental {
+        experimentalCapabilities["workspace/peekDocuments"] = peekDocuments
+        clientCapabilities.experimental = .dictionary(experimentalCapabilities)
+      } else {
+        clientCapabilities.experimental = .dictionary(["workspace/peekDocuments": peekDocuments])
+      }
+    }
+
+    capabilityRegistry = CapabilityRegistry(clientCapabilities: clientCapabilities)
+
     self.options = SourceKitLSPOptions.merging(
       base: self.options,
       override: orLog("Parsing SourceKitLSPOptions", { try SourceKitLSPOptions(fromLSPAny: req.initializationOptions) })

Sources/SourceKitLSP/Swift/MacroExpansion.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
+import Crypto
 import Foundation
 import LSPLogging
 import LanguageServerProtocol
@@ -46,17 +47,15 @@ struct MacroExpansion: RefactoringResponse {
 extension SwiftLanguageService {
   /// Handles the `ExpandMacroCommand`.
   ///
-  /// Makes a request to sourcekitd and wraps the result into a `MacroExpansion`
-  /// and then makes a `ShowDocumentRequest` to the client side for each
-  /// expansion to be displayed.
+  /// Makes a `PeekDocumentsRequest` or `ShowDocumentRequest`, containing the
+  /// location of each macro expansion, to the client depending on whether the
+  /// client supports the `experimental["workspace/peekDocuments"]` capability.
   ///
   /// - Parameters:
   ///   - expandMacroCommand: The `ExpandMacroCommand` that triggered this request.
-  ///
-  /// - Returns: A `[RefactoringEdit]` with the necessary edits and buffer name as a `LSPAny`
   func expandMacro(
     _ expandMacroCommand: ExpandMacroCommand
-  ) async throws -> LSPAny {
+  ) async throws {
     guard let sourceKitLSPServer else {
       // `SourceKitLSPServer` has been destructed. We are tearing down the
       // language server. Nothing left to do.
@@ -69,6 +68,10 @@ extension SwiftLanguageService {
 
     let expansion = try await self.refactoring(expandMacroCommand)
 
+    var completeExpansionFileContent = ""
+    var completeExpansionDirectoryName = ""
+
+    var macroExpansionFilePaths: [URL] = []
     for macroEdit in expansion.edits {
       if let bufferName = macroEdit.bufferName {
         // buffer name without ".swift"
@@ -79,6 +82,9 @@ extension SwiftLanguageService {
 
         let macroExpansionBufferDirectoryURL = self.generatedMacroExpansionsPath
           .appendingPathComponent(macroExpansionBufferDirectoryName)
+
+        completeExpansionDirectoryName += "\(bufferName)-"
+
         do {
           try FileManager.default.createDirectory(
             at: macroExpansionBufferDirectoryURL,
@@ -111,22 +117,95 @@ extension SwiftLanguageService {
           )
         }
 
-        Task {
-          let req = ShowDocumentRequest(uri: DocumentURI(macroExpansionFilePath))
+        macroExpansionFilePaths.append(macroExpansionFilePath)
 
-          let response = await orLog("Sending ShowDocumentRequest to Client") {
-            try await sourceKitLSPServer.sendRequestToClient(req)
-          }
+        let editContent =
+          """
+          // \(sourceFileURL.lastPathComponent) @ \(macroEdit.range.lowerBound.line + 1):\(macroEdit.range.lowerBound.utf16index + 1) - \(macroEdit.range.upperBound.line + 1):\(macroEdit.range.upperBound.utf16index + 1)
+          \(macroEdit.newText)
 
-          if let response, !response.success {
-            logger.error("client refused to show document for \(expansion.title, privacy: .public)")
-          }
-        }
+
+          """
+        completeExpansionFileContent += editContent
       } else if !macroEdit.newText.isEmpty {
         logger.fault("Unable to retrieve some parts of macro expansion")
       }
     }
 
-    return expansion.edits.encodeToLSPAny()
+    // removes superfluous newline
+    if completeExpansionFileContent.hasSuffix("\n\n") {
+      completeExpansionFileContent.removeLast()
+    }
+
+    if completeExpansionDirectoryName.hasSuffix("-") {
+      completeExpansionDirectoryName.removeLast()
+    }
+
+    var completeExpansionFilePath =
+      self.generatedMacroExpansionsPath.appendingPathComponent(
+        Insecure.MD5.hash(
+          data: Data(completeExpansionDirectoryName.utf8)
+        )
+        .map { String(format: "%02hhx", $0) }  // maps each byte of the hash to its hex equivalent `String`
+        .joined()
+      )
+
+    do {
+      try FileManager.default.createDirectory(
+        at: completeExpansionFilePath,
+        withIntermediateDirectories: true
+      )
+    } catch {
+      throw ResponseError.unknown(
+        "Failed to create directory for complete macro expansion at path: \(completeExpansionFilePath.path)"
+      )
+    }
+
+    completeExpansionFilePath =
+      completeExpansionFilePath.appendingPathComponent(sourceFileURL.lastPathComponent)
+    do {
+      try completeExpansionFileContent.write(to: completeExpansionFilePath, atomically: true, encoding: .utf8)
+    } catch {
+      throw ResponseError.unknown(
+        "Unable to write complete macro expansion to file path: \"\(completeExpansionFilePath.path)\""
+      )
+    }
+
+    let completeMacroExpansionFilePath = completeExpansionFilePath
+    let expansionURIs = macroExpansionFilePaths.map {
+      return DocumentURI($0)
+    }
+
+    if case .dictionary(let experimentalCapabilities) = self.capabilityRegistry.clientCapabilities.experimental,
+      case .bool(true) = experimentalCapabilities["workspace/peekDocuments"]
+    {
+      Task {
+        let req = PeekDocumentsRequest(
+          uri: expandMacroCommand.textDocument.uri,
+          position: expandMacroCommand.positionRange.lowerBound,
+          locations: expansionURIs
+        )
+
+        let response = await orLog("Sending PeekDocumentsRequest to Client") {
+          try await sourceKitLSPServer.sendRequestToClient(req)
+        }
+
+        if let response, !response.success {
+          logger.error("client refused to peek macro")
+        }
+      }
+    } else {
+      Task {
+        let req = ShowDocumentRequest(uri: DocumentURI(completeMacroExpansionFilePath))
+
+        let response = await orLog("Sending ShowDocumentRequest to Client") {
+          try await sourceKitLSPServer.sendRequestToClient(req)
+        }
+
+        if let response, !response.success {
+          logger.error("client refused to show document for macro expansion")
+        }
+      }
+    }
   }
 }

Sources/SourceKitLSP/Swift/Refactoring.swift renamed to Sources/SourceKitLSP/Swift/RefactoringResponse.swift

@@ -33,7 +33,7 @@ extension RefactoringResponse {
       return nil
     }
 
-    var refactoringEdits = [RefactoringEdit]()
+    var refactoringEdits: [RefactoringEdit] = []
 
     categorizedEdits.forEach { _, categorizedEdit in
       guard let edits: SKDResponseArray = categorizedEdit[keys.edits] else {