textDocument/playgrounds request

- New request that is tied to an experimental feature while [swift play](https://github.com/apple/swift-play-experimental/) is still experimental
- Add #Playground macro visitor to parse the macro expansions
- PlaygroundItem will record the id and optionally label to match detail you get from
```
$ swift play --list
Building for debugging...
Found 1 Playground
* Fibonacci/Fibonacci.swift:23 "Fibonacci"
```

Issue: #2339

Author: award999

Sources/ClangLanguageService/ClangLanguageService.swift

@@ -647,6 +647,10 @@ extension ClangLanguageService {
     return []
   }
 
+  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem] {
+    return []
+  }
+
   package func editsToRename(
     locations renameLocations: [RenameLocation],
     in snapshot: DocumentSnapshot,

Sources/LanguageServerProtocol/Messages.swift

@@ -40,6 +40,7 @@ public let builtinRequests: [_RequestType.Type] = [
   DocumentLinkRequest.self,
   DocumentLinkResolveRequest.self,
   DocumentOnTypeFormattingRequest.self,
+  DocumentPlaygroundsRequest.self,
   DocumentRangeFormattingRequest.self,
   DocumentSemanticTokensDeltaRequest.self,
   DocumentSemanticTokensRangeRequest.self,

Sources/LanguageServerProtocol/Requests/DocumentPlaygroundsRequest.swift

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 request that returns #Playground macro expansion locations within a file.
+///
+/// **(LSP Extension)**
+public struct DocumentPlaygroundsRequest: TextDocumentRequest, Hashable {
+  public static let method: String = "textDocument/playgrounds"
+  public typealias Response = [PlaygroundItem]
+
+  public var textDocument: TextDocumentIdentifier
+
+  public init(textDocument: TextDocumentIdentifier) {
+    self.textDocument = textDocument
+  }
+}

Sources/LanguageServerProtocol/SupportTypes/Location.swift

@@ -37,4 +37,11 @@ public struct Location: ResponseType, Hashable, Codable, CustomDebugStringConver
   public var debugDescription: String {
     return "\(uri):\(range.lowerBound)-\(range.upperBound)"
   }
+
+  public func encodeToLSPAny() -> LSPAny {
+    return .dictionary([
+      "uri": .string(uri.stringValue),
+      "range": range.encodeToLSPAny()
+    ])
+  }
 }

Sources/LanguageServerProtocol/SupportTypes/PlaygroundItem.swift

@@ -0,0 +1,48 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 playgrounds alongside a source file.
+public struct PlaygroundItem: 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 test.
+  public var label: String?
+
+  /// The range of the playground item in the source code.
+  public var location: Location
+
+  public init(
+    id: String,
+    label: String?,
+    location: Location,
+  ) {
+    self.id = id
+    self.label = label
+    self.location = location
+  }
+
+  public func encodeToLSPAny() -> LSPAny {
+    var dict: [String: LSPAny] = [
+      "id": .string(id),
+      "location": location.encodeToLSPAny()
+    ]
+
+    if let label {
+      dict["label"] = .string(label)
+    }
+
+    return .dictionary(dict)
+  }
+}

Sources/SourceKitLSP/LanguageService.swift

@@ -320,6 +320,11 @@ package protocol LanguageService: AnyObject, Sendable {
   /// The order of the returned tests is not defined. The results should be sorted before being returned to the editor.
   static func syntacticTestItems(in uri: DocumentURI) async -> [AnnotatedTestItem]
 
+  /// 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]
+
   /// 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.
   /// ```
@@ -527,6 +532,10 @@ 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] {
+    throw ResponseError.requestNotImplemented(DocumentOnTypeFormattingRequest.self)
+  }
+
   func canonicalDeclarationPosition(of position: Position, in uri: DocumentURI) async -> Position? {
     logger.error("\(#function) not implemented in \(Self.self) for \(uri)")
     return nil

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -813,6 +813,8 @@ extension SourceKitLSPServer: QueueBasedMessageHandler {
       await self.handleRequest(for: request, requestHandler: self.documentSymbol)
     case let request as RequestAndReply<DocumentTestsRequest>:
       await self.handleRequest(for: request, requestHandler: self.documentTests)
+    case let request as RequestAndReply<DocumentPlaygroundsRequest>:
+      await self.handleRequest(for: request, requestHandler: self.documentPlaygrounds)
     case let request as RequestAndReply<ExecuteCommandRequest>:
       await request.reply { try await executeCommand(request.params) }
     case let request as RequestAndReply<FoldingRangeRequest>:
@@ -1117,6 +1119,7 @@ extension SourceKitLSPServer {
       TriggerReindexRequest.method: .dictionary(["version": .int(1)]),
       GetReferenceDocumentRequest.method: .dictionary(["version": .int(1)]),
       DidChangeActiveDocumentNotification.method: .dictionary(["version": .int(1)]),
+      DocumentPlaygroundsRequest.method: .dictionary(["version": .int(1)]),
     ]
     for (key, value) in languageServiceRegistry.languageServices.flatMap({ $0.type.experimentalCapabilities }) {
       if let existingValue = experimentalCapabilities[key] {
@@ -1817,6 +1820,14 @@ extension SourceKitLSPServer {
     return try await languageService.documentOnTypeFormatting(req)
   }
 
+  func documentPlaygrounds(
+    _ req: DocumentPlaygroundsRequest,
+    workspace: Workspace,
+    languageService: LanguageService
+  ) async throws -> [PlaygroundItem] {
+    return try await languageService.syntacticDocumentPlaygrounds(for: req.textDocument.uri, in: workspace)
+  }
+
   func colorPresentation(
     _ req: ColorPresentationRequest,
     workspace: Workspace,

Sources/SwiftLanguageService/PlaygroundsMacro.swift

@@ -0,0 +1,130 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+package import LanguageServerProtocol
+import SKLogging
+package import SourceKitLSP
+import SwiftSyntax
+import Playgrounds
+import SwiftParser
+internal import BuildServerIntegration
+
+extension SwiftLanguageService {
+  package func syntacticDocumentPlaygrounds(for uri: DocumentURI, in workspace: Workspace) async throws -> [PlaygroundItem] {
+    let snapshot = try self.documentManager.latestSnapshot(uri)
+
+    let syntaxTree = await syntaxTreeManager.syntaxTree(for: snapshot)
+
+    try Task.checkCancellation()
+    return
+      await PlaygroundMacroFinder.find(
+        in: [Syntax(syntaxTree)],
+        workspace: workspace,
+        snapshot: snapshot,
+        range: syntaxTree.position..<syntaxTree.endPosition
+      )
+  }
+}
+
+// MARK: - PlaygroundMacroFinder
+
+final class PlaygroundMacroFinder: SyntaxAnyVisitor {
+  /// The base ID to use to generate IDs for any playgrounds found in this file.
+  private let baseID: String
+
+  /// The snapshot of the document for which we are getting playgrounds.
+  private let snapshot: DocumentSnapshot
+
+  /// Only playgrounds that intersect with this range get reported.
+  private let range: Range<AbsolutePosition>
+
+  /// Accumulating the result in here.
+  private var result: [PlaygroundItem] = []
+
+  /// Keep track of if "Playgrounds" has been imported
+  private var isPlaygroundImported: Bool = false
+
+  private init(baseID: String, snapshot: DocumentSnapshot, range: Range<AbsolutePosition>) {
+    self.baseID = baseID
+    self.snapshot = snapshot
+    self.range = range
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  /// Designated entry point for `PlaygroundMacroFinder`.
+  static func find(
+    in nodes: some Sequence<Syntax>,
+    workspace: Workspace,
+    snapshot: DocumentSnapshot,
+    range: Range<AbsolutePosition>
+  ) async -> [PlaygroundItem] {
+    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 
+    else {
+      return []
+    }
+    let visitor = PlaygroundMacroFinder(baseID: "\(moduleName)/\(baseName)", snapshot: snapshot, range: range)
+    for node in nodes {
+      visitor.walk(node)
+    }
+    return visitor.result
+  }
+
+  /// Add a playground location with the given parameters to the `result` array.
+  private func record(
+    id: String,
+    label: String?,
+    range: Range<AbsolutePosition>
+  ) {
+    if !self.range.overlaps(range) {
+      return
+    }
+    let positionRange = snapshot.absolutePositionRange(of: range)
+    let location = Location(uri: snapshot.uri, range: positionRange)
+  
+    result.append(
+      PlaygroundItem(
+        id: id,
+        label: label,
+        location: location,
+      )
+    )
+  }
+
+  override func visit(_ node: ImportPathComponentSyntax) -> SyntaxVisitorContinueKind {
+    if node.name.text == "Playgrounds" {
+      isPlaygroundImported = true
+    }
+    return .skipChildren
+  }
+
+  override func visit(_ node: MacroExpansionExprSyntax) -> SyntaxVisitorContinueKind {
+    guard isPlaygroundImported, node.macroName.text == "Playground" else {
+      return .skipChildren
+    }
+
+    let startPosition = snapshot.position(of: node.positionAfterSkippingLeadingTrivia)
+    let stringLiteral = node.arguments.first?.expression.as(StringLiteralExprSyntax.self)
+    let playgroundLabel = stringLiteral?.representedLiteralValue
+    let playgroundID = "\(baseID):\(startPosition.line + 1)"
+
+    record(
+      id: playgroundID, 
+      label: playgroundLabel,
+      range: node.positionAfterSkippingLeadingTrivia..<node.endPositionBeforeTrailingTrivia
+    )
+
+    return .skipChildren
+  }
+}