Make DocumentationLanguageService the only module that imports DocCDocumentation

Author: ahoppen

Sources/DocCDocumentation/DoccDocumentationError.swift

@@ -15,16 +15,13 @@ package import LanguageServerProtocol
 
 package enum DocCDocumentationError: LocalizedError {
   case unsupportedLanguage(Language)
-  case noDocumentableSymbols
   case indexNotAvailable
   case symbolNotFound(String)
 
   var errorDescription: String? {
     switch self {
     case .unsupportedLanguage(let language):
       return "Documentation preview is not available for \(language.description) files"
-    case .noDocumentableSymbols:
-      return "No documentable symbols were found in this Swift file"
     case .indexNotAvailable:
       return "The index is not availble to complete the request"
     case .symbolNotFound(let symbolName):

Sources/DocumentationLanguageService/DoccDocumentationHandler.swift

@@ -10,17 +10,16 @@
 //
 //===----------------------------------------------------------------------===//
 
-#if canImport(DocCDocumentation)
 import BuildServerIntegration
 import DocCDocumentation
 import Foundation
 @preconcurrency import IndexStoreDB
 package import LanguageServerProtocol
 import Markdown
+import SKLogging
 import SKUtilities
-import SourceKitLSP
 import SemanticIndex
-import SKLogging
+import SourceKitLSP
 
 extension DocumentationLanguageService {
   package func doccDocumentation(_ req: DoccDocumentationRequest) async throws -> DoccDocumentationResponse {
@@ -76,7 +75,7 @@ extension DocumentationLanguageService {
     moduleName: String?,
     catalogURL: URL?
   ) async throws -> DoccDocumentationResponse {
-    return try await workspace.doccDocumentationManager.renderDocCDocumentation(
+    return try await documentationManager.renderDocCDocumentation(
       tutorialFile: snapshot.text,
       moduleName: moduleName,
       catalogURL: catalogURL
@@ -92,7 +91,7 @@ extension DocumentationLanguageService {
     guard let sourceKitLSPServer else {
       throw ResponseError.internalError("SourceKit-LSP is shutting down")
     }
-    let documentationManager = workspace.doccDocumentationManager
+    let documentationManager = documentationManager
     guard case .symbol(let symbolName) = MarkdownTitleFinder.find(parsing: snapshot.text) else {
       // This is an article that can be rendered on its own
       return try await documentationManager.renderDocCDocumentation(
@@ -171,7 +170,6 @@ extension DocumentationLanguageService {
     guard let sourceKitLSPServer else {
       throw ResponseError.internalError("SourceKit-LSP is shutting down")
     }
-    let documentationManager = workspace.doccDocumentationManager
     let (symbolGraph, symbolUSR, overrideDocComments) = try await sourceKitLSPServer.primaryLanguageService(
       for: snapshot.uri,
       snapshot.language,
@@ -275,4 +273,3 @@ struct MarkdownTitleFinder: MarkupVisitor {
     return .plainText(heading.plainText)
   }
 }
-#endif

Sources/DocumentationLanguageService/DocumentationLanguageService.swift

@@ -10,6 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
+import DocCDocumentation
 import Foundation
 package import IndexStoreDB
 package import LanguageServerProtocol
@@ -23,6 +24,8 @@ package actor DocumentationLanguageService: LanguageService, Sendable {
   /// The ``SourceKitLSPServer`` instance that created this `DocumentationLanguageService`.
   private(set) weak var sourceKitLSPServer: SourceKitLSPServer?
 
+  let documentationManager: DocCDocumentationManager
+
   var documentManager: DocumentManager {
     get throws {
       guard let sourceKitLSPServer else {
@@ -34,6 +37,12 @@ package actor DocumentationLanguageService: LanguageService, Sendable {
 
   package static var builtInCommands: [String] { [] }
 
+  package static var experimentalCapabilities: [String: LSPAny] {
+    return [
+      DoccDocumentationRequest.method: .dictionary(["version": .int(1)])
+    ]
+  }
+
   package init(
     sourceKitLSPServer: SourceKitLSPServer,
     toolchain: Toolchain,
@@ -42,6 +51,7 @@ package actor DocumentationLanguageService: LanguageService, Sendable {
     workspace: Workspace
   ) async throws {
     self.sourceKitLSPServer = sourceKitLSPServer
+    self.documentationManager = DocCDocumentationManager(buildServerManager: workspace.buildServerManager)
   }
 
   func workspaceForDocument(uri: DocumentURI) async throws -> Workspace? {
@@ -109,6 +119,10 @@ package actor DocumentationLanguageService: LanguageService, Sendable {
     // The DocumentationLanguageService does not do anything with document events
   }
 
+  package func filesDidChange(_ events: [FileEvent]) async {
+    await documentationManager.filesDidChange(events)
+  }
+
   package func documentUpdatedBuildSettings(_ uri: DocumentURI) async {
     // The DocumentationLanguageService does not do anything with document events
   }

Sources/SKTestSupport/SkipUnless.swift

@@ -11,6 +11,7 @@
 //===----------------------------------------------------------------------===//
 
 import Foundation
+import InProcessClient
 import LanguageServerProtocol
 import LanguageServerProtocolExtensions
 import RegexBuilder
@@ -386,6 +387,41 @@ package actor SkipUnless {
         )
     }
   }
+
+  /// Check if SourceKit-LSP was compiled with docc support
+  package static func doccSupported(
+    file: StaticString = #filePath,
+    line: UInt = #line
+  ) async throws {
+    return try await shared.skipUnlessSupported(file: file, line: line) {
+      let server = try await SourceKitLSPServer(
+        client: LocalConnection(receiverName: "client"),
+        toolchainRegistry: .forTesting,
+        languageServerRegistry: .staticallyKnownServices,
+        options: .testDefault(),
+        hooks: Hooks()
+      )
+      let initializeResponse = try await withCheckedThrowingContinuation { continuation in
+        let initializeRequest = InitializeRequest(
+          processId: nil,
+          rootPath: nil,
+          rootURI: nil,
+          capabilities: ClientCapabilities(),
+          trace: .off,
+          workspaceFolders: []
+        )
+        server.handle(initializeRequest, id: .number(0)) { result in
+          continuation.resume(with: result)
+        }
+      }
+      guard case .dictionary(let dict) = initializeResponse.capabilities.experimental,
+        dict[DoccDocumentationRequest.method] != nil
+      else {
+        return .featureUnsupported(skipMessage: "docc not supported")
+      }
+      return .featureSupported
+    }
+  }
 }
 
 // MARK: - Parsing Swift compiler version

Sources/SourceKitLSP/LanguageService.swift

@@ -121,6 +121,9 @@ package protocol LanguageService: AnyObject, Sendable {
   /// Identifiers of the commands that this language service can handle.
   static var builtInCommands: [String] { get }
 
+  /// Experimental capabilities that should be reported to the client if this language service is enabled.
+  static var experimentalCapabilities: [String: LSPAny] { get }
+
   // MARK: - Lifetime
 
   func initialize(_ initialize: InitializeRequest) async throws -> InitializeResult
@@ -160,6 +163,10 @@ package protocol LanguageService: AnyObject, Sendable {
   func willSaveDocument(_ notification: WillSaveTextDocumentNotification) async
   func didSaveDocument(_ notification: DidSaveTextDocumentNotification) async
 
+  /// Called when files are changed on disk and the editor sends a `workspace/didChangeWatchedFiles` notification to
+  /// SourceKit-LSP.
+  func filesDidChange(_ events: [FileEvent]) async
+
   // MARK: - Build Server Integration
 
   /// Sent when the build server has resolved build settings, such as for the initial build settings
@@ -310,3 +317,9 @@ package protocol LanguageService: AnyObject, Sendable {
   /// Crash the language server. Should be used for crash recovery testing only.
   func crash() async
 }
+
+package extension LanguageService {
+  static var experimentalCapabilities: [String: LSPAny] { [:] }
+
+  func filesDidChange(_ events: [FileEvent]) async {}
+}

Sources/SourceKitLSP/SourceKitLSPServer.swift

@@ -28,10 +28,6 @@ package import ToolchainRegistry
 import struct TSCBasic.AbsolutePath
 import protocol TSCBasic.FileSystem
 
-#if canImport(DocCDocumentation)
-import DocCDocumentation
-#endif
-
 /// Disambiguate LanguageServerProtocol.Language and IndexstoreDB.Language
 package typealias Language = LanguageServerProtocol.Language
 
@@ -1116,9 +1112,14 @@ extension SourceKitLSPServer {
       GetReferenceDocumentRequest.method: .dictionary(["version": .int(1)]),
       DidChangeActiveDocumentNotification.method: .dictionary(["version": .int(1)]),
     ]
-    #if canImport(DocCDocumentation)
-    experimentalCapabilities["textDocument/doccDocumentation"] = .dictionary(["version": .int(1)])
-    #endif
+    for (key, value) in languageServiceRegistry.languageServices.flatMap({ $0.type.experimentalCapabilities }) {
+      if let existingValue = experimentalCapabilities[key] {
+        logger.error(
+          "Conflicting experimental capabilities for \(key): \(existingValue.forLogging) vs \(value.forLogging)"
+        )
+      }
+      experimentalCapabilities[key] = value
+    }
 
     return ServerCapabilities(
       textDocumentSync: .options(
@@ -1520,6 +1521,10 @@ extension SourceKitLSPServer {
     // (e.g. Package.swift doesn't have build settings but affects build
     // settings). Inform the build server about all file changes.
     await workspaces.concurrentForEach { await $0.filesDidChange(notification.changes) }
+
+    for languageService in languageServices.values.flatMap(\.self) {
+      await languageService.filesDidChange(notification.changes)
+    }
   }
 
   func setBackgroundIndexingPaused(_ request: SetOptionsRequest) async throws -> VoidResponse {

Sources/SourceKitLSP/Workspace.swift

@@ -26,10 +26,6 @@ import ToolchainRegistry
 import struct TSCBasic.AbsolutePath
 import struct TSCBasic.RelativePath
 
-#if canImport(DocCDocumentation)
-package import DocCDocumentation
-#endif
-
 /// Actor that caches realpaths for `sourceFilesWithSameRealpath`.
 fileprivate actor SourceFilesWithSameRealpathInferrer {
   private let buildServerManager: BuildServerManager
@@ -101,10 +97,6 @@ package final class Workspace: Sendable, BuildServerManagerDelegate {
   /// The build server manager to use for documents in this workspace.
   package let buildServerManager: BuildServerManager
 
-  #if canImport(DocCDocumentation)
-  package let doccDocumentationManager: DocCDocumentationManager
-  #endif
-
   private let sourceFilesWithSameRealpathInferrer: SourceFilesWithSameRealpathInferrer
 
   let options: SourceKitLSPOptions
@@ -153,9 +145,6 @@ package final class Workspace: Sendable, BuildServerManagerDelegate {
     self.options = options
     self._uncheckedIndex = ThreadSafeBox(initialValue: uncheckedIndex)
     self.buildServerManager = buildServerManager
-    #if canImport(DocCDocumentation)
-    self.doccDocumentationManager = DocCDocumentationManager(buildServerManager: buildServerManager)
-    #endif
     self.sourceFilesWithSameRealpathInferrer = SourceFilesWithSameRealpathInferrer(
       buildServerManager: buildServerManager
     )
@@ -417,9 +406,6 @@ package final class Workspace: Sendable, BuildServerManagerDelegate {
 
     // Notify all clients about the reported and inferred edits.
     await buildServerManager.filesDidChange(events)
-    #if canImport(DocCDocumentation)
-    await doccDocumentationManager.filesDidChange(events)
-    #endif
 
     async let updateSyntacticIndex: Void = await syntacticTestIndex.filesDidChange(events)
     async let updateSemanticIndex: Void? = await semanticIndexManager?.filesDidChange(events)

Sources/SwiftLanguageService/CMakeLists.txt

@@ -1,6 +1,5 @@
 add_library(SwiftLanguageService STATIC
   SemanticRefactoring.swift
-  DoccDocumentation.swift
   SwiftTestingScanner.swift
   FoldingRange.swift
   CMakeLists.txt

Sources/SwiftLanguageService/DoccDocumentation.swift

@@ -802,6 +802,10 @@ extension SwiftLanguageService {
     )
   }
 
+  package func doccDocumentation(_ req: DoccDocumentationRequest) async throws -> DoccDocumentationResponse {
+    throw ResponseError.requestNotImplemented(DoccDocumentationRequest.self)
+  }
+
   package func documentColor(_ req: DocumentColorRequest) async throws -> [ColorInformation] {
     let snapshot = try self.documentManager.latestSnapshot(req.textDocument.uri)