Fix a bug where article-only catalogs couldn't resolve external links (#1013)

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+Find.swift

@@ -90,7 +90,7 @@ extension PathHierarchy {
                         // Ignore this error and raise an error about not finding the module instead.
                         break
                     case .unknownName(let partialResult, remaining: _, availableChildren: _):
-                        if partialResult.node.symbol?.kind.identifier == .module {
+                        if modules.contains(where: { $0.identifier == partialResult.node.identifier }) {
                             // Failed to find the first path component. Ignore this error and raise an error about not finding the module instead.
                             break
                         } else {

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -5340,6 +5340,78 @@ let expected = """
             }
         }
     }
+    
+    func testResolveExternalLinkFromTechnologyRoot() throws {
+        enableFeatureFlag(\.isExperimentalLinkHierarchySerializationEnabled)
+        
+        let externalModuleName = "ExternalModuleName"
+        
+        func makeExternalResolver() throws -> ExternalPathHierarchyResolver {
+            let (bundle, context) = try loadBundle(
+                catalog: Folder(name: "Dependency.docc", content: [
+                    JSONFile(name: "\(externalModuleName).symbols.json", content: makeSymbolGraph(moduleName: externalModuleName)),
+                    TextFile(name: "Extension.md", utf8Content: """
+                    # ``\(externalModuleName)``
+                    
+                    Some description of this module.
+                    """)
+                ])
+            )
+            
+            // Retrieve the link information from the dependency, as if '--enable-experimental-external-link-support' was passed to DocC
+            let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+            let linkSummaries: [LinkDestinationSummary] = try context.knownPages.flatMap { reference in
+                let entity = try context.entity(with: reference)
+                let renderNode = try XCTUnwrap(converter.convert(entity))
+                
+                return entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode, includeTaskGroups: false)
+            }
+            let linkResolutionInformation = try context.linkResolver.localResolver.prepareForSerialization(bundleID: bundle.identifier)
+            
+            return ExternalPathHierarchyResolver(linkInformation: linkResolutionInformation, entityInformation: linkSummaries)
+        }
+        
+        let catalog = Folder(name: "unit-test.docc", content: [
+            TextFile(name: "Root.md", utf8Content: """
+            # Some root page
+            
+            A single-file article-only catalog.
+            
+            This root links to an external module ``/\(externalModuleName)``
+            """),
+        ])
+        
+        let (_, bundle, context) = try loadBundle(from: createTempFolder(content: [catalog])) { context in
+            context.linkResolver.externalResolvers = [externalModuleName: try makeExternalResolver()]
+        }
+        
+        XCTAssert(context.problems.isEmpty, "Unexpected problems: \(context.problems.map(\.diagnostic.summary))")
+        let reference = try XCTUnwrap(context.soleRootModuleReference)
+        let node = try context.entity(with: reference)
+        
+        let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+        let renderNode = try converter.convert(node)
+        
+        let externalReference = "doc://Dependency/documentation/ExternalModuleName"
+        
+        // Verify that the rendered page contains the resolved reference
+        let discussionSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
+        XCTAssertEqual(discussionSection.content, [
+            .heading(.init(level: 2, text: "Overview", anchor: "overview")),
+            
+            .paragraph(.init(inlineContent: [
+                .text("This root links to an external module "),
+                .reference(identifier: RenderReferenceIdentifier(externalReference), isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil)
+            ]))
+        ])
+        
+        // Verify that the rendered page has the render details about the resolved reference
+        XCTAssertEqual(renderNode.references.keys.sorted(), [externalReference])
+        
+        let externalRenderReference = try XCTUnwrap(renderNode.references[externalReference] as? TopicRenderReference)
+        XCTAssertEqual(externalRenderReference.title, externalModuleName)
+        XCTAssertEqual(externalRenderReference.abstract, [.text("Some description of this module.")])
+    }
 }
 
 func assertEqualDumps(_ lhs: String, _ rhs: String, file: StaticString = #file, line: UInt = #line) {

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -2476,6 +2476,32 @@ class PathHierarchyTests: XCTestCase {
         }
     }
 
+    func testResolveExternalLinkFromTechnologyRoot() throws {
+        enableFeatureFlag(\.isExperimentalLinkHierarchySerializationEnabled)
+        
+        let catalog = Folder(name: "unit-test.docc", content: [
+            TextFile(name: "Root.md", utf8Content: """
+            # Some root page
+            
+            A single-file article-only catalog
+            """),
+        ])
+        
+        let (_, _, context) = try loadBundle(from: createTempFolder(content: [catalog]))
+        let tree = context.linkResolver.localResolver.pathHierarchy
+        
+        let rootIdentifier = try XCTUnwrap(tree.modules.first?.identifier)
+        do {
+            _ = try tree.find(path: "/SomeModule", parent: rootIdentifier, onlyFindSymbols: true)
+            XCTFail("Unexpectedly found external symbol")
+        } catch PathHierarchy.Error.moduleNotFound(_, let remaining, _) {
+            // `LinkResolver` uses this error to know when to resolve a link from an external source.
+            XCTAssertEqual(remaining.map(\.full), ["SomeModule"])
+        } catch {
+            XCTFail("Unexpected error \(error)")
+        }
+    }
+    
     // MARK: Test helpers
 
     private func assertFindsPath(_ path: String, in tree: PathHierarchy, asSymbolID symbolID: String, file: StaticString = #file, line: UInt = #line) throws {