correct the invalid namespaces recorded by lib/SymbolGraphGen

Author: tayloraswift

Sources/SymbolGraphCompiler/Declarations/SSGC.DeclObject.swift

@@ -13,9 +13,9 @@ extension SSGC
     class DeclObject
     {
         let conditions:Set<GenericConstraint<Symbol.Decl>>
-        let namespace:Symbol.Module
+        var namespace:Symbol.Module
         let culture:Symbol.Module
-        let access:Symbol.ACL
+        var access:Symbol.ACL
 
         /// The outer set is populated by redundant implicit conformances produced by
         /// lib/SymbolGraphGen.

Sources/SymbolGraphCompiler/Declarations/SSGC.Declarations.swift

@@ -24,10 +24,12 @@ extension SSGC
 }
 extension SSGC.Declarations
 {
+    /// Returns the declaration object, or nil if it has already been indexed, or does not meet
+    /// the minimum visibility threshold.
     mutating
     func include(_ vertex:SymbolGraphPart.Vertex,
         namespace:Symbol.Module,
-        culture:Symbol.Module) -> SSGC.DeclObject
+        culture:Symbol.Module) -> SSGC.DeclObject?
     {
         guard
         case .scalar(let symbol) = vertex.usr,
@@ -37,11 +39,12 @@ extension SSGC.Declarations
             fatalError("vertex is not a decl!")
         }
 
-        let decl:SSGC.DeclObject =
+        let decl:SSGC.DeclObject? =
         {
-            if  let decl:SSGC.DeclObject = $0
+            guard case nil = $0
+            else
             {
-                return decl
+                return nil
             }
 
             var kinks:Phylum.Decl.Kinks = []
@@ -72,7 +75,7 @@ extension SSGC.Declarations
                     comment: vertex.doccomment.map { .init($0.text, at: $0.start) } ?? nil))
 
             $0 = decl
-            return decl
+            return decl.access < self.threshold ? nil : decl
 
         } (&self.decls[symbol])
 

Sources/SymbolGraphCompiler/SSGC.TypeChecker.swift

@@ -76,7 +76,7 @@ extension SSGC.TypeChecker
         /// We use this to look up protocols by name instead of symbol. This is needed in order
         /// to work around some bizarre lib/SymbolGraphGen bugs.
         var protocolsByName:[UnqualifiedPath: Symbol.Decl] = [:]
-        var children:[SSGC.DeclObject] = []
+        var children:[Int: [SSGC.DeclObject]] = [:]
         //  Pass I. Gather scalars, extension blocks, and extension relationships.
         for part:SSGC.SymbolDump in culture.symbols
         {
@@ -91,33 +91,40 @@ extension SSGC.TypeChecker
                     switch vertex.usr
                     {
                     case .block(let symbol):
-                    //  We *do* in fact care about extension blocks that only contain
-                    //  internal/private members, because they might contain a conformance
-                    //  to an internal protocol that inherits from a public protocol.
-                    //  SymbolGraphGen probably shouldn’t be marking these extension blocks
-                    //  as internal, but SymbolGraphGen doesn’t care what we think.
+                        //  We *do* in fact care about extension blocks that only contain
+                        //  internal/private members, because they might contain a conformance
+                        //  to an internal protocol that inherits from a public protocol.
+                        //  SymbolGraphGen probably shouldn’t be marking these extension blocks
+                        //  as internal, but SymbolGraphGen doesn’t care what we think.
                         self.extensions.include(vertex,
                             extending: try extensions.extendee(of: symbol),
                             culture: id)
 
                     case .scalar(let symbol):
+                        guard
                         let decl:SSGC.DeclObject = self.declarations.include(vertex,
                             namespace: namespace,
                             culture: id)
+                        else
+                        {
+                            //  Declaration is private or re-exported.
+                            continue
+                        }
 
                         if  case .decl(.protocol) = vertex.phylum
                         {
                             protocolsByName[vertex.path] = symbol
                         }
-                        else if !decl.value.path.prefix.isEmpty
+
+                        let depth:Int = decl.value.path.prefix.count
+                        if  depth > 0
                         {
-                            children.append(decl)
+                            children[depth, default: []].append(decl)
                         }
-
-                        if  decl.culture == id
+                        else
                         {
-                            //  If this is not a re-exported symbol, make it available for
-                            //  link resolution.
+                            //  We need to wait until the next pass for the nested declarations,
+                            //  because we do not know if their namespaces are correct yet.
                             self.resolvableLinks[namespace, decl.value.path].append(
                                 .decl(decl.value))
                         }
@@ -154,15 +161,15 @@ extension SSGC.TypeChecker
                 try nesting.do { try self.assign($0, by: id) }
             }
         }
-        //  SymbolGraphGen fails to emit a `memberOf` edge if the member is a default
+        //  lib/SymbolGraphGen fails to emit a `memberOf` edge if the member is a default
         //  implementation of a protocol requirement. Because the requirement might be a
         //  requirement from a different protocol than the protocol containing the default
         //  implementation, this means we need to use lexical name lookup to resolve the true
         //  parent of the default implementation.
         //
         //  Luckily for us, this lib/SymbolGraphGen bug only seems to affect default
         //  implementations that implement requirements from protocols in the current module.
-        for decl:SSGC.DeclObject in children
+        for decl:SSGC.DeclObject in children.values.joined()
         {
             guard decl.scopes.isEmpty,
             let parent:UnqualifiedPath = .init(decl.value.path.prefix),
@@ -176,6 +183,39 @@ extension SSGC.TypeChecker
 
             try self.assign(inferred, by: id)
         }
+        //  lib/SymbolGraphGen will place nested declarations under the wrong namespace if the
+        //  outer type was re-exported from another module. This is a bug in lib/SymbolGraphGen.
+        //  There is an alternative source of this information, in the `extendedModule` field of
+        //  the extension context, but this field is only present for declarations that are
+        //  physically written in an extension block, and also does not specify the correct
+        //  namespace for types under more than one level of nesting.
+        //
+        //  Therefore, we need to correct the namespaces by actually inspecting the extended
+        //  types of nested declarations. It is most efficient to visit the shallower
+        //  declarations first, as this avoids the need to traverse the entire path hierarchy.
+        for (_, decls):(Int, [SSGC.DeclObject]) in children.sorted(by: { $0.key < $1.key })
+        {
+            for decl:SSGC.DeclObject in decls
+            {
+                guard
+                let scope:Symbol.Decl = decl.scopes.first,
+                let scope:SSGC.DeclObject = self.declarations[visible: scope]
+                else
+                {
+                    //  If we can’t find the parent, this symbol is probably a public member of
+                    //  a private type, which is a common bug in lib/SymbolGraphGen.
+                    decl.access = .private
+                    continue
+                }
+
+                let namespace:Symbol.Module = scope.namespace
+
+                decl.access = min(decl.access, scope.access)
+                decl.namespace = namespace
+
+                self.resolvableLinks[namespace, decl.value.path].append(.decl(decl.value))
+            }
+        }
 
         //  Pass II. Populate remaining relationships.
         for part:SSGC.SymbolDump in culture.symbols

Sources/SymbolGraphParts/Vertices/SymbolGraphPart.Vertex.ExtensionContext.swift

@@ -26,12 +26,15 @@ extension SymbolGraphPart.Vertex.ExtensionContext:JSONObjectDecodable
     public
     enum CodingKey:String, Sendable
     {
-        case conditions = "constraints"
+        case constraints
+
+        @available(*, unavailable, message: "Not useful")
+        case extendedModule
     }
 
     public
     init(json:JSON.ObjectDecoder<CodingKey>) throws
     {
-        self.init(conditions: try json[.conditions]?.decode() ?? [])
+        self.init(conditions: try json[.constraints]?.decode() ?? [])
     }
 }

Sources/SymbolGraphParts/Vertices/SymbolGraphPart.Vertex.swift

@@ -155,19 +155,19 @@ extension SymbolGraphPart.Vertex:JSONObjectDecodable
     public
     enum CodingKey:String, Sendable
     {
-        case acl = "accessLevel"
+        case accessLevel
         case availability
 
-        case declaration = "declarationFragments"
-        case doccomment = "docComment"
+        case declarationFragments
+        case docComment
 
-        case `extension` = "swiftExtension"
-        case generics = "swiftGenerics"
+        case swiftExtension
+        case swiftGenerics
 
         case names
         enum Names:String, Sendable
         {
-            case subheading = "subHeading"
+            case subHeading
         }
 
         case identifier
@@ -176,8 +176,8 @@ extension SymbolGraphPart.Vertex:JSONObjectDecodable
             case precise
         }
 
-        case interfaces = "spi"
-        case path = "pathComponents"
+        case spi
+        case pathComponents
         case kind
         enum Kind:String, Sendable
         {
@@ -187,12 +187,12 @@ extension SymbolGraphPart.Vertex:JSONObjectDecodable
         case location
         enum Location:String, Sendable
         {
-            case file = "uri"
+            case uri
             case position
             enum Position:String, Sendable
             {
                 case line
-                case column = "character"
+                case character
             }
         }
     }
@@ -205,23 +205,23 @@ extension SymbolGraphPart.Vertex:JSONObjectDecodable
             {
                 try $0[.precise].decode()
             },
-            acl: try json[.acl].decode(),
+            acl: try json[.accessLevel].decode(),
             phylum: try json[.kind].decode(using: CodingKey.Kind.self)
             {
                 try $0[.identifier].decode()
             },
             availability: try json[.availability]?.decode() ?? .init(),
-            doccomment: try json[.doccomment]?.decode(),
-            interfaces: try json[.interfaces]?.decode(as: Bool.self) { $0 ? .init() : nil },
-            extension: try json[.extension]?.decode() ?? .init(),
-            fragments: try json[.declaration].decode(),
-            generics: try json[.generics]?.decode() ?? .init(),
+            doccomment: try json[.docComment]?.decode(),
+            interfaces: try json[.spi]?.decode(as: Bool.self) { $0 ? .init() : nil },
+            extension: try json[.swiftExtension]?.decode() ?? .init(),
+            fragments: try json[.declarationFragments].decode(),
+            generics: try json[.swiftGenerics]?.decode() ?? .init(),
             location: try json[.location]?.decode(using: CodingKey.Location.self)
             {
                 let (line, column):(Int, Int) = try $0[.position].decode(
                     using: CodingKey.Location.Position.self)
                 {
-                    (try $0[.line].decode(), try $0[.column].decode())
+                    (try $0[.line].decode(), try $0[.character].decode())
                 }
                 guard
                 let position:SourcePosition = .init(line: line, column: column)
@@ -231,8 +231,8 @@ extension SymbolGraphPart.Vertex:JSONObjectDecodable
                     return nil
                 }
 
-                return .init(position: position, file: try .uri(file: try $0[.file].decode()))
+                return .init(position: position, file: try .uri(file: try $0[.uri].decode()))
             },
-            path: try json[.path].decode())
+            path: try json[.pathComponents].decode())
     }
 }