Support beta status in navigator (#1249)

* Propagate beta attribute for external entities to the navigator

The `isBeta` attribute is part of `TopicRenderReference` [1], and is already computed based on the platforms [2][3] (though the platform information itself is dropped).

This changes propagates the property to `ExternalRenderNode` and `ExternalRenderNodeMetadataRepresentation` so that we can ultimately store it as part of the navigator `RenderIndex`. [4]

Fixes rdar://155521394.

[1]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift#L82-L85
[2]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L158
[3]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L592-L598
[4]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift#L251

* Add beta attribute to NavigatorIndexableRenderMetadataRepresentation

Adds a computed property to `NavigatorIndexableRenderMetadataRepresentation` which derives whether the navigator item `isBeta` or not. This uses the same logic used in other places in the codebase [1].

Fixes rdar://155521394.

[1]: https://github.com/swiftlang/swift-docc/blob/f968935b770b0011d7aa28f59eda22a8407282b7/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L592-L598

* Capture whether an item `isBeta` in the navigator item

Propagates the `isBeta` property to the `NavigatorItem` type from `NavigatorIndexableRenderMetadataRepresentation`.  When we index a new node, whether the item is beta or not will now be captured as part of the navigator

This is preparatory work before this property is propagated to the `RenderIndex` [1].

Fixes rdar://155521394.

[1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift#L257-L259

* Fix serialisation of isBeta and isExternal properties

The isBeta and isExternal properties weren't being serialised as part of `NavigatorItem`.

These properties are used to initialise to `RenderIndex.Node` during the conversion to `index.json` [1] and must be preserved when navigator indexes are written to disk [2] so that when they are read [3], we don't drop beta and external information.

This serialisation happens during the `finalize` step [4] and the deserialisation can be invoked via `NavigatorIndex.readNavigatorIndex` [5].

Otherwise, the values can be lost on serialisation roundtrip.

[1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift#L329
[2]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift#L195
[3]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorTree.swift#L266
[4]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift#L1193
[5]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift#L157

* Propagates `isBeta` property to RenderIndex

All that was left was that on initialisation of a `RenderIndex.Node`, we propagate the `isBeta` value from the `NavigatorItem`.

With this change, beta information is now available in the navigator, encoded as `"beta": true` in the resulting `index.json` file.

Fixes rdar://155521394.

* Check that we don't cause an out of bounds crash when accessing the new values.

Added an assertion that checks that the cursor plus the lenght of the memory
to be decoded is less or equal than the length of the entire memory for the
raw value that has been passed, avoiding a runtime crash.

Also both if statements were combined into a signgle one since, as pointed out
in [1], `isBeta` and `isExternal` have to either both exists or not.

---

[1] #1249 (comment)

* Update license year in the header of the modified files.

---------

Co-authored-by: Sofia Rodriguez Morales <[email protected]>

Author: anferbui

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -771,7 +771,8 @@ extension NavigatorIndex {
                 platformMask: platformID,
                 availabilityID: UInt64(availabilityID),
                 icon: renderNode.icon,
-                isExternal: external
+                isExternal: external,
+                isBeta: renderNode.metadata.isBeta
             )
             navigationItem.path = identifierPath
 

Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2025 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
@@ -49,6 +49,11 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
 
     var icon: RenderReferenceIdentifier? = nil
 
+    /// A value that indicates whether this item is built for a beta platform.
+    ///
+    /// This value is `false` if the referenced item is not a symbol.
+    var isBeta: Bool = false
+    
     /// Whether the item has originated from an external reference.
     ///
     /// Used for determining whether stray navigation items should remain part of the final navigator.
@@ -66,7 +71,7 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - path: The path to load the content.
         - icon: A reference to a custom image for this navigator item.
      */
-    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String, icon: RenderReferenceIdentifier? = nil, isExternal: Bool = false) {
+    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String, icon: RenderReferenceIdentifier? = nil, isExternal: Bool = false, isBeta: Bool = false) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
@@ -75,6 +80,7 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         self.path = path
         self.icon = icon
         self.isExternal = isExternal
+        self.isBeta = isBeta
     }
 
     /**
@@ -87,15 +93,18 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - platformMask: The mask indicating for which platform the page is available.
         - availabilityID:  The identifier of the availability information of the page.
         - icon: A reference to a custom image for this navigator item.
+        - isExternal: A flag indicating whether the navigator item belongs to an external documentation archive.
+        - isBeta: A flag indicating whether the navigator item is in beta.
      */
-    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, icon: RenderReferenceIdentifier? = nil, isExternal: Bool = false) {
+    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, icon: RenderReferenceIdentifier? = nil, isExternal: Bool = false, isBeta: Bool = false) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
         self.platformMask = platformMask
         self.availabilityID = availabilityID
         self.icon = icon
         self.isExternal = isExternal
+        self.isBeta = isBeta
     }
 
     // MARK: - Serialization and Deserialization
@@ -137,8 +146,27 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
 
         let pathData = data[cursor..<cursor + Int(pathLength)]
         self.path = String(data: pathData, encoding: .utf8)!
+        cursor += Int(pathLength)
 
-        assert(cursor+Int(pathLength) == data.count)
+        // isBeta and isExternal should be encoded because they are relevant when creating a RenderIndex node.
+        // Without proper serialization, these indicators would be lost when navigator indexes are loaded from disk.
+        
+        length = MemoryLayout<UInt8>.stride
+        // To ensure backwards compatibility, handle both when `isBeta` and `isExternal` has been encoded and when it hasn't
+        if cursor < data.count {
+            // Encoded `isBeta`
+            assert(cursor + length <= data.count, "The serialized data is malformed: `isBeta` value should not extend past the end of the data")
+            let betaValue: UInt8 = unpackedValueFromData(data[cursor..<cursor + length])
+            cursor += length
+            self.isBeta = betaValue != 0
+            // Encoded `isExternal`
+            assert(cursor + length <= data.count, "The serialized data is malformed: `isExternal` value should not extend past the end of the data")
+            let externalValue: UInt8 = unpackedValueFromData(data[cursor..<cursor + length])
+            cursor += length
+            self.isExternal = externalValue != 0
+        }
+
+        assert(cursor == data.count)
     }
 
     /// Returns the `Data` representation of the current `NavigatorItem` instance.
@@ -155,6 +183,9 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         data.append(Data(title.utf8))
         data.append(Data(path.utf8))
 
+        data.append(packedDataFromValue(isBeta ? UInt8(1) : UInt8(0)))
+        data.append(packedDataFromValue(isExternal ? UInt8(1) : UInt8(0)))
+        
         return data
     }
 
@@ -167,7 +198,9 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
             languageID: \(languageID),
             title: \(title),
             platformMask: \(platformMask),
-            availabilityID: \(availabilityID)
+            availabilityID: \(availabilityID),
+            isBeta: \(isBeta),
+            isExternal: \(isExternal)
         }
         """
     }

Sources/SwiftDocC/Indexing/Navigator/RenderNode+NavigatorIndex.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2024-2025 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
@@ -40,6 +40,7 @@ protocol NavigatorIndexableRenderMetadataRepresentation {
     var roleHeading: String? { get }
     var symbolKind: String? { get }
     var platforms: [AvailabilityRenderItem]? { get }
+    var isBeta: Bool { get }
 }
 
 extension NavigatorIndexableRenderNodeRepresentation {
@@ -122,6 +123,16 @@ struct RenderNodeVariantView: NavigatorIndexableRenderNodeRepresentation {
     }
 }
 
+extension NavigatorIndexableRenderMetadataRepresentation {
+    var isBeta: Bool {
+        guard let platforms, !platforms.isEmpty else {
+            return false
+        }
+        
+        return platforms.allSatisfy { $0.isBeta == true }
+    }
+}
+
 private let typesThatShouldNotUseNavigatorTitle: Set<NavigatorIndex.PageType> = [
     .framework, .class, .structure, .enumeration, .protocol, .typeAlias, .associatedType, .extension
 ]

Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022-2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2025 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
@@ -92,6 +92,7 @@ public struct RenderIndex: Codable, Equatable {
                 pageType: .framework,
                 isDeprecated: false,
                 isExternal: false,
+                isBeta: false,
                 children: nodes,
                 icon: nil
             )
@@ -245,6 +246,7 @@ extension RenderIndex {
             pageType: NavigatorIndex.PageType?,
             isDeprecated: Bool,
             isExternal: Bool,
+            isBeta: Bool,
             children: [Node],
             icon: RenderReferenceIdentifier?
         ) {
@@ -253,10 +255,8 @@ extension RenderIndex {
 
             self.isDeprecated = isDeprecated
             self.isExternal = isExternal
-            
-            // Currently Swift-DocC doesn't support marking a node as beta in the navigation index
-            // so we default to `false` here.
-            self.isBeta = false
+            self.isBeta = isBeta
+
             self.icon = icon
 
             guard let pageType else {
@@ -327,6 +327,7 @@ extension RenderIndex.Node {
             pageType: NavigatorIndex.PageType(rawValue: node.item.pageType),
             isDeprecated: isDeprecated,
             isExternal: node.item.isExternal,
+            isBeta: node.item.isBeta,
             children: node.children.map {
                 RenderIndex.Node.fromNavigatorTreeNode($0, in: navigatorIndex, with: builder)
             },

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver+NavigatorIndex.swift

@@ -77,6 +77,13 @@ package struct ExternalRenderNode {
             RenderNode.Variant(traits: [.interfaceLanguage($0.id)], paths: [externalEntity.topicRenderReference.url])
         }
     }
+    
+    /// A value that indicates whether this symbol is built for a beta platform
+    ///
+    /// This value is `false` if the referenced page is not a symbol.
+    var isBeta: Bool {
+        externalEntity.topicRenderReference.isBeta
+    }
 }
 
 /// A language specific representation of an external render node value for building a navigator index.
@@ -110,7 +117,8 @@ struct NavigatorExternalRenderNode: NavigatorIndexableRenderNodeRepresentation {
             externalID: renderNode.externalIdentifier.identifier,
             role: renderNode.role,
             symbolKind: renderNode.symbolKind?.identifier,
-            images: renderNode.images
+            images: renderNode.images,
+            isBeta: renderNode.isBeta
         )
     }
 }
@@ -123,6 +131,7 @@ struct ExternalRenderNodeMetadataRepresentation: NavigatorIndexableRenderMetadat
     var role: String?
     var symbolKind: String?
     var images: [TopicImage]
+    var isBeta: Bool
 
     // Values that we have insufficient information to derive.
     // These are needed to conform to the navigator indexable metadata protocol.

Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift

@@ -21,31 +21,35 @@ class ExternalRenderNodeTests: XCTestCase {
                 referencePath: "/path/to/external/swiftArticle",
                 title: "SwiftArticle",
                 kind: .article,
-                language: .swift
+                language: .swift,
+                platforms: [.init(name: "iOS", introduced: nil, isBeta: false)]
             )
         )
         externalResolver.entitiesToReturn["/path/to/external/objCArticle"] = .success(
             .init(
                 referencePath: "/path/to/external/objCArticle",
                 title: "ObjCArticle",
                 kind: .article,
-                language: .objectiveC
+                language: .objectiveC,
+                platforms: [.init(name: "macOS", introduced: nil, isBeta: true)]
             )
         )
         externalResolver.entitiesToReturn["/path/to/external/swiftSymbol"] = .success(
             .init(
                 referencePath: "/path/to/external/swiftSymbol",
                 title: "SwiftSymbol",
                 kind: .class,
-                language: .swift
+                language: .swift,
+                platforms: [.init(name: "iOS", introduced: nil, isBeta: true)]
             )
         )
         externalResolver.entitiesToReturn["/path/to/external/objCSymbol"] = .success(
             .init(
                 referencePath: "/path/to/external/objCSymbol",
                 title: "ObjCSymbol",
                 kind: .function,
-                language: .objectiveC
+                language: .objectiveC,
+                platforms: [.init(name: "macOS", introduced: nil, isBeta: false)]
             )
         )
         return externalResolver
@@ -89,24 +93,28 @@ class ExternalRenderNodeTests: XCTestCase {
         XCTAssertEqual(externalRenderNodes[0].symbolKind, nil)
         XCTAssertEqual(externalRenderNodes[0].role, "article")
         XCTAssertEqual(externalRenderNodes[0].externalIdentifier.identifier, "doc://com.test.external/path/to/external/objCArticle")
-        
+        XCTAssertTrue(externalRenderNodes[0].isBeta)
+
         XCTAssertEqual(externalRenderNodes[1].identifier.absoluteString, "doc://org.swift.MixedLanguageFramework/example/path/to/external/objCSymbol")
         XCTAssertEqual(externalRenderNodes[1].kind, .symbol)
         XCTAssertEqual(externalRenderNodes[1].symbolKind, nil)
         XCTAssertEqual(externalRenderNodes[1].role, "symbol")
         XCTAssertEqual(externalRenderNodes[1].externalIdentifier.identifier, "doc://com.test.external/path/to/external/objCSymbol")
+        XCTAssertFalse(externalRenderNodes[1].isBeta)
 
         XCTAssertEqual(externalRenderNodes[2].identifier.absoluteString, "doc://org.swift.MixedLanguageFramework/example/path/to/external/swiftArticle")
         XCTAssertEqual(externalRenderNodes[2].kind, .article)
         XCTAssertEqual(externalRenderNodes[2].symbolKind, nil)
         XCTAssertEqual(externalRenderNodes[2].role, "article")
         XCTAssertEqual(externalRenderNodes[2].externalIdentifier.identifier, "doc://com.test.external/path/to/external/swiftArticle")
+        XCTAssertFalse(externalRenderNodes[2].isBeta)
 
         XCTAssertEqual(externalRenderNodes[3].identifier.absoluteString, "doc://org.swift.MixedLanguageFramework/example/path/to/external/swiftSymbol")
         XCTAssertEqual(externalRenderNodes[3].kind, .symbol)
         XCTAssertEqual(externalRenderNodes[3].symbolKind, nil)
         XCTAssertEqual(externalRenderNodes[3].role, "symbol")
         XCTAssertEqual(externalRenderNodes[3].externalIdentifier.identifier, "doc://com.test.external/path/to/external/swiftSymbol")
+        XCTAssertTrue(externalRenderNodes[3].isBeta)
     }
 
     func testExternalRenderNodeVariantRepresentation() throws {
@@ -146,14 +154,16 @@ class ExternalRenderNodeTests: XCTestCase {
         )
         XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.title, swiftTitle)
         XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.navigatorTitle, navigatorTitle)
-        
+        XCTAssertFalse(swiftNavigatorExternalRenderNode.metadata.isBeta)
+
         let objcNavigatorExternalRenderNode = try XCTUnwrap(
             NavigatorExternalRenderNode(renderNode: externalRenderNode, trait: .interfaceLanguage("objc"))
         )
         XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.title, occTitle)
         XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.navigatorTitle, occNavigatorTitle)
+        XCTAssertFalse(objcNavigatorExternalRenderNode.metadata.isBeta)
     }
-    
+
     func testNavigatorWithExternalNodes() async throws {
         let externalResolver = generateExternalResolver()
         let (_, bundle, context) = try await testBundleAndContext(
@@ -208,6 +218,10 @@ class ExternalRenderNodeTests: XCTestCase {
         XCTAssertEqual(occExternalNodes.map(\.title), ["ObjCArticle", "ObjCSymbol"])
         XCTAssert(swiftExternalNodes.allSatisfy(\.isExternal))
         XCTAssert(occExternalNodes.allSatisfy(\.isExternal))
+        XCTAssert(swiftExternalNodes.first { $0.title == "SwiftArticle" }?.isBeta == false)
+        XCTAssert(swiftExternalNodes.first { $0.title == "SwiftSymbol" }?.isBeta == true)
+        XCTAssert(occExternalNodes.first { $0.title == "ObjCArticle" }?.isBeta == true)
+        XCTAssert(occExternalNodes.first { $0.title == "ObjCSymbol" }?.isBeta == false)
     }
 
     func testNavigatorWithExternalNodesOnlyAddsCuratedNodesToNavigator() async throws {
@@ -269,4 +283,52 @@ class ExternalRenderNodeTests: XCTestCase {
         XCTAssert(swiftExternalNodes.allSatisfy(\.isExternal))
         XCTAssert(occExternalNodes.allSatisfy(\.isExternal))
     }
+
+    func testExternalRenderNodeVariantRepresentationWhenIsBeta() throws {
+        let renderReferenceIdentifier = RenderReferenceIdentifier(forExternalLink: "doc://com.test.external/path/to/external/symbol")
+        
+        // Variants for the title
+        let swiftTitle = "Swift Symbol"
+        let occTitle = "Occ Symbol"
+        
+        // Variants for the navigator title
+        let navigatorTitle: [DeclarationRenderSection.Token] = [.init(text: "symbol", kind: .identifier)]
+        let occNavigatorTitle: [DeclarationRenderSection.Token] = [.init(text: "occ_symbol", kind: .identifier)]
+        
+        // Variants for the fragments
+        let fragments: [DeclarationRenderSection.Token] = [.init(text: "func", kind: .keyword), .init(text: "symbol", kind: .identifier)]
+        let occFragments: [DeclarationRenderSection.Token] = [.init(text: "func", kind: .keyword), .init(text: "occ_symbol", kind: .identifier)]
+        
+        let externalEntity = LinkResolver.ExternalEntity(
+            topicRenderReference: .init(
+                identifier: renderReferenceIdentifier,
+                titleVariants: .init(defaultValue: swiftTitle, objectiveCValue: occTitle),
+                abstractVariants: .init(defaultValue: []),
+                url: "/example/path/to/external/symbol",
+                kind: .symbol,
+                fragmentsVariants: .init(defaultValue: fragments, objectiveCValue: occFragments),
+                navigatorTitleVariants: .init(defaultValue: navigatorTitle, objectiveCValue: occNavigatorTitle),
+                isBeta: true
+            ),
+            renderReferenceDependencies: .init(),
+            sourceLanguages: [SourceLanguage(name: "swift"), SourceLanguage(name: "objc")])
+        let externalRenderNode = ExternalRenderNode(
+            externalEntity: externalEntity,
+            bundleIdentifier: "com.test.external"
+        )
+        
+        let swiftNavigatorExternalRenderNode = try XCTUnwrap(
+            NavigatorExternalRenderNode(renderNode: externalRenderNode)
+        )
+        XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.title, swiftTitle)
+        XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.navigatorTitle, navigatorTitle)
+        XCTAssertTrue(swiftNavigatorExternalRenderNode.metadata.isBeta)
+
+        let objcNavigatorExternalRenderNode = try XCTUnwrap(
+            NavigatorExternalRenderNode(renderNode: externalRenderNode, trait: .interfaceLanguage("objc"))
+        )
+        XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.title, occTitle)
+        XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.navigatorTitle, occNavigatorTitle)
+        XCTAssertTrue(objcNavigatorExternalRenderNode.metadata.isBeta)
+    }
 }