Support swift.play in textDocument/codelens request

- New `swift.play` CodeLens support that is 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
- File must `import Playgrounds` to record the macro expansion
- The `swift-play` binary must exist in the toolchain to
- TextDocumentPlayground 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"
```
- Add LSP extension documentation for designing pending `workspace/playground` request
- Add new parsing test cases
- Update CMake files

Issue: #2339 #2343

Author: award999

Contributor Documentation/LSP Extensions.md

@@ -690,6 +690,52 @@ 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. If you want to keep the list of playgrounds up to date without needing to
+call `workspace/playgrounds` each time a document is changed, you can filter for `swift.play` CodeLens returned by the `textDocument/codelens` request.
+
+SourceKit-LSP will advertise `workspace/playgrounds` in its experimental server capabilities if it supports it.
+
+- params: `WorkspacePlaygroundParams`
+- 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/LanguageServerProtocol/CMakeLists.txt

@@ -122,6 +122,7 @@ add_library(LanguageServerProtocol STATIC
   SupportTypes/NotebookDocument.swift
   SupportTypes/NotebookDocumentChangeEvent.swift
   SupportTypes/NotebookDocumentIdentifier.swift
+  SupportTypes/Playground.swift
   SupportTypes/Position.swift
   SupportTypes/PositionEncoding.swift
   SupportTypes/ProgressToken.swift
@@ -138,6 +139,7 @@ add_library(LanguageServerProtocol STATIC
   SupportTypes/TextDocumentEdit.swift
   SupportTypes/TextDocumentIdentifier.swift
   SupportTypes/TextDocumentItem.swift
+  SupportTypes/TextDocumentPlayground.swift
   SupportTypes/TextDocumentSaveReason.swift
   SupportTypes/TextEdit.swift
   SupportTypes/Tracing.swift

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/Playground.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 Playground: ResponseType, Equatable {
+  /// Identifier for the `Playground`.
+  ///
+  /// 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 location of the #Playground macro expansion 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/LanguageServerProtocol/SupportTypes/SupportedCodeLensCommand.swift

@@ -26,4 +26,7 @@ public struct SupportedCodeLensCommand: Codable, Hashable, RawRepresentable, Sen
 
   /// Lens to debug the application
   public static let debug: Self = Self(rawValue: "swift.debug")
+
+  /// Lens to run the playground
+  public static let play: Self = Self(rawValue: "swift.play")
 }

Sources/LanguageServerProtocol/SupportTypes/TextDocumentPlayground.swift

@@ -0,0 +1,49 @@
+//===----------------------------------------------------------------------===//
+//
+// 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 `TextDocumentPlayground`
+/// by not including location which is given for `textDocument/playgrounds` request
+public struct TextDocumentPlayground: ResponseType, Equatable {
+  /// Identifier for the `TextDocumentPlayground`.
+  ///
+  /// 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
+  }
+
+  public func encodeToLSPAny() -> LSPAny {
+    var dict: [String: LSPAny] = [
+      "id": .string(id),
+      "range": range.encodeToLSPAny()
+    ]
+
+    if let label {
+      dict["label"] = .string(label)
+    }
+
+    return .dictionary(dict)
+  }
+}

Sources/SKTestSupport/SwiftPMTestProject.swift

@@ -17,7 +17,7 @@ package import SKOptions
 package import SourceKitLSP
 import SwiftExtensions
 import TSCBasic
-import ToolchainRegistry
+package import ToolchainRegistry
 import XCTest
 
 package class SwiftPMTestProject: MultiFileTestProject {
@@ -183,6 +183,7 @@ package class SwiftPMTestProject: MultiFileTestProject {
     initializationOptions: LSPAny? = nil,
     capabilities: ClientCapabilities = ClientCapabilities(),
     options: SourceKitLSPOptions? = nil,
+    toolchainRegistry: ToolchainRegistry = .forTesting,
     hooks: Hooks = Hooks(),
     enableBackgroundIndexing: Bool = false,
     usePullDiagnostics: Bool = true,
@@ -224,6 +225,7 @@ package class SwiftPMTestProject: MultiFileTestProject {
       initializationOptions: initializationOptions,
       capabilities: capabilities,
       options: options,
+      toolchainRegistry: toolchainRegistry,
       hooks: hooks,
       enableBackgroundIndexing: enableBackgroundIndexing,
       usePullDiagnostics: usePullDiagnostics,

Sources/SwiftLanguageService/CMakeLists.txt

@@ -25,6 +25,7 @@ add_library(SwiftLanguageService STATIC
   InlayHints.swift
   MacroExpansion.swift
   OpenInterface.swift
+  PlaygroundDiscovery.swift
   RefactoringEdit.swift
   RefactoringResponse.swift
   RelatedIdentifiers.swift

Sources/SwiftLanguageService/DocumentFormatting.swift

@@ -20,6 +20,7 @@ import SourceKitLSP
 import SwiftExtensions
 import SwiftParser
 import SwiftSyntax
+import ToolchainRegistry
 import TSCExtensions
 
 import struct TSCBasic.AbsolutePath
@@ -170,7 +171,7 @@ extension SwiftLanguageService {
     options: FormattingOptions,
     range: Range<Position>? = nil
   ) async throws -> [TextEdit]? {
-    guard let swiftFormat else {
+    guard let swiftFormat = toolchain.swiftFormat else {
       throw ResponseError.unknown(
         "Formatting not supported because the toolchain is missing the swift-format executable"
       )

Sources/SwiftLanguageService/SwiftCodeLensScanner.swift

@@ -10,9 +10,12 @@
 //
 //===----------------------------------------------------------------------===//
 
+internal import BuildServerIntegration
+import BuildServerProtocol
 import LanguageServerProtocol
 import SourceKitLSP
 import SwiftSyntax
+import ToolchainRegistry
 
 /// Scans a source file for classes or structs annotated with `@main` and returns a code lens for them.
 final class SwiftCodeLensScanner: SyntaxVisitor {
@@ -42,19 +45,38 @@ final class SwiftCodeLensScanner: SyntaxVisitor {
   /// and returns CodeLens's with Commands to run/debug the application.
   public static func findCodeLenses(
     in snapshot: DocumentSnapshot,
+    workspace: Workspace?,
     syntaxTreeManager: SyntaxTreeManager,
-    targetName: String? = nil,
-    supportedCommands: [SupportedCodeLensCommand: String]
+    supportedCommands: [SupportedCodeLensCommand: String],
+    toolchain: Toolchain
   ) async -> [CodeLens] {
-    guard snapshot.text.contains("@main") && !supportedCommands.isEmpty else {
-      // This is intended to filter out files that obviously do not contain an entry point.
+    guard !supportedCommands.isEmpty else {
       return []
     }
 
+    var targetDisplayName: String? = nil
+    if let workspace,
+      let target = await workspace.buildServerManager.canonicalTarget(for: snapshot.uri),
+      let buildTarget = await workspace.buildServerManager.buildTarget(named: target)
+    {
+      targetDisplayName = buildTarget.displayName
+    }
+
+    var codeLenses: [CodeLens] = []
     let syntaxTree = await syntaxTreeManager.syntaxTree(for: snapshot)
-    let visitor = SwiftCodeLensScanner(snapshot: snapshot, targetName: targetName, supportedCommands: supportedCommands)
-    visitor.walk(syntaxTree)
-    return visitor.result
+    if snapshot.text.contains("@main") {
+      let visitor = SwiftCodeLensScanner(snapshot: snapshot, targetName: targetDisplayName, supportedCommands: supportedCommands)
+      visitor.walk(syntaxTree)
+      codeLenses += visitor.result
+    }
+
+    // "swift.play" CodeLens should be ignored if "swift-play" is not in the toolchain as the client has no way of running
+    if toolchain.swiftPlay != nil, let workspace, let playCommand = supportedCommands[SupportedCodeLensCommand.play], snapshot.text.contains("#Playground") {
+      let playgrounds = await SwiftPlaygroundsScanner.findDocumentPlaygrounds(in: syntaxTree, workspace: workspace, snapshot: snapshot)
+      codeLenses += playgrounds.map({ p in CodeLens(range: p.range, command: Command(title: "Play \"\(p.label ?? p.id)\"", command: playCommand, arguments: [p.encodeToLSPAny()])) })
+    }
+
+    return codeLenses
   }
 
   override func visit(_ node: ClassDeclSyntax) -> SyntaxVisitorContinueKind {