recover from an ambiguous codelink if there is only one possible overload

Author: tayloraswift

Sources/SymbolGraphLinker/Resolution/SSGC.OutlineDiagnostic.swift

@@ -1,10 +1,12 @@
+import FNV1
 import SourceDiagnostics
 import UCF
 
 extension SSGC
 {
     enum OutlineDiagnostic:Equatable, Error
     {
+        case annealedIncorrectHash(in:UCF.Selector, to:FNV24)
         case unresolvedAbsolute(Doclink)
         case suggestReformat(Doclink, to:UCF.Selector)
     }
@@ -17,8 +19,14 @@ extension SSGC.OutlineDiagnostic:Diagnostic
     {
         switch self
         {
+        case .annealedIncorrectHash(in: let selector, to: _):
+            output[.warning] = """
+            codelink '\(selector)' is unambiguous, but the hash does not match the resolved \
+            declaration
+            """
+
         case .unresolvedAbsolute(let doclink):
-            output[.note] = """
+            output[.warning] = """
             doclink '\(doclink)' does not resolve to any article (or tutorial) in this package
             """
 
@@ -33,6 +41,11 @@ extension SSGC.OutlineDiagnostic:Diagnostic
     {
         switch self
         {
+        case .annealedIncorrectHash(in: _, to: let hash):
+            output[.note] = """
+            replace the hash with [\(hash)] to suppress this warning
+            """
+
         case .unresolvedAbsolute:
             output[.note] = """
             absolute doclinks may only refer to articles (or tutorials), not to symbol \

Sources/SymbolGraphLinker/Resolution/SSGC.OutlineResolver.swift

@@ -293,34 +293,47 @@ extension SSGC.OutlineResolver
     func target(of codelink:UCF.Selector,
         at source:SourceReference<Markdown.Source>) -> (Int32, Int32?)?
     {
+        let chosen:any UCF.ResolvableOverload
+
         switch self.codelinks.resolve(codelink)
         {
-        case .ambiguous(let overloads, rejected: let rejected):
-            self.diagnostics[source] = UCF.ResolutionError<SSGC.Symbolicator>.init(
-                overloads: overloads,
-                rejected: rejected,
-                selector: codelink)
-
-            return nil
+        case .module(let module):
+            return (self.tables.intern(module) * .module, nil)
 
         case .overload(let overload as UCF.PackageOverload):
             return (overload.decl, overload.heir)
 
         case .overload(let overload):
-            let decl:Int32 = self.tables.intern(overload.id)
+            chosen = overload
 
-            if  case let overload as UCF.CausalOverload = overload,
-                let heir:Symbol.Decl = overload.heir
-            {
-                return (decl, self.tables.intern(heir))
-            }
+        case .ambiguous(let overloads, rejected: let rejected):
+            guard overloads.isEmpty, rejected.count == 1
             else
             {
-                return (decl, nil)
+                self.diagnostics[source] = UCF.ResolutionError<SSGC.Symbolicator>.init(
+                    overloads: overloads,
+                    rejected: rejected,
+                    selector: codelink)
+                return nil
             }
 
-        case .module(let module):
-            return (self.tables.intern(module) * .module, nil)
+            chosen = rejected[0]
+
+            self.diagnostics[source] = SSGC.OutlineDiagnostic.annealedIncorrectHash(
+                in: codelink,
+                to: chosen.hash)
+        }
+
+        let decl:Int32 = self.tables.intern(chosen.id)
+
+        if  case let chosen as UCF.CausalOverload = chosen,
+            let heir:Symbol.Decl = chosen.heir
+        {
+            return (decl, self.tables.intern(heir))
+        }
+        else
+        {
+            return (decl, nil)
         }
     }
 }