|
| 1 | +//===----------------------------------------------------------------------===// |
| 2 | +// |
| 3 | +// This source file is part of the Swift.org open source project |
| 4 | +// |
| 5 | +// Copyright (c) 2024 Apple Inc. and the Swift project authors |
| 6 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 7 | +// |
| 8 | +// See https://swift.org/LICENSE.txt for license information |
| 9 | +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| 10 | +// |
| 11 | +//===----------------------------------------------------------------------===// |
| 12 | + |
| 13 | +#if canImport(SwiftDocC) |
| 14 | +import Foundation |
| 15 | +@preconcurrency import SwiftDocC |
| 16 | +import SwiftExtensions |
| 17 | + |
| 18 | +final actor DocCCatalogIndexManager { |
| 19 | + private let server: DocCServer |
| 20 | + private var catalogToIndexMap = [URL: Result<DocCCatalogIndex, DocCIndexError>]() |
| 21 | + |
| 22 | + init(server: DocCServer) { |
| 23 | + self.server = server |
| 24 | + } |
| 25 | + |
| 26 | + func invalidate(catalogURLs: some Collection<URL>) { |
| 27 | + guard catalogURLs.count > 0 else { |
| 28 | + return |
| 29 | + } |
| 30 | + for catalogURL in catalogURLs { |
| 31 | + catalogToIndexMap.removeValue(forKey: catalogURL) |
| 32 | + } |
| 33 | + } |
| 34 | + |
| 35 | + func index(for catalogURL: URL, moduleName: String?) async throws(DocCIndexError) -> DocCCatalogIndex { |
| 36 | + if let existingCatalog = catalogToIndexMap[catalogURL] { |
| 37 | + return try existingCatalog.get() |
| 38 | + } |
| 39 | + let catalogIndexResult: Result<DocCCatalogIndex, DocCIndexError> |
| 40 | + do { |
| 41 | + let convertResponse = try await server.convert( |
| 42 | + externalIDsToConvert: [], |
| 43 | + documentPathsToConvert: [], |
| 44 | + includeRenderReferenceStore: true, |
| 45 | + documentationBundleLocation: catalogURL, |
| 46 | + documentationBundleDisplayName: moduleName ?? "unknown", |
| 47 | + documentationBundleIdentifier: "unknown", |
| 48 | + symbolGraphs: [], |
| 49 | + emitSymbolSourceFileURIs: true, |
| 50 | + markupFiles: [], |
| 51 | + tutorialFiles: [], |
| 52 | + convertRequestIdentifier: UUID().uuidString |
| 53 | + ) |
| 54 | + catalogIndexResult = Result { convertResponse } |
| 55 | + .flatMap { convertResponse in |
| 56 | + guard let renderReferenceStoreData = convertResponse.renderReferenceStore else { |
| 57 | + return .failure(.unexpectedlyNilRenderReferenceStore) |
| 58 | + } |
| 59 | + return .success(renderReferenceStoreData) |
| 60 | + } |
| 61 | + .flatMap { renderReferenceStoreData in |
| 62 | + Result { try JSONDecoder().decode(RenderReferenceStore.self, from: renderReferenceStoreData) } |
| 63 | + .flatMapError { .failure(.decodingFailure($0)) } |
| 64 | + } |
| 65 | + .map { DocCCatalogIndex(from: $0) } |
| 66 | + } catch { |
| 67 | + catalogIndexResult = .failure(.serverError(error)) |
| 68 | + } |
| 69 | + catalogToIndexMap[catalogURL] = catalogIndexResult |
| 70 | + return try catalogIndexResult.get() |
| 71 | + } |
| 72 | +} |
| 73 | + |
| 74 | +/// Represents a potential error that the ``DocCCatalogIndexManager`` could encounter while indexing |
| 75 | +enum DocCIndexError: LocalizedError { |
| 76 | + case decodingFailure(Error) |
| 77 | + case serverError(DocCServerError) |
| 78 | + case unexpectedlyNilRenderReferenceStore |
| 79 | + |
| 80 | + var errorDescription: String? { |
| 81 | + switch self { |
| 82 | + case .decodingFailure(let decodingError): |
| 83 | + return "Failed to decode a received message: \(decodingError.localizedDescription)" |
| 84 | + case .serverError(let serverError): |
| 85 | + return "DocC server failed to convert the catalog: \(serverError.localizedDescription)" |
| 86 | + case .unexpectedlyNilRenderReferenceStore: |
| 87 | + return "Did not receive a RenderReferenceStore from the DocC server" |
| 88 | + } |
| 89 | + } |
| 90 | +} |
| 91 | + |
| 92 | +struct DocCCatalogIndex: Sendable { |
| 93 | + private let assetReferenceToDataAsset: [String: DataAsset] |
| 94 | + private let fuzzyAssetReferenceToDataAsset: [String: DataAsset] |
| 95 | + private let documentationExtensionToSourceURL: [DocCSymbolLink: URL] |
| 96 | + let articlePathToSourceURLAndReference: [String: (URL, TopicRenderReference)] |
| 97 | + let tutorialPathToSourceURLAndReference: [String: (URL, TopicRenderReference)] |
| 98 | + let tutorialOverviewPathToSourceURLAndReference: [String: (URL, TopicRenderReference)] |
| 99 | + |
| 100 | + func asset(for assetReference: AssetReference) -> DataAsset? { |
| 101 | + assetReferenceToDataAsset[assetReference.assetName] ?? fuzzyAssetReferenceToDataAsset[assetReference.assetName] |
| 102 | + } |
| 103 | + |
| 104 | + func documentationExtension(for symbolLink: DocCSymbolLink) -> URL? { |
| 105 | + documentationExtensionToSourceURL[symbolLink] |
| 106 | + } |
| 107 | + |
| 108 | + init(from renderReferenceStore: RenderReferenceStore) { |
| 109 | + // Assets |
| 110 | + var assetReferenceToDataAsset = [String: DataAsset]() |
| 111 | + var fuzzyAssetReferenceToDataAsset = [String: DataAsset]() |
| 112 | + for (reference, asset) in renderReferenceStore.assets { |
| 113 | + var asset = asset |
| 114 | + asset.variants = asset.variants.compactMapValues { $0.withScheme("doc-asset") } |
| 115 | + assetReferenceToDataAsset[reference.assetName] = asset |
| 116 | + if let indexOfExtensionDelimiter = reference.assetName.lastIndex(of: ".") { |
| 117 | + let assetNameWithoutExtension = reference.assetName.prefix(upTo: indexOfExtensionDelimiter) |
| 118 | + fuzzyAssetReferenceToDataAsset[String(assetNameWithoutExtension)] = asset |
| 119 | + } |
| 120 | + } |
| 121 | + self.assetReferenceToDataAsset = assetReferenceToDataAsset |
| 122 | + self.fuzzyAssetReferenceToDataAsset = fuzzyAssetReferenceToDataAsset |
| 123 | + // Markdown and Tutorial content |
| 124 | + var documentationExtensionToSourceURL = [DocCSymbolLink: URL]() |
| 125 | + var articlePathToSourceURLAndReference = [String: (URL, TopicRenderReference)]() |
| 126 | + var tutorialPathToSourceURLAndReference = [String: (URL, TopicRenderReference)]() |
| 127 | + var tutorialOverviewPathToSourceURLAndReference = [String: (URL, TopicRenderReference)]() |
| 128 | + for (renderReferenceKey, topicContentValue) in renderReferenceStore.topics { |
| 129 | + guard let topicRenderReference = topicContentValue.renderReference as? TopicRenderReference, |
| 130 | + let topicContentSource = topicContentValue.source |
| 131 | + else { |
| 132 | + continue |
| 133 | + } |
| 134 | + |
| 135 | + if topicContentValue.isDocumentationExtensionContent { |
| 136 | + guard |
| 137 | + let absoluteSymbolLink = AbsoluteSymbolLink(string: topicContentValue.renderReference.identifier.identifier) |
| 138 | + else { |
| 139 | + continue |
| 140 | + } |
| 141 | + let doccSymbolLink = DocCSymbolLink(absoluteSymbolLink: absoluteSymbolLink) |
| 142 | + documentationExtensionToSourceURL[doccSymbolLink] = topicContentValue.source |
| 143 | + } else if topicRenderReference.kind == .article { |
| 144 | + articlePathToSourceURLAndReference[renderReferenceKey.url.lastPathComponent] = ( |
| 145 | + topicContentSource, topicRenderReference |
| 146 | + ) |
| 147 | + } else if topicRenderReference.kind == .tutorial { |
| 148 | + tutorialPathToSourceURLAndReference[renderReferenceKey.url.lastPathComponent] = ( |
| 149 | + topicContentSource, topicRenderReference |
| 150 | + ) |
| 151 | + } else if topicRenderReference.kind == .overview { |
| 152 | + tutorialOverviewPathToSourceURLAndReference[renderReferenceKey.url.lastPathComponent] = ( |
| 153 | + topicContentSource, topicRenderReference |
| 154 | + ) |
| 155 | + } |
| 156 | + } |
| 157 | + self.documentationExtensionToSourceURL = documentationExtensionToSourceURL |
| 158 | + self.articlePathToSourceURLAndReference = articlePathToSourceURLAndReference |
| 159 | + self.tutorialPathToSourceURLAndReference = tutorialPathToSourceURLAndReference |
| 160 | + self.tutorialOverviewPathToSourceURLAndReference = tutorialOverviewPathToSourceURLAndReference |
| 161 | + } |
| 162 | +} |
| 163 | + |
| 164 | +fileprivate extension URL { |
| 165 | + func withScheme(_ scheme: String) -> URL { |
| 166 | + var components = URLComponents(url: self, resolvingAgainstBaseURL: true) |
| 167 | + components?.scheme = scheme |
| 168 | + return components?.url ?? self |
| 169 | + } |
| 170 | +} |
| 171 | +#endif |
0 commit comments