Merge pull request #1854 from matthewbastien/documentation-language-service

Handle `*.md` and `*.tutorial` files from Swift DocC

Author: ahoppen

Contributor Documentation/LSP Extensions.md

@@ -622,3 +622,10 @@ export interface GetReferenceDocumentResult {
   content: string;
 }
 ```
+
+## Languages
+
+Added a new language with the identifier `tutorial` to support the `*.tutorial` files that
+Swift DocC uses to define tutorials and tutorial overviews in its documentation catalogs.
+It is expected that editors send document events for `tutorial` and `markdown` files if
+they wish to request information about these files from SourceKit-LSP.

Sources/BuildSystemIntegration/BuildSystemManager.swift

@@ -632,7 +632,7 @@ package actor BuildSystemManager: QueueBasedMessageHandler {
     }
 
     switch language {
-    case .swift:
+    case .swift, .markdown, .tutorial:
       return await toolchainRegistry.preferredToolchain(containing: [\.sourcekitd, \.swift, \.swiftc])
     case .c, .cpp, .objective_c, .objective_cpp:
       return await toolchainRegistry.preferredToolchain(containing: [\.clang, \.clangd])

Sources/LanguageServerProtocol/SupportTypes/Language.swift

@@ -92,6 +92,7 @@ extension Language: CustomStringConvertible, CustomDebugStringConvertible {
     case .shellScript: return "Shell Script (Bash)"
     case .sql: return "SQL"
     case .swift: return "Swift"
+    case .tutorial: return "Tutorial"
     case .typeScript: return "TypeScript"
     case .typeScriptReact: return "TypeScript React"
     case .tex: return "TeX"
@@ -153,6 +154,7 @@ public extension Language {
   static let shellScript = Language(rawValue: "shellscript")  // Shell Script (Bash)
   static let sql = Language(rawValue: "sql")
   static let swift = Language(rawValue: "swift")
+  static let tutorial = Language(rawValue: "tutorial")  // LSP Extension: Swift DocC Tutorial
   static let typeScript = Language(rawValue: "typescript")
   static let typeScriptReact = Language(rawValue: "typescriptreact")  // TypeScript React
   static let tex = Language(rawValue: "tex")

Sources/SKTestSupport/Utils.swift

@@ -26,6 +26,8 @@ extension Language {
   var fileExtension: String {
     switch self {
     case .objective_c: return "m"
+    case .markdown: return "md"
+    case .tutorial: return "tutorial"
     default: return self.rawValue
     }
   }
@@ -37,6 +39,8 @@ extension Language {
     case "m": self = .objective_c
     case "mm": self = .objective_cpp
     case "swift": self = .swift
+    case "md": self = .markdown
+    case "tutorial": self = .tutorial
     default: return nil
     }
   }

Sources/SourceKitLSP/CMakeLists.txt

@@ -24,6 +24,9 @@ target_sources(SourceKitLSP PRIVATE
   Clang/ClangLanguageService.swift
   Clang/SemanticTokenTranslator.swift
 )
+target_sources(SourceKitLSP PRIVATE
+  Documentation/DocumentationLanguageService.swift
+)
 target_sources(SourceKitLSP PRIVATE
   Swift/AdjustPositionToStartOfIdentifier.swift
   Swift/ClosureCompletionFormat.swift

Sources/SourceKitLSP/Documentation/DocumentationLanguageService.swift

@@ -0,0 +1,255 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 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
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+#if compiler(>=6)
+package import LanguageServerProtocol
+package import SKOptions
+package import SwiftSyntax
+package import ToolchainRegistry
+#else
+import LanguageServerProtocol
+import SKOptions
+import SwiftSyntax
+import ToolchainRegistry
+#endif
+
+package actor DocumentationLanguageService: LanguageService, Sendable {
+  package init?(
+    sourceKitLSPServer: SourceKitLSPServer,
+    toolchain: Toolchain,
+    options: SourceKitLSPOptions,
+    testHooks: TestHooks,
+    workspace: Workspace
+  ) async throws {}
+
+  package nonisolated func canHandle(workspace: Workspace) -> Bool {
+    return true
+  }
+
+  package func initialize(
+    _ initialize: InitializeRequest
+  ) async throws -> InitializeResult {
+    return InitializeResult(
+      capabilities: ServerCapabilities()
+    )
+  }
+
+  package func clientInitialized(_ initialized: InitializedNotification) async {
+    // Nothing to set up
+  }
+
+  package func shutdown() async {
+    // Nothing to tear down
+  }
+
+  package func addStateChangeHandler(
+    handler: @escaping @Sendable (LanguageServerState, LanguageServerState) -> Void
+  ) async {
+    // There is no underlying language server with which to report state
+  }
+
+  package func openDocument(
+    _ notification: DidOpenTextDocumentNotification,
+    snapshot: DocumentSnapshot
+  ) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func closeDocument(_ notification: DidCloseTextDocumentNotification) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func reopenDocument(_ notification: ReopenTextDocumentNotification) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func changeDocument(
+    _ notification: DidChangeTextDocumentNotification,
+    preEditSnapshot: DocumentSnapshot,
+    postEditSnapshot: DocumentSnapshot,
+    edits: [SwiftSyntax.SourceEdit]
+  ) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func willSaveDocument(_ notification: WillSaveTextDocumentNotification) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func didSaveDocument(_ notification: DidSaveTextDocumentNotification) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func documentUpdatedBuildSettings(_ uri: DocumentURI) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func documentDependenciesUpdated(_ uris: Set<DocumentURI>) async {
+    // The DocumentationLanguageService does not do anything with document events
+  }
+
+  package func completion(_ req: CompletionRequest) async throws -> CompletionList {
+    CompletionList(isIncomplete: false, items: [])
+  }
+
+  package func hover(_ req: HoverRequest) async throws -> HoverResponse? {
+    nil
+  }
+
+  package func symbolInfo(_ request: SymbolInfoRequest) async throws -> [SymbolDetails] {
+    []
+  }
+
+  package func openGeneratedInterface(
+    document: DocumentURI,
+    moduleName: String,
+    groupName: String?,
+    symbolUSR symbol: String?
+  ) async throws -> GeneratedInterfaceDetails? {
+    nil
+  }
+
+  package func definition(_ request: DefinitionRequest) async throws -> LocationsOrLocationLinksResponse? {
+    nil
+  }
+
+  package func declaration(_ request: DeclarationRequest) async throws -> LocationsOrLocationLinksResponse? {
+    nil
+  }
+
+  package func documentSymbolHighlight(_ req: DocumentHighlightRequest) async throws -> [DocumentHighlight]? {
+    nil
+  }
+
+  package func foldingRange(_ req: FoldingRangeRequest) async throws -> [FoldingRange]? {
+    nil
+  }
+
+  package func documentSymbol(_ req: DocumentSymbolRequest) async throws -> DocumentSymbolResponse? {
+    nil
+  }
+
+  package func documentColor(_ req: DocumentColorRequest) async throws -> [ColorInformation] {
+    []
+  }
+
+  package func documentSemanticTokens(
+    _ req: DocumentSemanticTokensRequest
+  ) async throws -> DocumentSemanticTokensResponse? {
+    nil
+  }
+
+  package func documentSemanticTokensDelta(
+    _ req: DocumentSemanticTokensDeltaRequest
+  ) async throws -> DocumentSemanticTokensDeltaResponse? {
+    nil
+  }
+
+  package func documentSemanticTokensRange(
+    _ req: DocumentSemanticTokensRangeRequest
+  ) async throws -> DocumentSemanticTokensResponse? {
+    nil
+  }
+
+  package func colorPresentation(_ req: ColorPresentationRequest) async throws -> [ColorPresentation] {
+    []
+  }
+
+  package func codeAction(_ req: CodeActionRequest) async throws -> CodeActionRequestResponse? {
+    nil
+  }
+
+  package func inlayHint(_ req: InlayHintRequest) async throws -> [InlayHint] {
+    []
+  }
+
+  package func codeLens(_ req: CodeLensRequest) async throws -> [CodeLens] {
+    []
+  }
+
+  package func documentDiagnostic(_ req: DocumentDiagnosticsRequest) async throws -> DocumentDiagnosticReport {
+    .full(RelatedFullDocumentDiagnosticReport(items: []))
+  }
+
+  package func documentFormatting(_ req: DocumentFormattingRequest) async throws -> [TextEdit]? {
+    nil
+  }
+
+  package func documentRangeFormatting(
+    _ req: LanguageServerProtocol.DocumentRangeFormattingRequest
+  ) async throws -> [LanguageServerProtocol.TextEdit]? {
+    return nil
+  }
+
+  package func documentOnTypeFormatting(_ req: DocumentOnTypeFormattingRequest) async throws -> [TextEdit]? {
+    return nil
+  }
+
+  package func rename(_ request: RenameRequest) async throws -> (edits: WorkspaceEdit, usr: String?) {
+    (edits: WorkspaceEdit(), usr: nil)
+  }
+
+  package func editsToRename(
+    locations renameLocations: [RenameLocation],
+    in snapshot: DocumentSnapshot,
+    oldName: CrossLanguageName,
+    newName: CrossLanguageName
+  ) async throws -> [TextEdit] {
+    []
+  }
+
+  package func prepareRename(
+    _ request: PrepareRenameRequest
+  ) async throws -> (prepareRename: PrepareRenameResponse, usr: String?)? {
+    nil
+  }
+
+  package func indexedRename(_ request: IndexedRenameRequest) async throws -> WorkspaceEdit? {
+    nil
+  }
+
+  package func editsToRenameParametersInFunctionBody(
+    snapshot: DocumentSnapshot,
+    renameLocation: RenameLocation,
+    newName: CrossLanguageName
+  ) async -> [TextEdit] {
+    []
+  }
+
+  package func executeCommand(_ req: ExecuteCommandRequest) async throws -> LSPAny? {
+    nil
+  }
+
+  package func getReferenceDocument(_ req: GetReferenceDocumentRequest) async throws -> GetReferenceDocumentResponse {
+    GetReferenceDocumentResponse(content: "")
+  }
+
+  package func syntacticDocumentTests(
+    for uri: DocumentURI,
+    in workspace: Workspace
+  ) async throws -> [AnnotatedTestItem]? {
+    nil
+  }
+
+  package func canonicalDeclarationPosition(
+    of position: Position,
+    in uri: DocumentURI
+  ) async -> Position? {
+    nil
+  }
+
+  package func crash() async {
+    // There's no way to crash the DocumentationLanguageService
+  }
+}

Sources/SourceKitLSP/LanguageServerType.swift

@@ -17,13 +17,16 @@ import LanguageServerProtocol
 enum LanguageServerType: Hashable {
   case clangd
   case swift
+  case documentation
 
   init?(language: Language) {
     switch language {
     case .c, .cpp, .objective_c, .objective_cpp:
       self = .clangd
     case .swift:
       self = .swift
+    case .markdown, .tutorial:
+      self = .documentation
     default:
       return nil
     }
@@ -44,6 +47,8 @@ enum LanguageServerType: Hashable {
       return ClangLanguageService.self
     case .swift:
       return SwiftLanguageService.self
+    case .documentation:
+      return DocumentationLanguageService.self
     }
   }
 }

Tests/SourceKitLSPTests/DocumentationLanguageServiceTests.swift

@@ -0,0 +1,41 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 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
+//
+//===----------------------------------------------------------------------===//
+
+import LanguageServerProtocol
+import SKTestSupport
+import SourceKitLSP
+import XCTest
+
+final class DocumentationLanguageServiceTests: XCTestCase {
+  func testHandlesMarkdownFiles() async throws {
+    try await assertHandles(language: .markdown)
+  }
+
+  func testHandlesTutorialFiles() async throws {
+    try await assertHandles(language: .tutorial)
+  }
+}
+
+fileprivate func assertHandles(language: Language) async throws {
+  let testClient = try await TestSourceKitLSPClient()
+  let uri = DocumentURI(for: language)
+  testClient.openDocument("", uri: uri)
+
+  // The DocumentationLanguageService doesn't do much right now except to enable handling `*.md`
+  // and `*.tutorial` files for the purposes of fulfilling documentation requests. We'll just
+  // issue a completion request here to make sure that an empty list is returned and that
+  // SourceKit-LSP does not respond with an error on requests for Markdown and Tutorial files.
+  let completions = try await testClient.send(
+    CompletionRequest(textDocument: .init(uri), position: .init(line: 0, utf16index: 0))
+  )
+  XCTAssertEqual(completions, .init(isIncomplete: false, items: []))
+}