Support unavailable platform status and updated fallback platforms. (#807)

Support unavailable platform status and updated fallback platforms. 

This commit has made changes to how the platform availability is calculated for symbols. Now, we add fallback and default availability after loading all the SGFs. Then, we merge the availability declarations from each of the availability mixins of the unified graph for each of its variants.

- Added `unavailable` status into DefaultAvailability.
- Added iOS as fallback for iPadOS.
- Fixed availability selection in symbols.
- When selecting the symbol availability we merge the availability variants of each availability mixin of the unified symbol.
- After the symbol graph loading we add the platforms defined in the info.plist that don't have a corresponding symbol graph file.
- After the symbol graph loading we add the fallback availability variants defined (catalyst and iPadOS).

rdar://88643064

Author: sofiaromorales

Sources/SwiftDocC/Infrastructure/Symbol Graph/SymbolGraphLoader.swift

@@ -146,6 +146,29 @@ struct SymbolGraphLoader {
 
         self.symbolGraphs = loadedGraphs.mapValues(\.graph)
         (self.unifiedGraphs, self.graphLocations) = graphLoader.finishLoading()
+        
+        for var unifiedGraph in unifiedGraphs.values {
+            var defaultUnavailablePlatforms = [PlatformName]()
+            var defaultAvailableInformation = [DefaultAvailability.ModuleAvailability]()
+
+            if let defaultAvailabilities = bundle.info.defaultAvailability?.modules[unifiedGraph.moduleName] {
+                let (unavailablePlatforms, availablePlatforms) = defaultAvailabilities.categorize(where: { $0.versionInformation == .unavailable })
+                defaultUnavailablePlatforms = unavailablePlatforms.map(\.platformName)
+                defaultAvailableInformation = availablePlatforms
+            }
+            
+            let platformsFoundInSymbolGraphs: [PlatformName] = unifiedGraph.moduleData.compactMap {
+                guard let platformName = $0.value.platform.name else { return nil }
+                return PlatformName(operatingSystemName: platformName)
+            }
+
+            addMissingAvailability(
+                unifiedGraph: &unifiedGraph,
+                unconditionallyUnavailablePlatformNames: defaultUnavailablePlatforms,
+                registeredPlatforms: platformsFoundInSymbolGraphs,
+                defaultAvailabilities: defaultAvailableInformation
+            )
+        }
     }
 
     // Alias to declutter code
@@ -176,76 +199,105 @@ struct SymbolGraphLoader {
 
         return (symbolGraph, isMainSymbolGraph)
     }
+    
+    /// Adds the missing fallback and default availability information to the unified symbol graph
+    /// in case it didn't exists in the loaded symbol graphs.
+    private func addMissingAvailability(
+        unifiedGraph: inout UnifiedSymbolGraph,
+        unconditionallyUnavailablePlatformNames: [PlatformName],
+        registeredPlatforms: [PlatformName],
+        defaultAvailabilities: [DefaultAvailability.ModuleAvailability]
+    ) {
+        // The fallback platforms that are missing from the unified graph correspond to
+        // the fallback platforms that have not been registered yet,
+        // are not marked as unavailable,
+        // and the corresponding inheritance platform has a SGF (has been registered).
+        let missingFallbackPlatforms = DefaultAvailability.fallbackPlatforms.filter {
+            !registeredPlatforms.contains($0.key) &&
+            !unconditionallyUnavailablePlatformNames.contains($0.key) &&
+            registeredPlatforms.contains($0.value)
+        }
+        // Platforms that are defined in the Info.plist that had no corresponding SGF
+        // and are not being added as fallback of another platform.
+        let missingAvailabilities = defaultAvailabilities.filter {
+            !missingFallbackPlatforms.keys.contains($0.platformName) &&
+            !registeredPlatforms.contains($0.platformName)
+        }
+        
+        unifiedGraph.symbols.values.forEach { symbol in
+            for (selector, _) in symbol.mixins {
+                if var symbolAvailability = (symbol.mixins[selector]?["availability"] as? SymbolGraph.Symbol.Availability) {
+                    guard !symbolAvailability.availability.isEmpty else { continue }
+                    // Add fallback availability.
+                    for (fallbackPlatform, inheritedPlatform) in missingFallbackPlatforms {
+                        if !symbolAvailability.contains(fallbackPlatform) {
+                            for var fallbackAvailability in symbolAvailability.availability {
+                                // Add the platform fallback to the availability mixin the platform is inheriting from.
+                                // The added availability copies the entire availability information,
+                                // including deprecated and obsolete versions.
+                                if fallbackAvailability.matches(inheritedPlatform) {
+                                    fallbackAvailability.domain = SymbolGraph.Symbol.Availability.Domain(rawValue: fallbackPlatform.rawValue)
+                                    symbolAvailability.availability.append(fallbackAvailability)
+                                }
+                            }
+                        }
+                    }
+                    // Add the missing default platform availability.
+                    missingAvailabilities.forEach { missingAvailability in
+                        if !symbolAvailability.contains(missingAvailability.platformName) {
+                            guard let defaultAvailability = AvailabilityItem(missingAvailability) else { return }
+                            symbolAvailability.availability.append(defaultAvailability)
+                        }
+                    }
+                    symbol.mixins[selector]![SymbolGraph.Symbol.Availability.mixinKey] = symbolAvailability
+                }
+            }
+        }
+    }    
 
     /// If the bundle defines default availability for the symbols in the given symbol graph
     /// this method adds them to each of the symbols in the graph.
     private func addDefaultAvailability(to symbolGraph: inout SymbolGraph, moduleName: String) {
+        let selector = UnifiedSymbolGraph.Selector(forSymbolGraph: symbolGraph)
         // Check if there are defined default availabilities for the current module
         if let defaultAvailabilities = bundle.info.defaultAvailability?.modules[moduleName],
             let platformName = symbolGraph.module.platform.name.map(PlatformName.init) {
-            
-            // Prepare a default availability lookup for this module.
-            let defaultAvailabilityIndex = defaultAvailabilities
-                .reduce(into: [DefaultAvailability.ModuleAvailability: AvailabilityItem](), { result, defaultAvailability in
-                    result[defaultAvailability] = AvailabilityItem(defaultAvailability)
-                })
-            
+
             // Prepare a default availability versions lookup for this module.
             let defaultAvailabilityVersionByPlatform = defaultAvailabilities
                 .reduce(into: [PlatformName: SymbolGraph.SemanticVersion](), { result, defaultAvailability in
-                    if let version = SymbolGraph.SemanticVersion(string: defaultAvailability.platformVersion) {
+                    if let introducedVersion = defaultAvailability.introducedVersion, let version = SymbolGraph.SemanticVersion(string: introducedVersion) {
                         result[defaultAvailability.platformName] = version
                     }
                 })
 
-            // In the case of Mac Catalyst use default availability for the iOS platform if annotated
-            let fallbackPlatform = (platformName == .catalyst) ? PlatformName.iOS.displayName : nil
-            
-            // `true` if this module has Mac Catalyst availability.
-            let isDefaultCatalystAvailabilitySet = defaultAvailabilities.contains(where: { $0.platformName == .catalyst })
-
             // Map all symbols and add default availability for any missing platforms
             let symbolsWithFilledIntroducedVersions = symbolGraph.symbols.mapValues { symbol -> SymbolGraph.Symbol in
                 var symbol = symbol
-                
+                let defaultModuleVersion = defaultAvailabilityVersionByPlatform[platformName]
+                // The availability item for each symbol of the given module.
+                let modulePlatformAvailabilityItem = AvailabilityItem(domain: SymbolGraph.Symbol.Availability.Domain(rawValue: platformName.rawValue), introducedVersion: defaultModuleVersion, deprecatedVersion: nil, obsoletedVersion: nil, message: nil, renamed: nil, isUnconditionallyDeprecated: false, isUnconditionallyUnavailable: false, willEventuallyBeDeprecated: false)
                 // Check if the symbol has existing availabilities from source
                 if var availability = symbol.mixins[SymbolGraph.Symbol.Availability.mixinKey] as? SymbolGraph.Symbol.Availability {
 
                     // Fill introduced versions when missing.
-                    var newAvailabilityItems = availability.availability.map {
-                        $0.fillingMissingIntroducedVersion(from: defaultAvailabilityVersionByPlatform, fallbackPlatform: fallbackPlatform)
+                    availability.availability = availability.availability.map {
+                        $0.fillingMissingIntroducedVersion(
+                            from: defaultAvailabilityVersionByPlatform,
+                            fallbackPlatform: DefaultAvailability.fallbackPlatforms[platformName]?.rawValue
+                        )
                     }
-                    
-                    // When Catalyst is missing, fall back on iOS availability.
-
-                    // First check if we're targeting the Mac Catalyst platform
-                    if isDefaultCatalystAvailabilitySet,
-                        // Then verify annotated availability from source for Mac Catalyst is missing
-                       !newAvailabilityItems.contains(where: { $0.domain?.rawValue == SymbolGraph.Symbol.Availability.Domain.macCatalyst }),
-                        // And finally fetch the symbol's iOS availability if there is one
-                        let iOSAvailability = newAvailabilityItems.first(where: { $0.domain?.rawValue == SymbolGraph.Symbol.Availability.Domain.iOS }) {
-                        
-                        var macCatalystAvailability = iOSAvailability
-                        macCatalystAvailability.domain = SymbolGraph.Symbol.Availability.Domain(rawValue: SymbolGraph.Symbol.Availability.Domain.macCatalyst)
-                        newAvailabilityItems.append(macCatalystAvailability)
-                    }
-
-                    // If a symbol doesn't have any availability annotation at all
-                    // for a given platform, create a new one just with the
-                    // introduced version so that it shows up in the sidebar.
-                    for defaultAvailability in defaultAvailabilities {
-                        let hasAvailabilityForThisPlatform = newAvailabilityItems.contains {
-                            guard let domain = $0.domain else { return false }
-                            return PlatformName(operatingSystemName: domain.rawValue) == defaultAvailability.platformName
-                        }
-                        if !hasAvailabilityForThisPlatform {
-                            // Safe to force unwrap below, the index contains all the avaialbility keys.
-                            newAvailabilityItems.append(defaultAvailabilityIndex[defaultAvailability]!)
-                        }
+                    // Add the module availability information to each of the symbols availability mixin.
+                    if !availability.contains(platformName) {
+                        availability.availability.append(modulePlatformAvailabilityItem)
                     }
-
-                    availability.availability = newAvailabilityItems
                     symbol.mixins[SymbolGraph.Symbol.Availability.mixinKey] = availability
+                } else {
+                    // ObjC doesn't propagate symbol availability to their children properties,
+                    // so only add the default availability to the Swift variant of the symbols.
+                    if !(selector?.interfaceLanguage == InterfaceLanguage.objc.name.lowercased()) {
+                        symbol.mixins[SymbolGraph.Symbol.Availability.mixinKey] = SymbolGraph.Symbol.Availability(availability: [modulePlatformAvailabilityItem])
+                    }
                 }
                 return symbol
             }
@@ -330,7 +382,7 @@ extension SymbolGraph.Symbol.Availability.AvailabilityItem {
     /// - Note: If the `defaultAvailability` argument doesn't have a valid
     /// platform version that can be parsed as a `SemanticVersion`, returns `nil`.
     init?(_ defaultAvailability: DefaultAvailability.ModuleAvailability) {
-        guard let platformVersion = SymbolGraph.SemanticVersion(string: defaultAvailability.platformVersion) else {
+        guard let introducedVersion = defaultAvailability.introducedVersion, let platformVersion = SymbolGraph.SemanticVersion(string: introducedVersion) else {
             return nil
         }
         let domain = SymbolGraph.Symbol.Availability.Domain(rawValue: defaultAvailability.platformName.rawValue)
@@ -354,7 +406,6 @@ extension SymbolGraph.Symbol.Availability.AvailabilityItem {
 
      - parameter defaults: Default module availabilities for each platform mentioned in a documentation bundle's `Info.plist`
      - parameter fallbackPlatform: An optional fallback platform name if this item's domain isn't found in the `defaults`.
-     For example, `macCatalyst` should fall back to `iOS` because `macCatalyst` symbols are originally `iOS` symbols.
      */
     func fillingMissingIntroducedVersion(from defaults: [PlatformName: SymbolGraph.SemanticVersion],
                                          fallbackPlatform: String?) -> SymbolGraph.Symbol.Availability.AvailabilityItem {
@@ -395,3 +446,15 @@ extension SymbolGraph.Symbol.Availability.AvailabilityItem {
         return newValue
     }
 }
+
+private extension SymbolGraph.Symbol.Availability {
+    func contains(_ platform: PlatformName) -> Bool {
+        availability.contains(where: { $0.matches(platform) })
+    }
+}
+
+private extension SymbolGraph.Symbol.Availability.AvailabilityItem {
+    func matches(_ platform: PlatformName) -> Bool {
+        domain?.rawValue.lowercased() == platform.rawValue.lowercased()
+    }
+}