(#1257) Combined module link issue - public extension of dependent module causes resolution failure

The basic setup is this:

```swift
// ImportedModule
struct ExtendedType {}

struct BaseType {}
```

```swift
// MainModule
import ImportedModule

extension ExtendedType {
    func extensionMethod()
}
```

With the above we have the following issues:

- `/ImportedModule/ExtendedType` **always** resolves to the type extension link
- `/ImportModule/BaseType` links are broken

Prioritize absolute links resolution to point to the module referenced in the link, so that `/ImportedModule/BaseType` finds the base type because the path starts with `/`.

To refer to the extended type or method, the non-absolute paths work in Xcode and with docc: `ImportedModule/ExtendedType` resolves to the type extension page, `ImportedModule/ExtendedType/extensionMethod()` resolves to the extension method page.

> ‼️🤖 Disclaimer: this is an AI-assisted change.

While AI was utilized to identify and apply the initial fix and create initial version of the tests, the code has been reviewed and modified where needed.

More importantly, I have tested the changes both with the sample project attached to the original issue and with a real work project where I'm using `xcodebuild docbuild`.

In the real world project I'm dealing with similar setup.
`ParentFramework` imports `ChildFramework` and extends `ChildType` and then uses paths like `/ChildFramework/ChildType` in the documentation.

By passing `DOCC_EXEC` build setting to `xcodebuild docbuild` invocation along with `--enable-experimental-combined-documentation` and other required flags I was able to produce doc archives for the 2 modules, then `docc merge` them into one and in the resulting doc archive all cross-linking works as expected.
I can also ue `ChildFramework/ChildType/extensionMethod()` links to create reference to the extension method doc page.

Author: Max Grebenets

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

@@ -84,7 +84,9 @@ extension PathHierarchy {
             if let moduleMatch = modules.first(where: { $0.matches(firstComponent) }) {
                 return try searchForNode(descendingFrom: moduleMatch, pathComponents: remaining.dropFirst(), onlyFindSymbols: onlyFindSymbols, rawPathForError: rawPath)
             }
-            if modules.count == 1 {
+            // For absolute links, only use the single-module fallback if the first component doesn't match
+            // any module name
+            if modules.count == 1 && !isAbsolute {
                 do {
                     return try searchForNode(descendingFrom: modules.first!, pathComponents: remaining, onlyFindSymbols: onlyFindSymbols, rawPathForError: rawPath)
                 } catch {

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -3126,7 +3126,103 @@ class PathHierarchyTests: XCTestCase {
         try assertFindsPath("/MainModule/TopLevelProtocol/extensionMember(_:)", in: tree, asSymbolID: "extensionMember1")
         try assertFindsPath("/MainModule/TopLevelProtocol/InnerStruct/extensionMember(_:)", in: tree, asSymbolID: "extensionMember2")
     }
-    
+
+    func testAbsoluteLinksToOtherModuleWithExtensions() async throws {
+        enableFeatureFlag(\.isExperimentalLinkHierarchySerializationEnabled)
+
+        let importedProtocolID = "s:14ImportedModule12BaseProtocolP"
+        let importedTypeID = "s:14ImportedModule12ExtendedTypeV"
+        let extensionSymbolID = "s:e:s:14ImportedModule12ExtendedTypeV04MainC0E15extensionMethodyyF"
+        let extensionMethodID = "s:14ImportedModule12ExtendedTypeV04MainC0E15extensionMethodyyF"
+        let mainModuleTypeID = "s:10MainModule0A4TypeV"
+
+        let extensionMixin = SymbolGraph.Symbol.Swift.Extension(
+            extendedModule: "ImportedModule",
+            typeKind: .struct,
+            constraints: []
+        )
+
+        let catalog = Folder(name: "TestCatalog.docc", content: [
+            JSONFile(name: "MainModule.symbols.json", content: makeSymbolGraph(
+                moduleName: "MainModule",
+                symbols: [
+                    makeSymbol(id: mainModuleTypeID, kind: .struct, pathComponents: ["MainType"])
+                ]
+            )),
+            JSONFile(name: "[email protected]", content: makeSymbolGraph(
+                moduleName: "MainModule",
+                symbols: [
+                    makeSymbol(id: importedProtocolID, kind: .protocol, pathComponents: ["BaseProtocol"]),
+                    makeSymbol(id: importedTypeID, kind: .struct, pathComponents: ["ExtendedType"]),
+                    makeSymbol(
+                        id: extensionSymbolID,
+                        kind: .extension,
+                        pathComponents: ["ExtendedType"],
+                        otherMixins: [extensionMixin]
+                    ),
+                    makeSymbol(
+                        id: extensionMethodID,
+                        kind: .method,
+                        pathComponents: ["ExtendedType", "extensionMethod()"],
+                        otherMixins: [extensionMixin]
+                    )
+                ],
+                relationships: [
+                    .init(
+                        source: extensionMethodID,
+                        target: extensionSymbolID,
+                        kind: .memberOf,
+                        targetFallback: "ImportedModule.ExtendedType"
+                    ),
+                    .init(
+                        source: extensionSymbolID,
+                        target: importedTypeID,
+                        kind: .extensionTo,
+                        targetFallback: "ImportedModule.ExtendedType"
+                    )
+                ]
+            ))
+        ])
+
+        let (_, context) = try await loadBundle(catalog: catalog)
+        let tree = context.linkResolver.localResolver.pathHierarchy
+
+        XCTAssertEqual(tree.modules.count, 1)
+        XCTAssertEqual(tree.modules.first?.name, "MainModule")
+
+        let paths = tree.caseInsensitiveDisambiguatedPaths()
+        XCTAssertEqual(paths[importedProtocolID], "/MainModule/ImportedModule/BaseProtocol")
+        XCTAssertEqual(paths[importedTypeID], "/MainModule/ImportedModule/ExtendedType-struct")
+        XCTAssertEqual(
+            paths[extensionMethodID],
+            "/MainModule/ImportedModule/ExtendedType/extensionMethod()"
+        )
+
+        // Verify that symbols can be found at their correct paths
+        try assertFindsPath("/MainModule/ImportedModule/BaseProtocol", in: tree, asSymbolID: importedProtocolID)
+        try assertFindsPath("/MainModule/ImportedModule/ExtendedType-struct", in: tree, asSymbolID: importedTypeID)
+        try assertFindsPath(
+            "/MainModule/ImportedModule/ExtendedType/extensionMethod()",
+            in: tree,
+            asSymbolID: extensionMethodID
+        )
+
+        // Verify that absolute paths to non-existent modules throw moduleNotFound error
+        // This is the fix being tested: without it, single-module fallback would trigger incorrectly
+        try assertPathRaisesErrorMessage(
+            "/ImportedModule/BaseProtocol",
+            in: tree,
+            context: context,
+            expectedErrorMessage: "No module named 'ImportedModule'"
+        )
+        try assertPathRaisesErrorMessage(
+            "/ImportedModule/ExtendedType",
+            in: tree,
+            context: context,
+            expectedErrorMessage: "No module named 'ImportedModule'"
+        )
+    }
+
     func testMissingRequiredMemberOfSymbolGraphRelationshipInOneLanguageAcrossManyPlatforms() async throws {
         // We make a best-effort attempt to create a valid path hierarchy, even if the symbol graph inputs are not valid.