Add logic to look for overload groups when emitting warnings and

suggestions about ambiguous symbols. If exactly one of the ambiguous
symbols is an overload group, then suggest the author simply remove
the incorrect disambiguation.

Author: patshaughnessy

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

@@ -147,14 +147,30 @@ extension PathHierarchy.Error {
             let disambiguations = nextPathComponent.full.dropFirst(nextPathComponent.name.count)
             let replacementRange = SourceRange.makeRelativeRange(startColumn: validPrefix.count, length: disambiguations.count)
 
-            let solutions: [Solution] = candidates
-                .sorted(by: collisionIsBefore)
-                .map { (node: PathHierarchy.Node, disambiguation: String) -> Solution in
-                    return Solution(summary: "\(Self.replacementOperationDescription(from: disambiguations.dropFirst(), to: disambiguation)) for\n\(fullNameOfNode(node).singleQuoted)", replacements: [
-                        Replacement(range: replacementRange, replacement: "-" + disambiguation)
-                    ])
-                }
-            
+            let solutions: [Solution]
+
+            // First check if any of the ambiguous symbols is an overload group.
+            // If one is (and all the others are disfavored) then suggest a single
+            // solution to remove the disambiguation from the path
+            if let overloadGroupNode = overloadGroupNodeFrom(candidates: candidates) {
+                solutions = [
+                    Solution(
+                        summary: "\(Self.replacementOperationDescription(from: "-" + disambiguations.dropFirst(), to: "")) to use overload group \n\(fullNameOfNode(overloadGroupNode).singleQuoted)",
+                        replacements: [ Replacement(range: replacementRange, replacement: "") ]
+                    )
+                ]
+
+            // Normally list all the ambiguous paths, with a replacement solution for each
+            } else {
+                solutions = candidates
+                    .sorted(by: collisionIsBefore)
+                    .map { (node: PathHierarchy.Node, disambiguation: String) -> Solution in
+                        return Solution(summary: "\(Self.replacementOperationDescription(from: disambiguations.dropFirst(), to: disambiguation)) for\n\(fullNameOfNode(node).singleQuoted)", replacements: [
+                            Replacement(range: replacementRange, replacement: "-" + disambiguation)
+                        ])
+                    }
+            }
+
             return TopicReferenceResolutionErrorInfo("""
                 \(disambiguations.dropFirst().singleQuoted) isn't a disambiguation for \(nextPathComponent.name.singleQuoted) at \(partialResult.node.pathWithoutDisambiguation().singleQuoted)
                 """,
@@ -231,6 +247,20 @@ extension PathHierarchy.Error {
         }
         return "Replace \(from.singleQuoted) with \(to.singleQuoted)"
     }
+
+    /// Find an overload group node from an array of disambiguation candidates. Only
+    /// return the overload group if all the remaining candidates are disfavored for link resolution.
+    /// - Parameters:
+    ///   - candidates: An array of candidate node and disambiguation tuples.
+    /// - Returns: The PathHierarchy node for the overload group symbol
+    func overloadGroupNodeFrom(candidates: [(node: PathHierarchy.Node, disambiguation: String)]) -> PathHierarchy.Node? {
+        guard FeatureFlags.current.isExperimentalOverloadedSymbolPresentationEnabled,
+            let favoredCandidate = candidates.singleMatch({ !$0.node.specialBehaviors.contains(.disfavorInLinkCollision) }),
+            favoredCandidate.node.symbol?.isOverloadGroup ?? false else {
+            return nil
+        }
+        return favoredCandidate.node
+    }
 }
 
 private extension PathHierarchy.Node {

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

@@ -475,7 +475,7 @@ private func == (lhs: (some StringProtocol)?, rhs: some StringProtocol) -> Bool
      return lhs == rhs
  }
 
-private extension Sequence {
+package extension Sequence {
     /// Returns the only element of the sequence that satisfies the given predicate.
     /// - Parameters:
     ///   - predicate: A closure that takes an element of the sequence as its argument and returns a Boolean value indicating whether the element is a match.

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -1318,6 +1318,20 @@ class PathHierarchyTests: XCTestCase {
         // This overloaded protocol method should be able to resolve without a suffix at all, since it doesn't conflict with anything
         let overloadedProtocolMethod = try tree.findNode(path: "/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)", onlyFindSymbols: true)
         XCTAssert(overloadedProtocolMethod.symbol?.identifier.precise.hasSuffix(SymbolGraph.Symbol.overloadGroupIdentifierSuffix) == true)
+
+    }
+
+    func testAmbiguousPathsForOverloadedGroupSymbols() throws {
+        enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
+        let (_, context) = try testBundleAndContext(named: "OverloadedSymbols")
+        let tree = context.linkResolver.localResolver.pathHierarchy
+        try assertPathRaisesErrorMessage("/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-abc123", in: tree, context: context, expectedErrorMessage: """
+        'abc123' isn't a disambiguation for 'fourthTestMemberName(test:)' at '/ShapeKit/OverloadedProtocol'
+        """) { error in
+            XCTAssertEqual(error.solutions, [
+                .init(summary: "Remove '-abc123' to use overload group \n'func fourthTestMemberName(test: String) -> Double\'", replacements: [("", 56, 63)]),
+            ])
+        }
     }
 
     func testSymbolsWithSameNameAsModule() throws {