Merge pull request #1959 from matthewbastien/markdown-documentation

Handle Markdown and Tutorial files in textDocument/doccDocumentation

Author: ahoppen

Contributor Documentation/BSP Extensions.md

@@ -76,18 +76,13 @@ export interface PrepareParams {
 ```ts
 export interface SourceKitSourceItemData {
   /** The language of the source file. If `nil`, the language is inferred from the file extension. */
-  language? LanguageId;
+  language?: LanguageId;
 
-  /** Whether the file is a header file that is clearly associated with one target.
-   *
-   * For example header files in SwiftPM projects are always associated to one target and SwiftPM can provide build
-   * settings for that header file.
-   *
-   * In general, build systems don't need to list all header files in the `buildTarget/sources` request: Semantic
-   * functionality for header files is usually provided by finding a main file that includes the header file and
-   * inferring build settings from it. Listing header files in `buildTarget/sources` allows SourceKit-LSP to provide
-   * semantic functionality for header files if they haven't been included by any main file. **/
-  isHeader?: bool;
+  /** 
+   * The kind of source file that this source item represents. If omitted, the item is assumed to be a normal source
+   * file, ie. omitting this key is equivalent to specifying it as `source`.
+   */
+  kind?: "source" | "header" | "doccCatalog";
 
   /**
    * The output path that is during indexing for this file, ie. the `-index-unit-output-path`, if it is specified

Package.swift

@@ -214,6 +214,25 @@ var targets: [Target] = [
     swiftSettings: globalSwiftSettings
   ),
 
+  // MARK: DocCDocumentation
+
+  .target(
+    name: "DocCDocumentation",
+    dependencies: [
+      "BuildServerProtocol",
+      "BuildSystemIntegration",
+      "LanguageServerProtocol",
+      "SemanticIndex",
+      "SKLogging",
+      "SwiftExtensions",
+      .product(name: "IndexStoreDB", package: "indexstore-db"),
+      .product(name: "SwiftDocC", package: "swift-docc"),
+      .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
+    ],
+    exclude: ["CMakeLists.txt"],
+    swiftSettings: globalSwiftSettings
+  ),
+
   // MARK: InProcessClient
 
   .target(
@@ -476,6 +495,7 @@ var targets: [Target] = [
     dependencies: [
       "BuildServerProtocol",
       "BuildSystemIntegration",
+      "DocCDocumentation",
       "LanguageServerProtocol",
       "LanguageServerProtocolExtensions",
       "LanguageServerProtocolJSONRPC",
@@ -487,9 +507,9 @@ var targets: [Target] = [
       "SwiftExtensions",
       "ToolchainRegistry",
       "TSCExtensions",
-      .product(name: "SwiftDocC", package: "swift-docc"),
       .product(name: "IndexStoreDB", package: "indexstore-db"),
       .product(name: "Crypto", package: "swift-crypto"),
+      .product(name: "Markdown", package: "swift-markdown"),
       .product(name: "SwiftToolsSupport-auto", package: "swift-tools-support-core"),
     ]
       + swiftPMDependency([
@@ -772,6 +792,8 @@ var dependencies: [Package.Dependency] {
     return [
       .package(path: "../indexstore-db"),
       .package(path: "../swift-docc"),
+      .package(path: "../swift-docc-symbolkit"),
+      .package(path: "../swift-markdown"),
       .package(path: "../swift-tools-support-core"),
       .package(path: "../swift-argument-parser"),
       .package(path: "../swift-syntax"),
@@ -783,6 +805,8 @@ var dependencies: [Package.Dependency] {
     return [
       .package(url: "https://github.com/swiftlang/indexstore-db.git", branch: relatedDependenciesBranch),
       .package(url: "https://github.com/swiftlang/swift-docc.git", branch: relatedDependenciesBranch),
+      .package(url: "https://github.com/swiftlang/swift-docc-symbolkit.git", branch: relatedDependenciesBranch),
+      .package(url: "https://github.com/swiftlang/swift-markdown.git", branch: relatedDependenciesBranch),
       .package(url: "https://github.com/apple/swift-tools-support-core.git", branch: relatedDependenciesBranch),
       .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.4.0"),
       .package(url: "https://github.com/swiftlang/swift-syntax.git", branch: relatedDependenciesBranch),

Sources/BuildServerProtocol/Messages/BuildTargetSourcesRequest.swift

@@ -119,11 +119,12 @@ public struct SourceItemDataKind: RawRepresentable, Codable, Hashable, Sendable
 }
 
 /// **(BSP Extension)**
-public struct SourceKitSourceItemData: LSPAnyCodable, Codable {
-  /// The language of the source file. If `nil`, the language is inferred from the file extension.
-  public var language: Language?
 
-  /// Whether the file is a header file that is clearly associated with one target.
+public enum SourceKitSourceItemKind: String, Codable {
+  /// A source file that belongs to the target
+  case source = "source"
+
+  /// A header file that is clearly associated with one target.
   ///
   /// For example header files in SwiftPM projects are always associated to one target and SwiftPM can provide build
   /// settings for that header file.
@@ -132,7 +133,19 @@ public struct SourceKitSourceItemData: LSPAnyCodable, Codable {
   /// functionality for header files is usually provided by finding a main file that includes the header file and
   /// inferring build settings from it. Listing header files in `buildTarget/sources` allows SourceKit-LSP to provide
   /// semantic functionality for header files if they haven't been included by any main file.
-  public var isHeader: Bool?
+  case header = "header"
+
+  /// A SwiftDocC documentation catalog usually ending in the ".docc" extension.
+  case doccCatalog = "doccCatalog"
+}
+
+public struct SourceKitSourceItemData: LSPAnyCodable, Codable {
+  /// The language of the source file. If `nil`, the language is inferred from the file extension.
+  public var language: Language?
+
+  /// The kind of source file that this source item represents. If omitted, the item is assumed to be a normal source file,
+  /// ie. omitting this key is equivalent to specifying it as `source`.
+  public var kind: SourceKitSourceItemKind?
 
   /// The output path that is used during indexing for this file, ie. the `-index-unit-output-path`, if it is specified
   /// in the compiler arguments or the file that is passed as `-o`, if `-index-unit-output-path` is not specified.
@@ -144,18 +157,22 @@ public struct SourceKitSourceItemData: LSPAnyCodable, Codable {
   /// `outputPathsProvider: true` in `SourceKitInitializeBuildResponseData`.
   public var outputPath: String?
 
-  public init(language: Language? = nil, isHeader: Bool? = nil, outputPath: String? = nil) {
+  public init(language: Language? = nil, kind: SourceKitSourceItemKind? = nil, outputPath: String? = nil) {
     self.language = language
-    self.isHeader = isHeader
+    self.kind = kind
     self.outputPath = outputPath
   }
 
   public init?(fromLSPDictionary dictionary: [String: LanguageServerProtocol.LSPAny]) {
     if case .string(let language) = dictionary[CodingKeys.language.stringValue] {
       self.language = Language(rawValue: language)
     }
-    if case .bool(let isHeader) = dictionary[CodingKeys.isHeader.stringValue] {
-      self.isHeader = isHeader
+    if case .string(let rawKind) = dictionary[CodingKeys.kind.stringValue] {
+      self.kind = SourceKitSourceItemKind(rawValue: rawKind)
+    }
+    // Backwards compatibility for isHeader
+    if case .bool(let isHeader) = dictionary["isHeader"], isHeader {
+      self.kind = .header
     }
     if case .string(let outputFilePath) = dictionary[CodingKeys.outputPath.stringValue] {
       self.outputPath = outputFilePath
@@ -167,8 +184,8 @@ public struct SourceKitSourceItemData: LSPAnyCodable, Codable {
     if let language {
       result[CodingKeys.language.stringValue] = .string(language.rawValue)
     }
-    if let isHeader {
-      result[CodingKeys.isHeader.stringValue] = .bool(isHeader)
+    if let kind {
+      result[CodingKeys.kind.stringValue] = .string(kind.rawValue)
     }
     if let outputPath {
       result[CodingKeys.outputPath.stringValue] = .string(outputPath)

Sources/BuildSystemIntegration/BuildSystemManager.swift

@@ -1266,7 +1266,7 @@ package actor BuildSystemManager: QueueBasedMessageHandler {
             isPartOfRootProject: isPartOfRootProject,
             mayContainTests: mayContainTests,
             isBuildable: !(target?.tags.contains(.notBuildable) ?? false)
-              && !(sourceKitData?.isHeader ?? false)
+              && (sourceKitData?.kind ?? .source) == .source
           )
           switch sourceItem.kind {
           case .file:

Sources/BuildSystemIntegration/FileBuildSettings.swift

@@ -55,7 +55,7 @@ package struct FileBuildSettings: Equatable, Sendable {
   ///
   /// This patches the arguments by searching for the argument corresponding to
   /// `originalFile` and replacing it.
-  func patching(newFile: DocumentURI, originalFile: DocumentURI) -> FileBuildSettings {
+  package func patching(newFile: DocumentURI, originalFile: DocumentURI) -> FileBuildSettings {
     var arguments = self.compilerArguments
     // URL.lastPathComponent is only set for file URLs but we want to also infer a file extension for non-file URLs like
     // untitled:file.cpp

Sources/BuildSystemIntegration/SwiftPMBuildSystem.swift

@@ -593,16 +593,23 @@ package actor SwiftPMBuildSystem: BuiltInBuildSystem {
           kind: .file,
           generated: false,
           dataKind: .sourceKit,
-          data: SourceKitSourceItemData(isHeader: true).encodeToLSPAny()
-        )
-      }
-      sources += (swiftPMTarget.resources + swiftPMTarget.ignored + swiftPMTarget.others).map {
-        SourceItem(
-          uri: DocumentURI($0),
-          kind: $0.isDirectory ? .directory : .file,
-          generated: false
+          data: SourceKitSourceItemData(kind: .header).encodeToLSPAny()
         )
       }
+      sources += (swiftPMTarget.resources + swiftPMTarget.ignored + swiftPMTarget.others)
+        .map { (url: URL) -> SourceItem in
+          var data: SourceKitSourceItemData? = nil
+          if url.isDirectory, url.pathExtension == "docc" {
+            data = SourceKitSourceItemData(kind: .doccCatalog)
+          }
+          return SourceItem(
+            uri: DocumentURI(url),
+            kind: url.isDirectory ? .directory : .file,
+            generated: false,
+            dataKind: data != nil ? .sourceKit : nil,
+            data: data?.encodeToLSPAny()
+          )
+        }
       result.append(SourcesItem(target: target, sources: sources))
     }
     return BuildTargetSourcesResponse(items: result)

Sources/DocCDocumentation/BuildSystemIntegrationExtensions.swift

@@ -0,0 +1,72 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 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
+//
+//===----------------------------------------------------------------------===//
+
+package import BuildServerProtocol
+package import BuildSystemIntegration
+package import Foundation
+import LanguageServerProtocol
+import SKLogging
+
+package extension BuildSystemManager {
+  /// Retrieves the name of the Swift module for a given target.
+  ///
+  /// **Note:** prefer using ``module(for:in:)`` over ths function. This function
+  /// only exists for cases where you want the Swift module name of a target where
+  /// you don't know one of its Swift document URIs in advance. E.g. when handling
+  /// requests for Markdown/Tutorial files in DocC since they don't have compile
+  /// commands that could be used to find the module name.
+  ///
+  /// - Parameter target: The build target identifier
+  /// - Returns: The name of the Swift module or nil if it could not be determined
+  func moduleName(for target: BuildTargetIdentifier) async -> String? {
+    let sourceFiles =
+      await orLog(
+        "Failed to retreive source files from target \(target.uri)",
+        { try await self.sourceFiles(in: [target]).flatMap(\.sources) }
+      ) ?? []
+    for sourceFile in sourceFiles {
+      let language = await defaultLanguage(for: sourceFile.uri, in: target)
+      guard language == .swift else {
+        continue
+      }
+      if let moduleName = await moduleName(for: sourceFile.uri, in: target) {
+        return moduleName
+      }
+    }
+    return nil
+  }
+
+  /// Finds the SwiftDocC documentation catalog associated with a target, if any.
+  ///
+  /// - Parameter target: The build target identifier
+  /// - Returns: The URL of the documentation catalog or nil if one could not be found
+  func doccCatalog(for target: BuildTargetIdentifier) async -> URL? {
+    let sourceFiles =
+      await orLog(
+        "Failed to retrieve source files from target \(target.uri)",
+        { try await self.sourceFiles(in: [target]).flatMap(\.sources) }
+      ) ?? []
+    let catalogURLs = sourceFiles.compactMap { sourceItem -> URL? in
+      guard sourceItem.dataKind == .sourceKit,
+        let data = SourceKitSourceItemData(fromLSPAny: sourceItem.data),
+        data.kind == .doccCatalog
+      else {
+        return nil
+      }
+      return sourceItem.uri.fileURL
+    }.sorted(by: { $0.absoluteString < $1.absoluteString })
+    if catalogURLs.count > 1 {
+      logger.error("Multiple SwiftDocC catalogs found in build target \(target.uri)")
+    }
+    return catalogURLs.first
+  }
+}