add 'AlternateDeclarations' mixin (#60)

rdar://111227476

Author: QuietMisdreavus

Sources/SymbolKit/SymbolGraph/Symbol/AlternateDeclarations.swift

@@ -0,0 +1,58 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+extension SymbolGraph.Symbol {
+    /// A mixin to hold alternate declarations of a symbol.
+    ///
+    /// This mixin is created while a symbol graph is decoded, to hold ``DeclarationFragments-swift.struct``
+    /// for symbols which share the same precise identifier.
+    public struct AlternateDeclarations: Mixin, Codable {
+        public static let mixinKey = "alternateDeclarations"
+
+        /// Alternate declarations for this symbol.
+        public var declarations: [DeclarationFragments]
+
+        public init(declarations: [DeclarationFragments]) {
+            self.declarations = declarations
+        }
+
+        public init(from decoder: Decoder) throws {
+            let container = try decoder.singleValueContainer()
+            declarations = try container.decode([DeclarationFragments].self)
+        }
+
+        public func encode(to encoder: Encoder) throws {
+            var container = encoder.singleValueContainer()
+            try container.encode(declarations)
+        }
+    }
+
+    /// Convenience accessor to fetch alternate declarations for this symbol.
+    public var alternateDeclarations: [DeclarationFragments]? {
+        (mixins[AlternateDeclarations.mixinKey] as? AlternateDeclarations)?.declarations
+    }
+
+    internal mutating func addAlternateDeclaration(_ declaration: DeclarationFragments) {
+        if var alternateDeclarations = mixins[AlternateDeclarations.mixinKey] as? AlternateDeclarations {
+            alternateDeclarations.declarations.append(declaration)
+            mixins[AlternateDeclarations.mixinKey] = alternateDeclarations
+        } else {
+            mixins[AlternateDeclarations.mixinKey] = AlternateDeclarations(declarations: [declaration])
+        }
+    }
+
+    internal mutating func addAlternateDeclaration(from symbol: SymbolGraph.Symbol) {
+        if let declaration = symbol.mixins[DeclarationFragments.mixinKey] as? DeclarationFragments {
+            addAlternateDeclaration(declaration)
+        }
+    }
+}

Sources/SymbolKit/SymbolGraph/Symbol/Symbol.swift

@@ -236,7 +236,8 @@ extension SymbolGraph.Symbol {
         static let httpEndpoint = HTTP.Endpoint.symbolCodingInfo
         static let httpParameterSource = HTTP.ParameterSource.symbolCodingInfo
         static let httpMediaType = HTTP.MediaType.symbolCodingInfo
-        
+        static let alternateDeclarations = AlternateDeclarations.symbolCodingInfo
+
         static let mixinCodingInfo: [String: SymbolMixinCodingInfo] = [
             CodingKeys.availability.codingKey.stringValue: Self.availability,
             CodingKeys.declarationFragments.codingKey.stringValue: Self.declarationFragments,
@@ -260,6 +261,7 @@ extension SymbolGraph.Symbol {
             CodingKeys.httpEndpoint.codingKey.stringValue: Self.httpEndpoint,
             CodingKeys.httpParameterSource.codingKey.stringValue: Self.httpParameterSource,
             CodingKeys.httpMediaType.codingKey.stringValue: Self.httpMediaType,
+            CodingKeys.alternateDeclarations.codingKey.stringValue: Self.alternateDeclarations,
         ]
 
         static func == (lhs: SymbolGraph.Symbol.CodingKeys, rhs: SymbolGraph.Symbol.CodingKeys) -> Bool {

Sources/SymbolKit/SymbolGraph/SymbolGraph.swift

@@ -62,13 +62,37 @@ public struct SymbolGraph: Codable {
 
     public static func _symbolToKeepInCaseOfPreciseIdentifierConflict(_ lhs: Symbol, _ rhs: Symbol) -> Symbol {
         if lhs.declarationContainsAsyncKeyword() {
-            return rhs
+            var result = rhs
+            result.addAlternateDeclaration(from: lhs)
+            return result
         } else if rhs.declarationContainsAsyncKeyword() {
-            return lhs
+            var result = lhs
+            result.addAlternateDeclaration(from: rhs)
+            return result
         } else {
             // It's not expected to ever end up here, but if we do, we return the symbol with the longer name
             // to have consistent results.
-            return lhs.names.title.count < rhs.names.title.count ? rhs : lhs
+            var result: Symbol
+            let other: Symbol
+            if lhs.names.title.count < rhs.names.title.count {
+                result = rhs
+                other = lhs
+            } else if rhs.names.title.count < lhs.names.title.count {
+                result = lhs
+                other = rhs
+            } else {
+                // If, by total coincidence, both symbols have the same length, try a lexicographic
+                // sort and pick the first one.
+                if lhs.names.title <= rhs.names.title {
+                    result = lhs
+                    other = rhs
+                } else {
+                    result = rhs
+                    other = lhs
+                }
+            }
+            result.addAlternateDeclaration(from: other)
+            return result
         }
     }
 }

Tests/SymbolKitTests/SymbolGraph/SymbolGraphTests.swift

@@ -63,6 +63,19 @@ class SymbolGraphTests: XCTestCase {
         XCTAssertTrue(declaration.declarationFragments.contains(where: { fragment in
             fragment.kind == .externalParameter && fragment.spelling == "completionHandler"
         }))
+
+        // The async declaration should have been saved as an alternate declaration
+        let alternateDeclarations = try XCTUnwrap(symbol.alternateDeclarations)
+        XCTAssertEqual(alternateDeclarations.count, 1)
+        let alternate = alternateDeclarations[0]
+
+        XCTAssertTrue(alternate.declarationFragments.contains(where: { fragment in
+            fragment.kind == .keyword && fragment.spelling == "async"
+        }))
+
+        XCTAssertFalse(alternate.declarationFragments.contains(where: { fragment in
+            fragment.kind == .externalParameter && fragment.spelling == "completionHandler"
+        }))
     }
 }