Allow default availability entries without version number. (#1037)

Allow default availability entries without version number.

This change allows the definition of entries in the Default Availability section of the Info.plist file without specifying an introduced version.

The goal of this change is to avoid enforcing a potentially incorrect version for symbols with unknown introduction versions while still indicating their availability on a given platform. Additionally, it allows for communicating that a framework is available on other platforms, such as Linux.

rdar://132980711

Author: sofiaromorales

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

@@ -401,10 +401,12 @@ extension SymbolGraph.SemanticVersion {
 extension SymbolGraph.Symbol.Availability.AvailabilityItem {
     /// Create an availability item with a `domain` and an `introduced` version.
     /// - parameter defaultAvailability: Default availability information for symbols that lack availability authored in code.
-    /// - Note: If the `defaultAvailability` argument doesn't have a valid
-    /// platform version that can be parsed as a `SemanticVersion`, returns `nil`.
+    /// - Note: If the `defaultAvailability` argument has a introduced version that can't
+    /// be parsed as a `SemanticVersion`, returns `nil`.
     init?(_ defaultAvailability: DefaultAvailability.ModuleAvailability) {
-        guard let introducedVersion = defaultAvailability.introducedVersion, let platformVersion = SymbolGraph.SemanticVersion(string: introducedVersion) else {
+        let introducedVersion = defaultAvailability.introducedVersion
+        let platformVersion = introducedVersion.flatMap { SymbolGraph.SemanticVersion(string: $0) }
+        if platformVersion == nil && introducedVersion != nil {
             return nil
         }
         let domain = SymbolGraph.Symbol.Availability.Domain(rawValue: defaultAvailability.platformName.rawValue)

Sources/SwiftDocC/Infrastructure/Workspace/DefaultAvailability.swift

@@ -30,6 +30,10 @@ import Foundation
 ///         </dict>
 ///         <dict>
 ///             <key>name</key>
+///             <string>Platform Name</string>
+///         </dict>
+///         <dict>
+///             <key>name</key>
 ///             <string>Other Platform Name</string>
 ///             <key>unavailable</key>
 ///             <true/>
@@ -48,10 +52,10 @@ public struct DefaultAvailability: Codable, Equatable {
         }
 
         /// The different availability states that can be declared.
-        /// Unavailable or Available with an introduced version.
+        /// Unavailable or Available with a potential introduced version.
         enum VersionInformation: Hashable {
             case unavailable
-            case available(version: String)
+            case available(version: String?)
         }
 
         /// The name of the platform, e.g. "macOS".
@@ -71,7 +75,7 @@ public struct DefaultAvailability: Codable, Equatable {
         public var introducedVersion: String? {
             switch versionInformation {
             case .available(let introduced):
-                return introduced.description
+                return introduced?.description
             case .unavailable:
                 return nil
             }
@@ -82,7 +86,7 @@ public struct DefaultAvailability: Codable, Equatable {
         /// - Parameters:
         ///   - platformName: A platform name, such as "iOS" or "macOS"; see ``PlatformName``.
         ///   - platformVersion: A 2- or 3-component version string, such as `"13.0"` or `"13.1.2"`.
-        public init(platformName: PlatformName, platformVersion: String) {
+        public init(platformName: PlatformName, platformVersion: String?) {
             self.platformName = platformName
             self.versionInformation = .available(version: platformVersion)
         }
@@ -103,10 +107,14 @@ public struct DefaultAvailability: Codable, Equatable {
                 versionInformation = .unavailable
                 return
             }
-            let introducedVersion = try values.decode(String.self, forKey: .platformVersion)
+            let introducedVersion = try values.decodeIfPresent(String.self, forKey: .platformVersion)
             versionInformation = .available(version: introducedVersion)
-            guard let version = Version(versionString: introducedVersion), (2...3).contains(version.count) else {
-                throw DocumentationBundle.PropertyListError.invalidVersionString(introducedVersion)
+            // If the default availability contains a version, validate it's a
+            // semantic version.
+            if let introducedVersion {
+                guard let version = Version(versionString: introducedVersion), (2...3).contains(version.count) else {
+                    throw DocumentationBundle.PropertyListError.invalidVersionString(introducedVersion)
+                }
             }
         }
 

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1249,8 +1249,10 @@ public struct RenderNodeTranslator: SemanticVisitor {
 
             return availability.availability
                 .compactMap { availability -> AvailabilityRenderItem? in
-                    // Filter items with insufficient availability data
-                    guard availability.introducedVersion != nil else {
+                    // Filter items with insufficient availability data.
+                    // Allow availability without version information, but only if
+                    // both, introduced and deprecated, are nil.
+                    if availability.introducedVersion == nil && availability.deprecatedVersion != nil {
                         return nil
                     }
                     guard let name = availability.domain.map({ PlatformName(operatingSystemName: $0.rawValue) }),
@@ -1817,10 +1819,9 @@ public struct RenderNodeTranslator: SemanticVisitor {
         let renderedAvailability = moduleAvailability
             .filter({ $0.versionInformation != .unavailable })
             .compactMap({ availability -> AvailabilityRenderItem? in
-                guard let availabilityIntroducedVersion = availability.introducedVersion else { return nil }
                 return AvailabilityRenderItem(
                     name: availability.platformName.displayName,
-                    introduced: availabilityIntroducedVersion,
+                    introduced: availability.introducedVersion,
                     isBeta: currentPlatforms.map({ isModuleBeta(moduleAvailability: availability, currentPlatforms: $0) }) ?? false
                 )
             })

Sources/SwiftDocC/Model/Rendering/Symbol/AvailabilityRenderMetadataItem.swift

@@ -157,7 +157,7 @@ public struct AvailabilityRenderItem: Codable, Hashable, Equatable {
     ///   - name: A platform name.
     ///   - introduced: A version string.
     ///   - isBeta: If `true`, the symbol is introduced in a beta version of the platform.
-    init(name: String, introduced: String, isBeta: Bool) {
+    init(name: String, introduced: String?, isBeta: Bool) {
         self.name = name
         self.introduced = introduced
         self.isBeta = isBeta

Tests/SwiftDocCTests/Rendering/DefaultAvailabilityTests.swift

@@ -85,7 +85,7 @@ class DefaultAvailabilityTests: XCTestCase {
             var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: node.reference)
             let renderNode = translator.visit(node.semantic) as! RenderNode
 
-            XCTAssertEqual(renderNode.metadata.platforms?.map({ "\($0.name ?? "") \($0.introduced ?? "")" }).sorted(), [expectedDefaultAvailability.last ?? ""])
+            XCTAssertEqual(renderNode.metadata.platforms?.map({ "\($0.name ?? "") \($0.introduced ?? "")" }).sorted(), ["Mac Catalyst ", "iOS ", "iPadOS ", "macOS 10.15.1"])
         }
 
         // Test if the default availability is NOT used for symbols with explicit availability
@@ -579,4 +579,178 @@ class DefaultAvailabilityTests: XCTestCase {
         )
 
     }
+    
+    func testInheritDefaultAvailabilityOptions() throws {
+        func makeInfoPlist(
+            defaultAvailability: String
+        ) -> String {
+            return """
+               <plist version="1.0">
+               <dict>
+                   <key>CDAppleDefaultAvailability</key>
+                   <dict>
+                       <key>MyModule</key>
+                       <array>
+                           \(defaultAvailability)
+                       </array>
+                   </dict>
+               </dict>
+               </plist>
+               """
+        }
+        func setupContext(
+            defaultAvailability: String
+        ) throws -> (DocumentationBundle, DocumentationContext) {
+            // Create an empty bundle
+            let targetURL = try createTemporaryDirectory(named: "test.docc")
+            // Create symbol graph
+            let symbolGraphURL = targetURL.appendingPathComponent("MyModule.symbols.json")
+            try symbolGraphString.write(to: symbolGraphURL, atomically: true, encoding: .utf8)
+            // Create info plist
+            let infoPlistURL = targetURL.appendingPathComponent("Info.plist")
+            let infoPlist = makeInfoPlist(defaultAvailability: defaultAvailability)
+            try infoPlist.write(to: infoPlistURL, atomically: true, encoding: .utf8)
+            // Load the bundle & reference resolve symbol graph docs
+            let (_, bundle, context) = try loadBundle(from: targetURL)
+            return (bundle, context)
+        }
+        
+        let symbols = """
+           {
+               "kind": {
+                   "displayName" : "Instance Property",
+                   "identifier" : "swift.property"
+               },
+               "identifier": {
+                   "precise": "c:@F@SymbolWithAvailability",
+                   "interfaceLanguage": "swift"
+               },
+               "pathComponents": [
+                   "Foo"
+               ],
+               "names": {
+                   "title": "Foo",
+               },
+               "accessLevel": "public",
+               "availability" : [
+                   {
+                      "domain" : "ios",
+                      "introduced" : {
+                           "major" : 10,
+                           "minor" : 0
+                      }
+                   }
+               ]
+           },
+           {
+               "kind": {
+                   "displayName" : "Instance Property",
+                   "identifier" : "swift.property"
+               },
+               "identifier": {
+                   "precise": "c:@F@SymbolWithoutAvailability",
+                   "interfaceLanguage": "swift"
+               },
+               "pathComponents": [
+                   "Foo"
+               ],
+               "names": {
+                   "title": "Bar",
+               },
+               "accessLevel": "public"
+           }
+           """
+        let symbolGraphString = makeSymbolGraphString(
+            moduleName: "MyModule",
+            symbols: symbols,
+            platform: """
+               "operatingSystem" : {
+                  "minimumVersion" : {
+                    "major" : 10,
+                    "minor" : 0
+                  },
+                  "name" : "ios"
+                }
+               """
+        )
+        
+        // Don't use default availability version.
+        
+        var (bundle, context) = try setupContext(
+            defaultAvailability: """
+               <dict>
+                   <key>name</key>
+                   <string>iOS</string>
+               </dict>
+               """
+        )
+        
+        // Verify we add the version number into the symbols that have availability annotation.
+        guard let availability = (context.documentationCache["c:@F@SymbolWithAvailability"]?.semantic as? Symbol)?.availability?.availability else {
+            XCTFail("Did not find availability for symbol 'c:@F@SymbolWithAvailability'")
+            return
+        }
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "iOS" }))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "iOS" })?.introducedVersion, SymbolGraph.SemanticVersion(major: 10, minor: 0, patch: 0))
+        // Verify we don't add the version number into the symbols that don't have availability annotation.
+        guard let availability = (context.documentationCache["c:@F@SymbolWithoutAvailability"]?.semantic as? Symbol)?.availability?.availability else {
+            XCTFail("Did not find availability for symbol 'c:@F@SymbolWithoutAvailability'")
+            return
+        }
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "iOS" }))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "iOS" })?.introducedVersion, nil)
+        // Verify we remove the version from the module availability information.
+        var identifier = ResolvedTopicReference(bundleIdentifier: "test", path: "/documentation/MyModule", fragment: nil, sourceLanguage: .swift)
+        var node = try context.entity(with: identifier)
+        var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: identifier)
+        var renderNode = translator.visit(node.semantic) as! RenderNode
+        XCTAssertEqual(renderNode.metadata.platforms?.count, 1)
+        XCTAssertEqual(renderNode.metadata.platforms?.first?.name, "iOS")
+        XCTAssertEqual(renderNode.metadata.platforms?.first?.introduced, nil)
+        
+        // Add an extra default availability to test behaviour when mixin in source with default behaviour.
+        (bundle, context) = try setupContext(defaultAvailability: """
+               <dict>
+                   <key>name</key>
+                   <string>iOS</string>
+                   <key>version</key>
+                   <string>8.0</string>
+               </dict>
+               <dict>
+                  <key>name</key>
+                  <string>watchOS</string>
+               </dict>
+               """
+        )
+        
+        // Verify we add the version number into the symbols that have availability annotation.
+        guard let availability = (context.documentationCache["c:@F@SymbolWithAvailability"]?.semantic as? Symbol)?.availability?.availability else {
+            XCTFail("Did not find availability for symbol 'c:@F@SymbolWithAvailability'")
+            return
+        }
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "iOS" }))
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "watchOS" }))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "iOS" })?.introducedVersion, SymbolGraph.SemanticVersion(major: 10, minor: 0, patch: 0))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "watchOS" })?.introducedVersion, nil)
+        
+        guard let availability = (context.documentationCache["c:@F@SymbolWithoutAvailability"]?.semantic as? Symbol)?.availability?.availability else {
+            XCTFail("Did not find availability for symbol 'c:@F@SymbolWithAvailability'")
+            return
+        }
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "iOS" }))
+        XCTAssertNotNil(availability.first(where: { $0.domain?.rawValue == "watchOS" }))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "iOS" })?.introducedVersion, SymbolGraph.SemanticVersion(major: 8, minor: 0, patch: 0))
+        XCTAssertEqual(availability.first(where: { $0.domain?.rawValue == "watchOS" })?.introducedVersion, nil)
+        
+        // Verify the module availability shows as expected.
+        identifier = ResolvedTopicReference(bundleIdentifier: "test", path: "/documentation/MyModule", fragment: nil, sourceLanguage: .swift)
+        node = try context.entity(with: identifier)
+        translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: identifier)
+        renderNode = translator.visit(node.semantic) as! RenderNode
+        XCTAssertEqual(renderNode.metadata.platforms?.count, 4)
+        var moduleAvailability = try XCTUnwrap(renderNode.metadata.platforms?.first(where: {$0.name == "iOS"}))
+        XCTAssertEqual(moduleAvailability.introduced, "8.0")
+        moduleAvailability = try XCTUnwrap(renderNode.metadata.platforms?.first(where: {$0.name == "watchOS"}))
+        XCTAssertEqual(moduleAvailability.introduced, nil)
+    }
 }