Add page image directive

Add custom icon support to navigator index

Extract SVG IDs

Update Render Node and Index spec for `@PageImage`

Fix failing tests

# Conflicts:
#	Sources/SwiftDocC/Model/DocumentationNode.swift
#	Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift
#	Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift

Author: ethan-kusters

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -753,11 +753,14 @@ extension NavigatorIndex {
                 }
             }
 
-            let navigationItem = NavigatorItem(pageType: renderNode.navigatorPageType().rawValue,
-                                           languageID: language.mask,
-                                           title: title,
-                                           platformMask: platformID,
-                                           availabilityID: UInt64(availabilityID))
+            let navigationItem = NavigatorItem(
+                pageType: renderNode.navigatorPageType().rawValue,
+                languageID: language.mask,
+                title: title,
+                platformMask: platformID,
+                availabilityID: UInt64(availabilityID),
+                icon: renderNode.icon
+            )
             navigationItem.path = identifierPath
 
             // Index the USR for the given identifier
@@ -894,7 +897,8 @@ extension NavigatorIndex {
         public func finalize(
             estimatedCount: Int? = nil,
             emitJSONRepresentation: Bool = true,
-            emitLMDBRepresentation: Bool = true
+            emitLMDBRepresentation: Bool = true,
+            context: DocumentationContext? = nil
         ) {
             precondition(!isCompleted, "Finalizing an already completed index build multiple times is not possible.")
 
@@ -1020,7 +1024,7 @@ extension NavigatorIndex {
             }
 
             if emitJSONRepresentation {
-                let renderIndex = RenderIndex.fromNavigatorIndex(navigatorIndex, with: self)
+                let renderIndex = RenderIndex.fromNavigatorIndex(navigatorIndex, with: self, context: context)
 
                 let jsonEncoder = JSONEncoder()
                 if shouldPrettyPrintOutputJSON {

Sources/SwiftDocC/Indexing/Navigator/NavigatorItem.swift

@@ -47,6 +47,8 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
     /// If available, a hashed USR of this entry and its language information.
     internal var usrIdentifier: String? = nil
 
+    var icon: RenderReferenceIdentifier? = nil
+    
     /**
      Initialize a `NavigatorItem` with the given data.
 
@@ -58,13 +60,14 @@ public final class NavigatorItem: Serializable, Codable, Equatable, CustomString
         - availabilityID:  The identifier of the availability information of the page.
         - path: The path to load the content.
      */
-    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String) {
+    init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, path: String, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
         self.platformMask = platformMask
         self.availabilityID = availabilityID
         self.path = path
+        self.icon = icon
     }
 
     /**
@@ -77,12 +80,13 @@ 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.
      */
-    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64) {
+    public init(pageType: UInt8, languageID: UInt8, title: String, platformMask: UInt64, availabilityID: UInt64, icon: RenderReferenceIdentifier? = nil) {
         self.pageType = pageType
         self.languageID = languageID
         self.title = title
         self.platformMask = platformMask
         self.availabilityID = availabilityID
+        self.icon = icon
     }
 
     // MARK: - Serialization and Deserialization

Sources/SwiftDocC/Indexing/IndexJSON/Index.swift renamed to Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift

@@ -23,20 +23,46 @@ import SymbolKit
 /// `Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderIndex.spec.json`.
 public struct RenderIndex: Codable, Equatable {
     /// The current schema version of the Index JSON spec.
-    public static let currentSchemaVersion = SemanticVersion(major: 0, minor: 1, patch: 0)
+    public static let currentSchemaVersion = SemanticVersion(major: 0, minor: 1, patch: 1)
 
     /// The version of the RenderIndex spec that was followed when creating this index.
     public let schemaVersion: SemanticVersion
 
     /// A mapping of interface languages to the index nodes they contain.
     public let interfaceLanguages: [String: [Node]]
 
+    /// The values of the image references used in the documentation index.
+    public private(set) var references: [String: ImageReference]
+    
+    enum CodingKeys: CodingKey {
+        case schemaVersion
+        case interfaceLanguages
+        case references
+    }
+    
     /// Creates a new render index with the given interface language to node mapping.
     public init(
-        interfaceLanguages: [String: [Node]]
+        interfaceLanguages: [String: [Node]],
+        references: [String: ImageReference] = [:]
     ) {
         self.schemaVersion = Self.currentSchemaVersion
         self.interfaceLanguages = interfaceLanguages
+        self.references = references
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.schemaVersion, forKey: .schemaVersion)
+        try container.encode(self.interfaceLanguages, forKey: .interfaceLanguages)
+        
+        try container.encodeIfNotEmpty(self.references, forKey: .references)
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.schemaVersion = try container.decode(SemanticVersion.self, forKey: .schemaVersion)
+        self.interfaceLanguages = try container.decode([String : [RenderIndex.Node]].self, forKey: .interfaceLanguages)
+        self.references = try container.decodeIfPresent([String : ImageReference].self, forKey: .references) ?? [:]
     }
 }
 
@@ -73,6 +99,9 @@ extension RenderIndex {
         ///
         /// Allows renderers to use a specific design treatment for render index nodes that mark the node as in beta.
         public let isBeta: Bool
+        
+        /// Reference to the image that should be used to represent this node.
+        public let icon: RenderReferenceIdentifier?
 
         enum CodingKeys: String, CodingKey {
             case title
@@ -82,6 +111,7 @@ extension RenderIndex {
             case deprecated
             case external
             case beta
+            case icon
         }
 
         public func encode(to encoder: Encoder) throws {
@@ -107,6 +137,8 @@ extension RenderIndex {
             if isBeta {
                 try container.encode(isBeta, forKey: .beta)
             }
+            
+            try container.encodeIfPresent(icon, forKey: .icon)
         }
 
         public init(from decoder: Decoder) throws {
@@ -126,6 +158,8 @@ extension RenderIndex {
 
             // `isBeta` defaults to false if it's not specified
             isBeta = try values.decodeIfPresent(Bool.self, forKey: .beta) ?? false
+            
+            icon = try values.decodeIfPresent(RenderReferenceIdentifier.self, forKey: .icon)
         }
 
         /// Creates a new node with the given title, path, type, and children.
@@ -146,7 +180,8 @@ extension RenderIndex {
             children: [Node]?,
             isDeprecated: Bool,
             isExternal: Bool,
-            isBeta: Bool
+            isBeta: Bool,
+            icon: RenderReferenceIdentifier? = nil
         ) {
             self.title = title
             self.path = path
@@ -155,14 +190,16 @@ extension RenderIndex {
             self.isDeprecated = isDeprecated
             self.isExternal = isExternal
             self.isBeta = isBeta
+            self.icon = nil
         }
 
         init(
             title: String,
             path: String,
             pageType: NavigatorIndex.PageType?,
             isDeprecated: Bool,
-            children: [Node]
+            children: [Node],
+            icon: RenderReferenceIdentifier?
         ) {
             self.title = title
             self.children = children.isEmpty ? nil : children
@@ -174,6 +211,7 @@ extension RenderIndex {
             self.isExternal = false
 
             self.isBeta = false
+            self.icon = icon
 
             guard let pageType = pageType else {
                 self.type = nil
@@ -193,14 +231,20 @@ extension RenderIndex {
 }
 
 extension RenderIndex {
-    static func fromNavigatorIndex(_ navigatorIndex: NavigatorIndex, with builder: NavigatorIndex.Builder) -> RenderIndex {
+    static func fromNavigatorIndex(
+        _ navigatorIndex: NavigatorIndex,
+        with builder: NavigatorIndex.Builder,
+        context: DocumentationContext?
+    ) -> RenderIndex {
         // The immediate children of the root represent the interface languages
         // described in this navigator tree.
         let interfaceLanguageRoots = navigatorIndex.navigatorTree.root.children
 
         let languageMaskToLanguage = navigatorIndex.languageMaskToLanguage
 
-        return RenderIndex(
+        var iconIdentifiers = [RenderReferenceIdentifier]()
+        
+        var renderIndex = RenderIndex(
             interfaceLanguages: Dictionary(
                 interfaceLanguageRoots.compactMap { interfaceLanguageRoot in
                     // If an interface language in the given navigator tree does not exist
@@ -210,19 +254,51 @@ extension RenderIndex {
 
                     return (
                         language: languageID,
-                        children: interfaceLanguageRoot.children.map {
-                            RenderIndex.Node.fromNavigatorTreeNode($0, in: navigatorIndex, with: builder)
+                        children: interfaceLanguageRoot.children.map { node in
+                            RenderIndex.Node.fromNavigatorTreeNode(
+                                node,
+                                in: navigatorIndex,
+                                with: builder,
+                                iconIdentifiers: &iconIdentifiers
+                            )
                         }
                     )
                 },
                 uniquingKeysWith: +
             )
         )
+        
+        guard let context = context else {
+            return renderIndex
+        }
+        
+        let icons = iconIdentifiers.lazy.compactMap { iconReference -> ImageReference? in
+            guard let dataAsset = context.resolveAsset(
+                named: iconReference.identifier,
+                bundleIdentifier: builder.bundleIdentifier
+            ) else {
+                return nil
+            }
+                    
+            return ImageReference(identifier: iconReference, imageAsset: dataAsset)
+        }
+
+        let mappedReferences = Dictionary(
+            uniqueKeysWithValues: icons.map { ($0.identifier.identifier, $0) }
+        )
+        
+        renderIndex.references = mappedReferences
+        return renderIndex
     }
 }
 
 extension RenderIndex.Node {
-    static func fromNavigatorTreeNode(_ node: NavigatorTree.Node, in navigatorIndex: NavigatorIndex, with builder: NavigatorIndex.Builder) -> RenderIndex.Node {
+    fileprivate static func fromNavigatorTreeNode(
+        _ node: NavigatorTree.Node,
+        in navigatorIndex: NavigatorIndex,
+        with builder: NavigatorIndex.Builder,
+        iconIdentifiers: inout [RenderReferenceIdentifier]
+    ) -> RenderIndex.Node {
         // If this node was deprecated on any platform version mark it as deprecated.
         let isDeprecated: Bool
 
@@ -235,14 +311,19 @@ extension RenderIndex.Node {
             isDeprecated = false
         }
 
+        if let iconIdentifier = node.item.icon {
+            iconIdentifiers.append(iconIdentifier)
+        }
+        
         return RenderIndex.Node(
             title: node.item.title,
             path: node.item.path,
             pageType: NavigatorIndex.PageType(rawValue: node.item.pageType),
             isDeprecated: isDeprecated,
             children: node.children.map {
-                RenderIndex.Node.fromNavigatorTreeNode($0, in: navigatorIndex, with: builder)
-            }
+                RenderIndex.Node.fromNavigatorTreeNode($0, in: navigatorIndex, with: builder, iconIdentifiers: &iconIdentifiers)
+            },
+            icon: node.item.icon
         )
     }
 }

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -71,10 +71,11 @@ struct DataAssetManager {
         try! NSRegularExpression(pattern: "(?!^)(?<=@)[1|2|3]x(?=\\.\\w*$)")
     }()
 
-    private mutating func referenceMetaInformationForDataURL(_ dataURL: URL, dataProvider: DocumentationContextDataProvider? = nil, bundle documentationBundle: DocumentationBundle? = nil) throws -> (reference: String, traits: DataTraitCollection) {
+    private mutating func referenceMetaInformationForDataURL(_ dataURL: URL, dataProvider: DocumentationContextDataProvider? = nil, bundle documentationBundle: DocumentationBundle? = nil) throws -> (reference: String, traits: DataTraitCollection, metadata: DataAsset.Metadata) {
         var dataReference = dataURL.path
         var traitCollection = DataTraitCollection()
 
+        var metadata = DataAsset.Metadata()
         if DocumentationContext.isFileExtension(dataURL.pathExtension, supported: .video) {
             // In case of a video read its traits: dark/light variants.
 
@@ -103,9 +104,13 @@ struct DataAssetManager {
             // Remove the display scale information from the image reference.
             dataReference = dataReference.replacingOccurrences(of: "@\(displayScale.rawValue)", with: "")
             traitCollection = .init(userInterfaceStyle: userInterfaceStyle, displayScale: displayScale)
+            
+            if dataURL.pathExtension.lowercased() == "svg" {
+                metadata.svgID = SVGIDExtractor.extractID(from: dataURL)
+            }
         }
 
-        return (reference: dataReference, traits: traitCollection)
+        return (reference: dataReference, traits: traitCollection, metadata: metadata)
     }
 
     /**
@@ -123,7 +128,7 @@ struct DataAssetManager {
             // Store the image with given scale information and display scale.
             let name = referenceURL.lastPathComponent
             storage[name, default: DataAsset()]
-                .register(dataURL, with: meta.traits)
+                .register(dataURL, with: meta.traits, metadata: meta.metadata)
 
             if name.contains(".") {
                 let nameNoExtension = referenceURL.deletingPathExtension().lastPathComponent
@@ -156,7 +161,7 @@ struct DataAssetManager {
 /// ### Asset Traits
 /// - ``DisplayScale``
 /// - ``UserInterfaceStyle``
-public struct DataAsset: Codable {
+public struct DataAsset: Codable, Equatable {
     /// A context in which you intend clients to use a data asset.
     public enum Context: String, CaseIterable, Codable {
         /// An asset that a user intends to view alongside documentation content.
@@ -172,6 +177,9 @@ public struct DataAsset: Codable {
     /// depending on the system's appearance.
     public var variants = [DataTraitCollection: URL]()
 
+    /// The metadata associated with each variant.
+    public var metadata = [URL : Metadata]()
+    
     /// The context in which you intend to use the data asset.
     public var context = Context.display
 
@@ -182,8 +190,9 @@ public struct DataAsset: Codable {
     /// - Parameters:
     ///   - url: The location of the variant.
     ///   - traitCollection: The trait collection associated with the variant.
-    public mutating func register(_ url: URL, with traitCollection: DataTraitCollection) {
+    public mutating func register(_ url: URL, with traitCollection: DataTraitCollection, metadata: Metadata = Metadata()) {
         variants[traitCollection] = url
+        self.metadata[url] = metadata
     }
 
     /// Returns the data that is registered to the data asset that best matches the given trait collection.
@@ -210,6 +219,21 @@ public struct DataAsset: Codable {
 
 }
 
+extension DataAsset {
+    /// Metadata specific to this data asset.
+    public struct Metadata: Codable, Equatable {
+        /// The first ID found in the SVG asset.
+        ///
+        /// This value is nil if the data asset is not an SVG or if it is an SVG that does not contain an ID.
+        public var svgID: String?
+        
+        /// Create a new data asset metadata with the given SVG ID.
+        public init(svgID: String? = nil) {
+            self.svgID = svgID
+        }
+    }
+}
+
 /// A collection of environment traits for an asset variant.
 ///
 /// Traits describe properties of a rendering environment, such as a user-interface style (light or dark mode) and display-scale