|
10 | 10 | // |
11 | 11 | //===----------------------------------------------------------------------===// |
12 | 12 |
|
| 13 | +import Foundation |
13 | 14 | package import IndexStoreDB |
14 | 15 | import SKLogging |
15 | 16 | import SemanticIndex |
16 | | -@_spi(LinkCompletion) import SwiftDocC |
| 17 | +@preconcurrency @_spi(LinkCompletion) import SwiftDocC |
| 18 | +import SwiftExtensions |
| 19 | +import SymbolKit |
17 | 20 |
|
18 | 21 | extension CheckedIndex { |
19 | 22 | /// Find a `SymbolOccurrence` that is considered the primary definition of the symbol with the given `DocCSymbolLink`. |
20 | 23 | /// |
21 | 24 | /// If the `DocCSymbolLink` has an ambiguous definition, the most important role of this function is to deterministically return |
22 | 25 | /// the same result every time. |
23 | 26 | package func primaryDefinitionOrDeclarationOccurrence( |
24 | | - ofDocCSymbolLink symbolLink: DocCSymbolLink |
25 | | - ) -> SymbolOccurrence? { |
26 | | - var components = symbolLink.components |
27 | | - guard components.count > 0 else { |
28 | | - return nil |
| 27 | + ofDocCSymbolLink symbolLink: DocCSymbolLink, |
| 28 | + fetchSymbolGraph: @Sendable (SymbolLocation) async throws -> String? |
| 29 | + ) async throws -> SymbolOccurrence? { |
| 30 | + guard let topLevelSymbolName = symbolLink.components.last?.name else { |
| 31 | + throw DocCCheckedIndexError.emptyDocCSymbolLink |
29 | 32 | } |
30 | | - // Do a lookup to find the top level symbol |
31 | | - let topLevelSymbol = components.removeLast() |
| 33 | + // Find all occurrences of the symbol by name alone |
32 | 34 | var topLevelSymbolOccurrences: [SymbolOccurrence] = [] |
33 | | - forEachCanonicalSymbolOccurrence(byName: topLevelSymbol.name) { symbolOccurrence in |
| 35 | + forEachCanonicalSymbolOccurrence(byName: topLevelSymbolName) { symbolOccurrence in |
34 | 36 | topLevelSymbolOccurrences.append(symbolOccurrence) |
35 | 37 | return true // continue |
36 | 38 | } |
37 | | - topLevelSymbolOccurrences = topLevelSymbolOccurrences.filter { |
38 | | - let symbolInformation = LinkCompletionTools.SymbolInformation(fromSymbolOccurrence: $0) |
39 | | - return symbolInformation.matches(topLevelSymbol.disambiguation) |
40 | | - } |
41 | | - // Search each potential symbol's parents to find an exact match |
42 | | - let symbolOccurences = topLevelSymbolOccurrences.filter { topLevelSymbolOccurrence in |
43 | | - var components = components |
44 | | - var symbolOccurrence = topLevelSymbolOccurrence |
45 | | - while let nextComponent = components.popLast(), let parentSymbolOccurrence = symbolOccurrence.parent(self) { |
46 | | - let parentSymbolInformation = LinkCompletionTools.SymbolInformation( |
47 | | - fromSymbolOccurrence: parentSymbolOccurrence |
48 | | - ) |
49 | | - guard parentSymbolOccurrence.symbol.name == nextComponent.name, |
50 | | - parentSymbolInformation.matches(nextComponent.disambiguation) |
51 | | - else { |
52 | | - return false |
53 | | - } |
54 | | - symbolOccurrence = parentSymbolOccurrence |
| 39 | + // Determine which of the symbol occurrences actually matches the symbol link |
| 40 | + var result: [SymbolOccurrence] = [] |
| 41 | + for occurrence in topLevelSymbolOccurrences { |
| 42 | + let info = try await doccSymbolInformation(ofUSR: occurrence.symbol.usr, fetchSymbolGraph: fetchSymbolGraph) |
| 43 | + if let info, info.matches(symbolLink) { |
| 44 | + result.append(occurrence) |
55 | 45 | } |
56 | | - // If we have exactly one component left, check to see if it's the module name |
57 | | - if components.count == 1 { |
58 | | - let lastComponent = components.removeLast() |
59 | | - guard lastComponent.name == topLevelSymbolOccurrence.location.moduleName else { |
60 | | - return false |
61 | | - } |
| 46 | + } |
| 47 | + // Ensure that this is deterministic by sorting the results |
| 48 | + result.sort() |
| 49 | + if result.count > 1 { |
| 50 | + logger.debug("Multiple symbols found for DocC symbol link '\(symbolLink.linkString)'") |
| 51 | + } |
| 52 | + return result.first |
| 53 | + } |
| 54 | + |
| 55 | + /// Find the DocCSymbolLink for a given symbol USR. |
| 56 | + /// |
| 57 | + /// - Parameters: |
| 58 | + /// - usr: The symbol USR to find in the index. |
| 59 | + /// - fetchSymbolGraph: Callback that returns a SymbolGraph for a given SymbolLocation |
| 60 | + package func doccSymbolInformation( |
| 61 | + ofUSR usr: String, |
| 62 | + fetchSymbolGraph: (SymbolLocation) async throws -> String? |
| 63 | + ) async throws -> DocCSymbolInformation? { |
| 64 | + guard let topLevelSymbolOccurrence = primaryDefinitionOrDeclarationOccurrence(ofUSR: usr) else { |
| 65 | + return nil |
| 66 | + } |
| 67 | + let moduleName = topLevelSymbolOccurrence.location.moduleName |
| 68 | + var symbols = [topLevelSymbolOccurrence] |
| 69 | + // Find any parent symbols |
| 70 | + var symbolOccurrence: SymbolOccurrence = topLevelSymbolOccurrence |
| 71 | + while let parentSymbolOccurrence = symbolOccurrence.parent(self) { |
| 72 | + symbols.insert(parentSymbolOccurrence, at: 0) |
| 73 | + symbolOccurrence = parentSymbolOccurrence |
| 74 | + } |
| 75 | + // Fetch symbol information from the symbol graph |
| 76 | + var components = [DocCSymbolInformation.Component(fromModuleName: moduleName)] |
| 77 | + for symbolOccurence in symbols { |
| 78 | + guard let rawSymbolGraph = try await fetchSymbolGraph(symbolOccurence.location) else { |
| 79 | + throw DocCCheckedIndexError.noSymbolGraph(symbolOccurence.symbol.usr) |
62 | 80 | } |
63 | | - guard components.isEmpty else { |
64 | | - return false |
| 81 | + let symbolGraph = try JSONDecoder().decode(SymbolGraph.self, from: Data(rawSymbolGraph.utf8)) |
| 82 | + guard let symbol = symbolGraph.symbols[symbolOccurence.symbol.usr] else { |
| 83 | + throw DocCCheckedIndexError.symbolNotFound(symbolOccurence.symbol.usr) |
65 | 84 | } |
66 | | - return true |
67 | | - }.sorted() |
68 | | - if symbolOccurences.count > 1 { |
69 | | - logger.debug("Multiple symbols found for DocC symbol link '\(symbolLink.linkString)'") |
| 85 | + components.append(DocCSymbolInformation.Component(fromSymbol: symbol)) |
| 86 | + } |
| 87 | + return DocCSymbolInformation(components: components) |
| 88 | + } |
| 89 | +} |
| 90 | + |
| 91 | +enum DocCCheckedIndexError: LocalizedError { |
| 92 | + case emptyDocCSymbolLink |
| 93 | + case noSymbolGraph(String) |
| 94 | + case symbolNotFound(String) |
| 95 | + |
| 96 | + var errorDescription: String? { |
| 97 | + switch self { |
| 98 | + case .emptyDocCSymbolLink: |
| 99 | + "The provided DocCSymbolLink was empty and could not be resolved" |
| 100 | + case .noSymbolGraph(let usr): |
| 101 | + "Unable to locate symbol graph for \(usr)" |
| 102 | + case .symbolNotFound(let usr): |
| 103 | + "Symbol \(usr) was not found in its symbol graph" |
70 | 104 | } |
71 | | - return symbolOccurences.first |
72 | 105 | } |
73 | 106 | } |
74 | 107 |
|
|
0 commit comments