RenderNodeTranslator.visitSymbol filters out availability items with a missing domain (#1256)

RenderNodeTranslator.visitSymbol filters out availability items which have a missing or invalid domain (platform name).

Swift developers can add global availability messages with no specific platform information, for example like this:

@available(*, deprecated, message:
  """
  Don't use this function; call some other function instead.
  """
)

In this scenario, the Swift compiler adds an availability item with the
message but no domain (platform name) to the symbol graph file, like
this:

{
  "domain": null,
  "isUnconditionallyDeprecated": true,
  "message": "Don't use this function; call some other function instead."
}

To avoid displaying an empty/null platform in the DocC Render user
interface, the RenderNodeTranslator needs to filter out these records.
Additionally, AvailabilityRenderOrder.compare always returns false for
availability items that have no name, leading to an unpredictable sort
order when any of the items is missing a platform name, even for
availability items that had a valid platform name.

Author: patshaughnessy

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1257,13 +1257,14 @@ public struct RenderNodeTranslator: SemanticVisitor {
                     if availability.obsoletedVersion != nil {
                         return nil
                     }
-                    guard let name = availability.domain.map({ PlatformName(operatingSystemName: $0.rawValue) }),
-                          let currentPlatform = context.configuration.externalMetadata.currentPlatforms?[name.displayName]
-                    else {
+                    // Filter out this availability item if it has a missing or invalid domain.
+                    guard let name = availability.domain.map({ PlatformName(operatingSystemName: $0.rawValue) }) else {
+                        return nil
+                    }
+                    guard let currentPlatform = context.configuration.externalMetadata.currentPlatforms?[name.displayName] else {
                         // No current platform provided by the context
                         return AvailabilityRenderItem(availability, current: nil)
                     }
-                    
                     return AvailabilityRenderItem(availability, current: currentPlatform)
                 }
                 .filter { $0.unconditionallyUnavailable != true }

Tests/SwiftDocCTests/Rendering/AvailabilityRenderOrderTests.swift

@@ -9,6 +9,7 @@
 */
 
 import Foundation
+import SymbolKit
 import XCTest
 @testable import SwiftDocC
 
@@ -18,7 +19,47 @@ class AvailabilityRenderOrderTests: XCTestCase {
 
     func testSortingAtRenderTime() throws {
         let (bundleURL, bundle, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", excludingPaths: []) { url in
-            try? FileManager.default.copyItem(at: self.availabilitySGFURL, to: url.appendingPathComponent("Availability.symbols.json"))
+            let availabilitySymbolGraphURL = url.appendingPathComponent("Availability.symbols.json")
+            try? FileManager.default.copyItem(at: self.availabilitySGFURL, to: availabilitySymbolGraphURL)
+
+            // Load the symbol graph fixture
+            var availabilitySymbolGraph = try JSONDecoder().decode(SymbolGraph.self, from: try Data(contentsOf: availabilitySymbolGraphURL))
+
+            // There should be at least one symbol in this graph
+            XCTAssertEqual(1, availabilitySymbolGraph.symbols.count)
+            if let tuple = availabilitySymbolGraph.symbols.first {
+
+                let key = tuple.key
+                var symbol = tuple.value
+
+                // The symbol should have availability info specified
+                XCTAssertNotNil(symbol.availability)
+                if var alternateSymbols = symbol.mixins[Availability.mixinKey] as? Availability {
+
+                    // Create a new availability item which is missing a domain (platform name).
+                    let missingDomain = SymbolGraph.Symbol.Availability.AvailabilityItem(
+                        domain: nil,
+                        introducedVersion: nil,
+                        deprecatedVersion: nil,
+                        obsoletedVersion: nil,
+                        message: "Don't use this function; call some other function instead.",
+                        renamed: nil,
+                        isUnconditionallyDeprecated: true,
+                        isUnconditionallyUnavailable: false,
+                        willEventuallyBeDeprecated: false
+                    )
+
+                    // Append the invalid item and update the symbol
+                    alternateSymbols.availability.insert(missingDomain, at: 4)
+                    symbol.mixins[Availability.mixinKey] = alternateSymbols
+                }
+                availabilitySymbolGraph.symbols[key] = symbol
+            }
+
+            // Update the temporary copy of the fixture
+            let jsonEncoder = JSONEncoder()
+            let data = try jsonEncoder.encode(availabilitySymbolGraph)
+            try data.write(to: availabilitySymbolGraphURL)
         }
         defer {
             try? FileManager.default.removeItem(at: bundleURL)
@@ -32,6 +73,7 @@ class AvailabilityRenderOrderTests: XCTestCase {
         // Verify that all the symbol's availabilities were sorted into the order
         // they need to appear for rendering (they are not in the symbol graph fixture).
         // Additionally verify all the platforms have their correctly spelled name including spaces.
+        // Finally, the invalid item added above should be filtered out.
         XCTAssertEqual(renderNode.metadata.platforms?.map({ "\($0.name ?? "") \($0.introduced ?? "")" }), [
             "iOS 12.0", "iOS App Extension 12.0",
             "iPadOS 12.0",

Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorSymbolVariantsTests.swift

@@ -147,7 +147,7 @@ class RenderNodeTranslatorSymbolVariantsTests: XCTestCase {
             configureSymbol: { symbol in
                 symbol.availabilityVariants[.swift] = SymbolGraph.Symbol.Availability(availability: [
                     SymbolGraph.Symbol.Availability.AvailabilityItem(
-                        domain: nil,
+                        domain: .init(rawValue: "iOS"),
                         introducedVersion: SymbolGraph.SemanticVersion(string: "1.0"),
                         deprecatedVersion: nil,
                         obsoletedVersion: nil,
@@ -161,7 +161,7 @@ class RenderNodeTranslatorSymbolVariantsTests: XCTestCase {
 
                 symbol.availabilityVariants[.objectiveC] = SymbolGraph.Symbol.Availability(availability: [
                     SymbolGraph.Symbol.Availability.AvailabilityItem(
-                        domain: nil,
+                        domain: .init(rawValue: "iOS"),
                         introducedVersion: SymbolGraph.SemanticVersion(string: "2.0"),
                         deprecatedVersion: nil,
                         obsoletedVersion: nil,