Use SymbolKit's "unified symbol graph" representation when loading symbol graphs (#30)

* use parsed symbol kinds

* use unified symbol graphs when loading symbols

rdar://69835303

* Add experimental Objective-C feature flag

Resolves rdar://84269048.

Co-authored-by: Ethan Kusters <[email protected]>

Author: QuietMisdreavus

Package.resolved

@@ -115,6 +115,10 @@ public struct ConvertService: DocumentationService {
         messageIdentifier: String
     ) -> Result<([RenderNode], RenderReferenceStore?), ConvertServiceError> {
         Result {
+            // Update DocC's current feature flags based on the ones provided
+            // in the request.
+            FeatureFlags.current = request.featureFlags
+            
             // Set up the documentation context.
 
             let workspace = DocumentationWorkspace()

Sources/SwiftDocC/DocumentationService/Convert/ConvertService.swift

@@ -19,6 +19,9 @@ public struct ConvertRequest: Codable {
     /// - ``DocumentationBundle/Info-swift.struct``
     public var bundleInfo: DocumentationBundle.Info
 
+    /// Feature flags to enable when performing this convert request.
+    public var featureFlags: FeatureFlags
+    
     /// The external IDs of the symbols to convert.
     ///
     /// Use this property to indicate what symbol documentation nodes should be converted. When ``externalIDsToConvert``
@@ -151,6 +154,7 @@ public struct ConvertRequest: Codable {
         self.knownDisambiguatedSymbolPathComponents = knownDisambiguatedSymbolPathComponents
         self.markupFiles = markupFiles
         self.miscResourceURLs = miscResourceURLs
+        self.featureFlags = FeatureFlags()
 
         self.bundleInfo = DocumentationBundle.Info(
             displayName: displayName,
@@ -174,6 +178,7 @@ public struct ConvertRequest: Codable {
     ///   - miscResourceURLs: The on-disk resources in the documentation bundle to convert.
     public init(
         bundleInfo: DocumentationBundle.Info,
+        featureFlags: FeatureFlags = FeatureFlags(),
         externalIDsToConvert: [String]?,
         documentPathsToConvert: [String]? = nil,
         includeRenderReferenceStore: Bool? = nil,
@@ -192,5 +197,6 @@ public struct ConvertRequest: Codable {
         self.markupFiles = markupFiles
         self.miscResourceURLs = miscResourceURLs
         self.bundleInfo = bundleInfo
+        self.featureFlags = featureFlags
     }
 }

Sources/SwiftDocC/DocumentationService/Models/Services/Convert/ConvertRequest.swift

@@ -25,7 +25,7 @@ extension ExternalSymbolResolver {
     /// everything should work as expected in practice — covering the exceptions with the known values and having "any symbol"
     /// value for the rest.
     static func symbolKind(forNodeKind kind: DocumentationNode.Kind) -> SymbolGraph.Symbol.Kind {
-        let symbolKind: SymbolGraph.Symbol.Kind.Swift
+        let symbolKind: SymbolGraph.Symbol.KindIdentifier
 
         switch kind {
         case .associatedType:
@@ -75,6 +75,6 @@ extension ExternalSymbolResolver {
             symbolKind = .class
         }
 
-        return .init(identifier: symbolKind.rawValue, displayName: kind.name)
+        return .init(parsedIdentifier: symbolKind, displayName: kind.name)
     }
 }

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -17,6 +17,8 @@ import SymbolKit
 /// which makes detecting symbol collisions and overloads easier.
 struct SymbolGraphLoader {
     private(set) var symbolGraphs: [URL: SymbolKit.SymbolGraph] = [:]
+    private(set) var unifiedGraphs: [String: SymbolKit.UnifiedSymbolGraph] = [:]
+    private(set) var graphLocations: [String: [SymbolKit.GraphCollector.GraphKind]] = [:]
     private var dataProvider: DocumentationContextDataProvider
     private var bundle: DocumentationBundle
 
@@ -48,6 +50,7 @@ struct SymbolGraphLoader {
         let decoder = JSONDecoder()
 
         var loadedGraphs = [URL: SymbolKit.SymbolGraph]()
+        let graphLoader = GraphCollector()
         var loadError: Error?
         let bundle = self.bundle
         let dataProvider = self.dataProvider
@@ -68,14 +71,25 @@ struct SymbolGraphLoader {
                 case .concurrentlyEachFileInBatches:
                     symbolGraph = try SymbolGraphConcurrentDecoder.decode(data)
                 }
+                
+                if let firstSymbolLanguage = symbolGraph.symbols.first?.value.identifier.interfaceLanguage {
+                    guard FeatureFlags.current.isExperimentalObjectiveCSupportEnabled
+                            || InterfaceLanguage.from(string: firstSymbolLanguage) == .swift
+                    else {
+                        return
+                    }
+                }
 
                 // `moduleNameFor(_:at:)` is static because it's pure function.
                 let (moduleName, _) = Self.moduleNameFor(symbolGraph, at: symbolGraphURL)
                 // If the bundle provides availability defaults add symbol availability data.
                 self.addDefaultAvailability(to: &symbolGraph, moduleName: moduleName)
 
                 // Store the decoded graph in `loadedGraphs`
-                loadingLock.sync { loadedGraphs[symbolGraphURL] = symbolGraph }
+                loadingLock.sync {
+                    loadedGraphs[symbolGraphURL] = symbolGraph
+                    graphLoader.mergeSymbolGraph(symbolGraph, at: symbolGraphURL)
+                }
             } catch {
                 // If the symbol graph was invalid, store the error
                 loadingLock.sync { loadError = error }
@@ -110,6 +124,7 @@ struct SymbolGraphLoader {
         }
 
         self.symbolGraphs = loadedGraphs
+        (self.unifiedGraphs, self.graphLocations) = graphLoader.finishLoading()
     }
 
     // Alias to declutter code

Sources/SwiftDocC/Infrastructure/External Data/ExternalSymbolResolver+SymbolKind.swift

@@ -142,14 +142,14 @@ struct SymbolGraphRelationshipsBuilder {
         let relationshipConstraints = edge.mixins[SymbolGraph.Relationship.Swift.GenericConstraints.mixinKey] as? SymbolGraph.Relationship.Swift.GenericConstraints
 
         // Add relationships depending whether it's class inheritance or protocol conformance
-        if conformingSymbol.kind.identifier == SymbolGraph.Symbol.Kind.Swift.protocol.rawValue {
+        if conformingSymbol.kind.identifier == .protocol {
             conformingSymbol.relationships.addRelationship(.inheritsFrom(conformanceNodeReference))
         } else {
             conformingSymbol.relationships.addRelationship(.conformsTo(conformanceNodeReference, relationshipConstraints?.constraints))
         }
 
         if let conformanceSymbol = optionalConformanceNode?.semantic as? Symbol {
-            if let rawSymbol = conformingNode.symbol, rawSymbol.kind.identifier == SymbolGraph.Symbol.Kind.Swift.protocol.rawValue {
+            if let rawSymbol = conformingNode.symbol, rawSymbol.kind.identifier == .protocol {
                 conformanceSymbol.relationships.addRelationship(.inheritedBy(.successfullyResolved(conformingNode.reference)))
             } else {
                 conformanceSymbol.relationships.addRelationship(.conformingType(.successfullyResolved(conformingNode.reference), relationshipConstraints?.constraints))

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphLoader.swift

@@ -22,11 +22,7 @@ extension String {
 public struct SymbolReference {
     /// Returns `true` if the symbol is a known graph leaf symbol.
     static func isLeaf(_ symbol: SymbolGraph.Symbol) -> Bool {
-        guard let swiftKind = SymbolGraph.Symbol.Kind.Swift(rawValue: symbol.kind.identifier) else {
-            return true
-        }
-        
-        return !swiftKind.symbolCouldHaveChildren
+        return !symbol.kind.identifier.swiftSymbolCouldHaveChildren
     }
 
     /// Creates a new reference to a symbol.
@@ -56,15 +52,15 @@ public struct SymbolReference {
         }
 
         // A module reference does not have path as it's a root symbol in the topic graph.
-        if symbol.kind.identifier == SymbolGraph.Symbol.Kind.Swift.module.rawValue {
+        if symbol.kind.identifier == SymbolGraph.Symbol.KindIdentifier.module {
             path = ""
             return
         }
 
         var name = symbol.pathComponents.joinedSymbolPathComponents
 
         if shouldAddKind {
-            name = name.appending("-\(symbol.kind.identifier)")
+            name = name.appending("-\(symbol.identifier.interfaceLanguage).\(symbol.kind.identifier.identifier)")
         }
         if shouldAddHash {
             name = name.appendingHashedIdentifier(identifier)

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphRelationshipsBuilder.swift

@@ -224,10 +224,10 @@ extension AbsoluteSymbolLink.LinkComponent {
         case kindAndPreciseIdentifier(
             kindIdentifier: String, preciseIdentifierHash: String
         )
-        
-        private static let knownSymbolKindIdentifiers: Set<String> = {
-            Set(SymbolGraph.Symbol.Kind.Swift.allCases.map(\.rawValue))
-        }()
+
+        private static func isKnownSymbolKindIdentifier(identifier: String) -> Bool {
+            return SymbolGraph.Symbol.KindIdentifier.isKnownIdentifier(identifier)
+        }
 
         /// Creates a disambiguation suffix based on the given kind and precise
         /// identifiers.
@@ -261,7 +261,7 @@ extension AbsoluteSymbolLink.LinkComponent {
             if splitSuffix.count == 1 && splitSuffix[0] == string {
                 // The string didn't contain a "-" so now we check
                 // to see if the hash is a known symbol kind identifier.
-                if Self.knownSymbolKindIdentifiers.contains(string) {
+                if Self.isKnownSymbolKindIdentifier(identifier: string) {
                     self = .kindIdentifier(string)
                 } else {
                     // Since we've confirmed that it's not a symbol kind identifier
@@ -274,7 +274,7 @@ extension AbsoluteSymbolLink.LinkComponent {
                 //
                 // We expect the symbol kind identifier to come first, followed
                 // by a hash of the symbol's precise identifier.
-                if Self.knownSymbolKindIdentifiers.contains(String(splitSuffix[0])) {
+                if Self.isKnownSymbolKindIdentifier(identifier: String(splitSuffix[0])) {
                     self = .kindAndPreciseIdentifier(
                         kindIdentifier: String(splitSuffix[0]),
                         preciseIdentifierHash: String(splitSuffix[1])

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolReference.swift

@@ -175,10 +175,44 @@ extension SymbolGraph.Symbol: DocCSymbolRepresentable {
     }
 
     public var kindIdentifier: String? {
-        self.kind.identifier
+        "\(self.identifier.interfaceLanguage).\(self.kind.identifier.identifier)"
     }
 
     public static func == (lhs: SymbolGraph.Symbol, rhs: SymbolGraph.Symbol) -> Bool {
         lhs.identifier.precise == rhs.identifier.precise
     }
 }
+
+extension UnifiedSymbolGraph.Symbol: DocCSymbolRepresentable {
+    public var preciseIdentifier: String? {
+        self.uniqueIdentifier
+    }
+
+    public var title: String {
+        guard let selector = self.defaultSelector else {
+            fatalError("""
+                Failed to find a supported default selector. \
+                Language unsupported or corrupt symbol graph provided.
+                """
+            )
+        }
+
+        return self.names[selector]!.title
+    }
+
+    public var kindIdentifier: String? {
+        guard let selector = self.defaultSelector else {
+            fatalError("""
+                Failed to find a supported default selector. \
+                Language unsupported or corrupt symbol graph provided.
+                """
+            )
+        }
+
+        return "\(selector.interfaceLanguage).\(self.kind[selector]!.identifier.identifier)"
+    }
+
+    public static func == (lhs: UnifiedSymbolGraph.Symbol, rhs: UnifiedSymbolGraph.Symbol) -> Bool {
+        lhs.uniqueIdentifier == rhs.uniqueIdentifier
+    }
+}

Sources/SwiftDocC/Infrastructure/Symbol Link Resolution/AbsoluteSymbolLink.swift

@@ -28,7 +28,7 @@ public struct AutomaticCuration {
     }
 
     /// A mapping between a symbol kind and its matching group.
-    typealias ReferenceGroupIndex = [SymbolGraph.Symbol.Kind.Swift: ReferenceGroup]
+    typealias ReferenceGroupIndex = [SymbolGraph.Symbol.KindIdentifier: ReferenceGroup]
 
     /// A static list of predefined groups for each supported kind of symbol.
     static var groups: ReferenceGroupIndex {
@@ -65,12 +65,9 @@ public struct AutomaticCuration {
                 }
 
                 let childNode = try context.entity(with: child.reference)
-                guard let childSymbol = childNode.semantic as? Symbol,
-                    let swiftKind = SymbolGraph.Symbol.Kind.Swift(rawValue: childSymbol.kind.identifier) else {
-                    return
+                if let childSymbol = childNode.semantic as? Symbol {
+                    groupsIndex[childSymbol.kind.identifier]?.references.append(child.reference)
                 }
-                
-                groupsIndex[swiftKind]?.references.append(child.reference)
             }
             .lazy
             // Sort the groups in the order intended for rendering
@@ -137,7 +134,7 @@ extension AutomaticCuration {
     /// Returns a topics group title for the given symbol kind.
     /// - Parameter symbolKind: A symbol kind, such as a protocol or a variable.
     /// - Returns: A group title for symbols of the given kind.
-    static func groupTitle(`for` symbolKind: SymbolGraph.Symbol.Kind.Swift) -> String {
+    static func groupTitle(`for` symbolKind: SymbolGraph.Symbol.KindIdentifier) -> String {
         switch symbolKind {
             case .`associatedtype`: return "Associated Types"
             case .`class`: return "Classes"
@@ -158,11 +155,12 @@ extension AutomaticCuration {
             case .`typealias`: return "Type Aliases"
             case .`var`: return "Variables"
             case .module: return "Modules"
+            case .unknown: return "Symbols"
         }
     }
 
     /// The order of symbol kinds when grouped automatically.
-    static let groupKindOrder: [SymbolGraph.Symbol.Kind.Swift] = [
+    static let groupKindOrder: [SymbolGraph.Symbol.KindIdentifier] = [
         .module,
 
         .`class`,

Sources/SwiftDocC/Infrastructure/Symbol Link Resolution/DocCSymbolRepresentable.swift

@@ -30,7 +30,8 @@ struct TopicGraph {
     class Node: Hashable, CustomDebugStringConvertible {
         /// The location of the node's contents.
         enum ContentLocation: Hashable {
-            
+
+            // TODO: make this take multiple URLs?
             /// The node exists as a whole file at some URL.
             case file(url: URL)