Have different playground type for workspace and document requests

Author: award999

Contributor Documentation/LSP Extensions.md

@@ -169,7 +169,7 @@ call `workspace/playgrounds` each time a document is changed.
 SourceKit-LSP will advertise `textDocument/playgrounds` in its experimental server capabilities if it supports it.
 
 - params: `DocumentPlaygroundParams`
-- result: `PlaygroundItem[]`
+- result: `DocumentPlayground[]`
 
 ```ts
 export interface DocumentPlaygroundParams {
@@ -179,14 +179,14 @@ export interface DocumentPlaygroundParams {
   textDocument: TextDocumentIdentifier;
 }
 /**
- * A `PlaygroundItem` represents an expansion of the #Playground macro, providing the editor with the
+ * A `DocumentPlayground` represents an expansion of the #Playground macro, providing the editor with the
  * location of the playground and identifiers to allow executing the playground through a "swift play" command.
  */
-export interface PlaygroundItem {
+export interface DocumentPlayground {
   /**
-   * Unique identifier for the `PlaygroundItem`. Client can run the playground by executing `swift play <id>`.
+   * Unique identifier for the `DocumentPlayground`. Client can run the playground by executing `swift play <id>`.
    * 
-   * This property is always present whether the `PlaygroundItem` has a `label` or not.
+   * This property is always present whether the `DocumentPlayground` has a `label` or not.
    *
    * Follows the format output by `swift play --list`.
    */
@@ -199,9 +199,9 @@ export interface PlaygroundItem {
   label?: string
 
   /**
-   * The location of the of where the #Playground macro expansion occured in the source code.
+   * The range where the #Playground macro expansion occured in the given document.
    */
-  location: Location
+  range: Range<Position>
 }
 ```
 
@@ -742,6 +742,54 @@ export interface PeekDocumentsResult {
 }
 ```
 
+## `workspace/playgrounds`
+
+New request for return the list of all #Playground macro expansions in the workspace.
+
+Primarily designed to allow editors to provide a list of available playgrounds in the project workspace and allow
+jumping to the locations where the #Playground macro was expanded.
+
+The request fetches the list of all macro expansions found in the workspace, returning the location, identifier, and optional label
+when available for each #Playground macro expansion. The request is intended to be used in combination with the `textDocument/playgrounds`
+request where the `workspace/playgrounds` provides the full list of playgrounds in the workspace and `textDocument/playgrounds`
+can be called after document changes. This way the editor can itself keep the list of playgrounds up to date without needing to
+call `workspace/playgrounds` each time a document is changed.
+
+SourceKit-LSP will advertise `workspace/playgrounds` in its experimental server capabilities if it supports it.
+
+- params: `DocumentPlaygroundParams`
+- result: `Playground[]`
+
+```ts
+export interface WorkspacePlaygroundParams {}
+
+/**
+ * A `Playground` represents an expansion of the #Playground macro, providing the editor with the
+ * location of the playground and identifiers to allow executing the playground through a "swift play" command.
+ */
+export interface Playground {
+  /**
+   * Unique identifier for the `Playground`. Client can run the playground by executing `swift play <id>`.
+   *
+   * This property is always present whether the `Playground` has a `label` or not.
+   *
+   * Follows the format output by `swift play --list`.
+   */
+  id: string;
+
+  /**
+   * The label that can be used as a display name for the playground. This optional property is only available
+   * for named playgrounds. For example: `#Playground("hello") { print("Hello!) }` would have a `label` of `"hello"`.
+   */
+  label?: string
+
+  /**
+   * The location of the of where the #Playground macro expansion occured in the source code.
+   */
+  location: Location
+}
+```
+
 ## `workspace/synchronize`
 
 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.

Sources/ClangLanguageService/ClangLanguageService.swift

@@ -647,7 +647,7 @@ extension ClangLanguageService {
     return []
   }
 
-  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem] {
+  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [TextDocumentPlayground] {
     return []
   }
 

Sources/LanguageServerProtocol/Requests/DocumentPlaygroundsRequest.swift

@@ -15,7 +15,7 @@
 /// **(LSP Extension)**
 public struct DocumentPlaygroundsRequest: TextDocumentRequest, Hashable {
   public static let method: String = "textDocument/playgrounds"
-  public typealias Response = [PlaygroundItem]
+  public typealias Response = [TextDocumentPlayground]
 
   public var textDocument: TextDocumentIdentifier
 

Sources/LanguageServerProtocol/SupportTypes/PlaygroundItem.swift renamed to Sources/LanguageServerProtocol/SupportTypes/Playground.swift

@@ -11,7 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 /// A playground item that can be used to identify playgrounds alongside a source file.
-public struct PlaygroundItem: ResponseType, Equatable {
+public struct Playground: ResponseType, Equatable {
   /// Identifier for the `PlaygroundItem`.
   ///
   /// This identifier uniquely identifies the playground. It can be used to run an individual playground with `swift play`.

Sources/LanguageServerProtocol/SupportTypes/TextDocumentPlayground.swift

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 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
+//
+//===----------------------------------------------------------------------===//
+
+/// A playground item that can be used to identify playground. Differs from `PlaygroundItem`
+/// by not including location which is given for `textDocument/playgrounds` request
+public struct TextDocumentPlayground: ResponseType, Equatable {
+  /// Identifier for the `PlaygroundItem`.
+  ///
+  /// This identifier uniquely identifies the playground. It can be used to run an individual playground with `swift play`.
+  public var id: String
+
+  /// Display name describing the playground.
+  public var label: String?
+
+  /// The range of the #Playground macro expansion in the given file.
+  public var range: Range<Position>
+
+  public init(
+    id: String,
+    label: String?,
+    range: Range<Position>
+  ) {
+    self.id = id
+    self.label = label
+    self.range = range
+  }
+}

Sources/SourceKitLSP/LanguageService.swift

@@ -323,7 +323,7 @@ package protocol LanguageService: AnyObject, Sendable {
   /// Syntactically scans the file at the given URL for #Playground macro expansions within it.
   ///
   /// Does not write the results to the index.
-  func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem]
+  func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [TextDocumentPlayground]
 
   /// A position that is canonical for all positions within a declaration. For example, if we have the following
   /// declaration, then all `|` markers should return the same canonical position.
@@ -532,7 +532,7 @@ package extension LanguageService {
     throw ResponseError.internalError("syntacticDocumentTests not implemented in \(Self.self) for \(uri)")
   }
 
-  func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem] {
+  func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [TextDocumentPlayground] {
     throw ResponseError.requestNotImplemented(DocumentPlaygroundsRequest.self)
   }
 

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -1824,7 +1824,7 @@ extension SourceKitLSPServer {
     _ req: DocumentPlaygroundsRequest,
     workspace: Workspace,
     languageService: LanguageService
-  ) async throws -> [PlaygroundItem] {
+  ) async throws -> [TextDocumentPlayground] {
     return try await languageService.syntacticDocumentPlaygrounds(for: req.textDocument.uri, in: workspace)
   }
 

Sources/SwiftLanguageService/PlaygroundDiscovery.swift

@@ -19,7 +19,7 @@ import SwiftParser
 internal import BuildServerIntegration
 
 extension SwiftLanguageService {
-  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem] {
+  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [TextDocumentPlayground] {
     let snapshot = try self.documentManager.latestSnapshot(uri)
 
     let syntaxTree = await syntaxTreeManager.syntaxTree(for: snapshot)
@@ -44,7 +44,7 @@ final class PlaygroundFinder: SyntaxAnyVisitor {
   private let snapshot: DocumentSnapshot
 
   /// Accumulating the result in here.
-  private var result: [PlaygroundItem] = []
+  private var result: [TextDocumentPlayground] = []
 
   /// Keep track of if "Playgrounds" has been imported
   fileprivate var isPlaygroundImported: Bool = false
@@ -60,7 +60,7 @@ final class PlaygroundFinder: SyntaxAnyVisitor {
     in node: some SyntaxProtocol,
     workspace: Workspace,
     snapshot: DocumentSnapshot
-  ) async -> [PlaygroundItem] {
+  ) async -> [TextDocumentPlayground] {
     guard let canonicalTarget = await workspace.buildServerManager.canonicalTarget(for: snapshot.uri),
       let moduleName = await workspace.buildServerManager.moduleName(for: snapshot.uri, in: canonicalTarget),
       let baseName = snapshot.uri.fileURL?.lastPathComponent 
@@ -79,13 +79,12 @@ final class PlaygroundFinder: SyntaxAnyVisitor {
     range: Range<AbsolutePosition>
   ) {
     let positionRange = snapshot.absolutePositionRange(of: range)
-    let location = Location(uri: snapshot.uri, range: positionRange)
 
     result.append(
-      PlaygroundItem(
+      TextDocumentPlayground(
         id: id,
         label: label,
-        location: location,
+        range: positionRange,
       )
     )
   }

Tests/SourceKitLSPTests/DocumentPlaygroundDiscoveryTests.swift

@@ -54,20 +54,20 @@ final class DocumentPlaygroundDiscoveryTests: XCTestCase {
     XCTAssertEqual(
       playgrounds,
       [
-        PlaygroundItem(
+        TextDocumentPlayground(
           id: "MyLibrary/MyLib.swift:7",
           label: "foo",
-          location: Location(uri: uri, range: positions["1️⃣"]..<positions["2️⃣"]),
+          range: positions["1️⃣"]..<positions["2️⃣"],
         ),
-        PlaygroundItem(
+        TextDocumentPlayground(
           id: "MyLibrary/MyLib.swift:11",
           label: nil,
-          location: Location(uri: uri, range: positions["3️⃣"]..<positions["4️⃣"]),
+          range: positions["3️⃣"]..<positions["4️⃣"],
         ),
-        PlaygroundItem(
+        TextDocumentPlayground(
           id: "MyLibrary/MyLib.swift:19",
           label: "bar",
-          location: Location(uri: uri, range: positions["5️⃣"]..<positions["6️⃣"]),
+          range: positions["5️⃣"]..<positions["6️⃣"],
         ),
       ]
     )