add unknown.extension and inContextOf relationship + adapt transformation to build context hierarchy

Author: theMomax

Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift

@@ -247,7 +247,8 @@ extension CoverageDataEntry {
                 .extendedClass,
                 .extendedStructure,
                 .extendedEnumeration,
-                .extendedProtocol:
+                .extendedProtocol,
+                .unknownExtendedType:
                 self = .types
             case .localVariable,
                 .instanceProperty,

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -1025,7 +1025,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     private func parentChildRelationship(from edge: SymbolGraph.Relationship) -> (ResolvedTopicReference, ResolvedTopicReference)? {
         // Filter only parent <-> child edges
         switch edge.kind {
-        case .memberOf, .requirementOf, .declaredIn:
+        case .memberOf, .requirementOf, .declaredIn, .inContextOf:
             guard let parentRef = symbolIndex[edge.target]?.reference, let childRef = symbolIndex[edge.source]?.reference else {
             return nil
             }

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

@@ -76,6 +76,8 @@ extension ExternalSymbolResolver {
             symbolKind = .extendedEnumeration
         case .extendedProtocol:
             symbolKind = .extendedProtocol
+        case .unknownExtendedType:
+            symbolKind = .unknownExtendedType
 
         // There shouldn't be any reason for a symbol graph file to reference one of these kinds outside of the symbol graph itself.
         // Return `.class` as the symbol kind (acting as "any symbol") so that the render reference gets a "symbol" role.

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

@@ -14,6 +14,8 @@ import SymbolKit
 
 extension SymbolGraph.Relationship.Kind {
     static let declaredIn = Self(rawValue: "declaredIn")
+    
+    static let inContextOf = Self(rawValue: "inContextOf")
 }
 
 // MARK: Custom Symbol Kind Identifiers
@@ -27,6 +29,8 @@ extension SymbolGraph.Symbol.KindIdentifier {
 
     static let extendedEnumeration = Self(rawValue: "enum.extension")
 
+    static let unknownExtendedType = Self(rawValue: "unknown.extension")
+    
     static let extendedModule = Self(rawValue: "module.extension")
 
     init?(extending other: Self) {
@@ -72,9 +76,11 @@ extension SymbolGraph.Symbol.Kind {
         case .some(.extendedEnumeration):
             return Self(parsedIdentifier: .extendedEnumeration, displayName: "Extended Enumeration")
         default:
-            return Self(rawIdentifier: "unknown.extension", displayName: "Extended Type")
+            return unknownExtendedType
         }
     }
+    
+    static let unknownExtendedType = Self(parsedIdentifier: .unknownExtendedType, displayName: "Extended Type")
 }
 
 

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

@@ -194,7 +194,9 @@ extension ExtendedTypesFormatTransformation {
 
         var (extendedTypeSymbols,
              extensionBlockToExtendedTypeMapping,
-             extendedTypeToExtensionBlockMapping) = synthesizeExtendedTypeSymbols(using: extensionBlockSymbols, extensionToRelationships)
+             extendedTypeToExtensionBlockMapping) = synthesizePrimaryExtendedTypeSymbols(using: extensionBlockSymbols, extensionToRelationships)
+        
+        let contextOfRelationships = synthesizeSecondaryExtendedTypeSymbols(&extendedTypeSymbols)
 
         redirect(\.target, of: &memberOfRelationships, using: extensionBlockToExtendedTypeMapping)
 
@@ -217,12 +219,79 @@ extension ExtendedTypesFormatTransformation {
 
         symbolGraph.relationships.append(contentsOf: memberOfRelationships)
         symbolGraph.relationships.append(contentsOf: conformsToRelationships)
+        symbolGraph.relationships.append(contentsOf: contextOfRelationships)
         extendedTypeSymbols.values.forEach { symbol in symbolGraph.symbols[symbol.identifier.precise] = symbol }
 
-        try synthesizeExtendedModuleSymbolsAndDeclaredInRelationships(on: &symbolGraph, using: extendedTypeSymbols.values.map(\.identifier.precise))
+        try synthesizeExtendedModuleSymbolsAndDeclaredInRelationships(on: &symbolGraph, using: extendedTypeSymbols.values.filter { symbol in symbol.pathComponents.count == 2 }.map(\.identifier.precise))
 
         return true
     }
+    
+    private static func synthesizeSecondaryExtendedTypeSymbols(_ extendedTypeSymbols: inout [String: SymbolGraph.Symbol]) -> [SymbolGraph.Relationship] {
+        let sortedKeys: [(pathComponents: [String], preciseId: String)] = extendedTypeSymbols.map { key, value in
+            (value.pathComponents, key)
+        }.sorted(by: { a, b in a.pathComponents.count <= b.pathComponents.count && a.preciseId < b.preciseId })
+        
+        var pathComponentsToSymbolIds: [ArraySlice<String>: String] = [:]
+        pathComponentsToSymbolIds.reserveCapacity(extendedTypeSymbols.count)
+        for (key, symbol) in extendedTypeSymbols {
+            pathComponentsToSymbolIds[symbol.pathComponents[1...]] = key
+        }
+        
+        func lookupSymbol(_ pathComponents: ArraySlice<String>) -> SymbolGraph.Symbol? {
+            guard let id = pathComponentsToSymbolIds[pathComponents] else {
+                return nil
+            }
+            
+            return extendedTypeSymbols[id]
+        }
+        
+        var relationships = [SymbolGraph.Relationship]()
+        var symbolIsConnectedToParent = [String: Bool]()
+        symbolIsConnectedToParent.reserveCapacity(extendedTypeSymbols.count)
+        
+        for (pathComponents, preciseId) in sortedKeys {
+            guard var symbol = extendedTypeSymbols[preciseId] else {
+                continue
+            }
+            
+            let modulePrefix = pathComponents[0]
+            var pathComponents = pathComponents[1..<pathComponents.count-1]
+            
+            while !pathComponents.isEmpty {
+                let parent = lookupSymbol(pathComponents)?.replacing(\.accessLevel) { oldSymbol in
+                    max(oldSymbol.accessLevel, symbol.accessLevel)
+                } ?? SymbolGraph.Symbol(identifier: .init(precise: "s:e:" + symbol.identifier.precise,
+                                                          interfaceLanguage: symbol.identifier.interfaceLanguage),
+                                        names: .init(title: pathComponents.joined(separator: "."),
+                                                navigator: pathComponents.last?.asDeclarationFragment(.identifier),
+                                                subHeading: nil,
+                                                prose: nil),
+                                        pathComponents: [modulePrefix] + pathComponents,
+                                        docComment: nil,
+                                        accessLevel: symbol.accessLevel,
+                                        kind: .unknownExtendedType,
+                                        mixins: symbol.mixins.keeping(SymbolGraph.Symbol.Swift.Extension.mixinKey))
+                
+                
+                pathComponentsToSymbolIds[pathComponents] = parent.identifier.precise
+                extendedTypeSymbols[parent.identifier.precise] = parent
+                
+                if !symbolIsConnectedToParent[symbol.identifier.precise, default: false] {
+                    relationships.append(.init(source: symbol.identifier.precise,
+                                               target: parent.identifier.precise,
+                                               kind: .inContextOf,
+                                               targetFallback: parent.title))
+                    symbolIsConnectedToParent[symbol.identifier.precise] = true
+                }
+                
+                symbol = parent
+                pathComponents.removeLast()
+            }
+        }
+        
+        return relationships
+    }
 
     /// Tries to obtain `docComment`s for all `targets` and copies the documentaiton from sources to the target.
     ///
@@ -344,7 +413,7 @@ extension ExtendedTypesFormatTransformation {
     ///
     /// - Returns: - the created extended type symbols keyed by their precise identifier, along with a bidirectional
     /// mapping between the extended type symbols and the `.extension` symbols
-    private static func synthesizeExtendedTypeSymbols<RS: Sequence>(using extensionBlockSymbols: [String: SymbolGraph.Symbol],
+    private static func synthesizePrimaryExtendedTypeSymbols<RS: Sequence>(using extensionBlockSymbols: [String: SymbolGraph.Symbol],
                                                      _ extensionToRelationships: RS)
     -> (extendedTypeSymbols: [String: SymbolGraph.Symbol],
         extensionBlockToExtendedTypeMapping: [String: String],
@@ -354,10 +423,11 @@ extension ExtendedTypesFormatTransformation {
         var extendedTypeSymbols: [String: SymbolGraph.Symbol] = [:]
         var extensionBlockToExtendedTypeMapping: [String: String] = [:]
         var extendedTypeToExtensionBlockMapping: [String: [String]] = [:]
+        var pathComponentToExtendedTypeMapping: [ArraySlice<String>: String] = [:]
 
         extensionBlockToExtendedTypeMapping.reserveCapacity(extensionBlockSymbols.count)
 
-        let createExtendedTypeSymbol = { (extensionBlockSymbol: SymbolGraph.Symbol, id: String) -> SymbolGraph.Symbol in
+        let createExtendedTypeSymbolAndAnchestors = { (extensionBlockSymbol: SymbolGraph.Symbol, id: String) -> SymbolGraph.Symbol in
             var newMixins = [String: Mixin]()
 
             if var swiftExtension = extensionBlockSymbol[mixin: SymbolGraph.Symbol.Swift.Extension.self] {
@@ -408,13 +478,14 @@ extension ExtendedTypesFormatTransformation {
 
             let symbol: SymbolGraph.Symbol = extendedTypeSymbols[extendedSymbolId]?.replacing(\.accessLevel) { oldSymbol in
                 max(oldSymbol.accessLevel, extensionBlockSymbol.accessLevel)
-            } ?? createExtendedTypeSymbol(extensionBlockSymbol, extendedSymbolId)
+            } ?? createExtendedTypeSymbolAndAnchestors(extensionBlockSymbol, extendedSymbolId)
+            
+            pathComponentToExtendedTypeMapping[symbol.pathComponents[...]] = symbol.identifier.precise
 
             extendedTypeSymbols[symbol.identifier.precise] = symbol
 
             extensionBlockToExtendedTypeMapping[extensionTo.source] = symbol.identifier.precise
-            extendedTypeToExtensionBlockMapping[symbol.identifier.precise]
-            = (extendedTypeToExtensionBlockMapping[symbol.identifier.precise] ?? []) + [extensionBlockSymbol.identifier.precise]
+            extendedTypeToExtensionBlockMapping[symbol.identifier.precise, default: []] += [extensionBlockSymbol.identifier.precise]
         }
 
         return (extendedTypeSymbols, extensionBlockToExtendedTypeMapping, extendedTypeToExtensionBlockMapping)
@@ -522,3 +593,21 @@ private extension SymbolGraph.Relationship {
         return new
     }
 }
+
+private extension String {
+    func asDeclarationFragment(_ kind: SymbolGraph.Symbol.DeclarationFragments.Fragment.Kind) -> [SymbolGraph.Symbol.DeclarationFragments.Fragment] {
+        [.init(kind: kind, spelling: self, preciseIdentifier: nil)]
+    }
+}
+
+private extension Dictionary {
+    func keeping(_ keys: Key...) -> Self {
+        var new = Self()
+        
+        for key in keys {
+            new[key] = self[key]
+        }
+        
+        return new
+    }
+}

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

@@ -135,6 +135,10 @@ struct SymbolGraphLoader {
 
         // feed the loaded graphs into the `graphLoader`
         for (url, (_, graph)) in loadedGraphs {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = .prettyPrinted
+            print(url.absoluteString)
+            print(String(data: try! encoder.encode(graph), encoding: .utf8)!)
             graphLoader.mergeSymbolGraph(graph, at: url)
         }
 

Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift

@@ -209,6 +209,7 @@ extension AutomaticCuration {
             case .extendedStructure: return "Extended Structures"
             case .extendedEnumeration: return "Extended Enumerations"
             case .extendedProtocol: return "Extended Protocols"
+            case .unknownExtendedType: return "Extended Types"
             default: return "Symbols"
         }
     }
@@ -244,5 +245,6 @@ extension AutomaticCuration {
         .extendedProtocol,
         .extendedStructure,
         .extendedEnumeration,
+        .unknownExtendedType,
     ]
 }

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -473,6 +473,7 @@ public struct DocumentationNode {
         case .extendedClass: return .extendedClass
         case .extendedEnumeration: return .extendedEnumeration
         case .extendedProtocol: return .extendedProtocol
+        case .unknownExtendedType: return .unknownExtendedType
         default: return .unknown
         }
     }

Sources/SwiftDocC/Model/Kind.swift

@@ -165,6 +165,8 @@ extension DocumentationNode.Kind {
     public static let extendedEnumeration = DocumentationNode.Kind(name: "Extended Enumeration", id: "org.swift.docc.kind.extendedEnumeration", isSymbol: true)
 
     public static let extendedProtocol = DocumentationNode.Kind(name: "Extended Protocol", id: "org.swift.docc.kind.extendedProtocol", isSymbol: true)
+    
+    public static let unknownExtendedType = DocumentationNode.Kind(name: "Extended Type", id: "org.swift.docc.kind.unknownExtendedType", isSymbol: true)
 
     /// The list of all known kinds of documentation nodes.
     /// - Note: The `unknown` value is not included.
@@ -182,7 +184,7 @@ extension DocumentationNode.Kind {
         // Data
         .buildSetting, .propertyListKey,
         // Extended Symbols
-        .extendedModule, .extendedStructure, .extendedClass, .extendedEnumeration, .extendedProtocol,
+        .extendedModule, .extendedStructure, .extendedClass, .extendedEnumeration, .extendedProtocol, .unknownExtendedType,
         // Other
         .keyword, .restAPI, .tag, .propertyList, .object
     ]