Add basic merge command to combine documentation archives

rdar://114730477

Author: d-ronnqvist

Sources/SwiftDocC/Converter/RenderNode+Coding.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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

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 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2024 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
@@ -23,45 +23,74 @@ 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: 1)
+    public static let currentSchemaVersion = SemanticVersion(major: 0, minor: 1, patch: 2)
 
     /// 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]]
+    public private(set) var interfaceLanguages: [String: [Node]]
 
     /// The values of the image references used in the documentation index.
     public private(set) var references: [String: ImageReference]
 
+    /// The unique identifiers of the archives that are included in the documentation index.
+    public private(set) var includedArchiveIdentifiers: [String]
+    
     enum CodingKeys: CodingKey {
         case schemaVersion
         case interfaceLanguages
         case references
+        case includedArchiveIdentifiers
     }
 
     /// Creates a new render index with the given interface language to node mapping.
     public init(
         interfaceLanguages: [String: [Node]],
-        references: [String: ImageReference] = [:]
+        references: [String: ImageReference] = [:],
+        includedArchiveIdentifiers: [String]
     ) {
         self.schemaVersion = Self.currentSchemaVersion
         self.interfaceLanguages = interfaceLanguages
         self.references = references
+        self.includedArchiveIdentifiers = includedArchiveIdentifiers
     }
 
     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)
+        try container.encodeIfNotEmpty(self.includedArchiveIdentifiers, forKey: .includedArchiveIdentifiers)
     }
 
     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) ?? [:]
+        self.includedArchiveIdentifiers = try container.decodeIfPresent([String].self.self, forKey: .includedArchiveIdentifiers) ?? []
+    }
+    
+    public mutating func merge(_ other: RenderIndex) throws {
+        for (languageID, nodes) in other.interfaceLanguages {
+            interfaceLanguages[languageID, default: []].append(contentsOf: nodes)
+        }
+        
+        try references.merge(other.references) { _, new in throw MergeError.referenceCollision(new.identifier.identifier) }
+        
+        includedArchiveIdentifiers.append(contentsOf: other.includedArchiveIdentifiers)
+    }
+    
+    enum MergeError: DescribedError {
+        case referenceCollision(String)
+        
+        var errorDescription: String {
+            switch self {
+            case .referenceCollision(let reference):
+                return "Collision merging image references. Reference \(reference.singleQuoted) exists in more than one input archive."
+            }
+        }
     }
 }
 
@@ -254,7 +283,8 @@ extension RenderIndex {
                 },
                 uniquingKeysWith: +
             ),
-            references: builder.iconReferences
+            references: builder.iconReferences,
+            includedArchiveIdentifiers: [builder.bundleIdentifier]
         )
     }
 }

Sources/SwiftDocC/Model/Rendering/References/ImageReference.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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

Sources/SwiftDocC/Model/Rendering/References/RenderReference.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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

Sources/SwiftDocC/Model/Rendering/References/VideoReference.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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

Sources/SwiftDocC/Model/Rendering/Tutorial/References/DownloadReference.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderIndex.spec.json

@@ -2,7 +2,7 @@
     "openapi": "3.0.0",
     "info": {
         "description": "Specification of the Swift-DocC Index.json file.",
-        "version": "0.1.0",
+        "version": "0.1.2",
         "title": "RenderIndex"
     },
     "paths": {},
@@ -33,6 +33,12 @@
                             "$ref": "#/components/schemas/ImageRenderReference"
                         }
                     },
+                    "includedArchiveIdentifiers": {
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    }
                 }
             },
             "Node": {

Sources/SwiftDocCTestUtilities/FilesAndFolders.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -251,3 +251,134 @@ extension XCTestCase {
         return temporaryDirectory
     }
 }
+
+// MARK: Dump
+
+extension Folder {
+    /// Creates a file and folder hierarchy from the given file paths.
+    ///
+    /// ## Example
+    /// For example, `makeStructure(filePaths: ["one/two/a.json", "one/two/b.json"])` creates the following files and folders.
+    /// ```
+    /// one/
+    /// ╰─ two/
+    ///    ├─ a.json
+    ///    ╰─ b.json
+    /// ```
+    ///
+    /// - Note: If there are more than one first path component in the provided paths, the return value will contain more than one element.
+    public static func makeStructure(
+        filePaths: [String],
+        isEmptyDirectoryCheck: (String) -> Bool = { _ in false }
+    ) -> [File] {
+        guard !filePaths.isEmpty else {
+            return []
+        }
+        typealias Path = [String]
+        
+        func _makeStructure(paths: [Path], accumulatedBasePath: String) -> [File] {
+            assert(paths.allSatisfy { !$0.isEmpty })
+            
+            let grouped = [String: [Path]](grouping: paths, by: { $0.first! }).mapValues {
+                $0.map { Array($0.dropFirst()) }
+            }
+            
+            return grouped.map { pathComponent, remaining in
+                let absolutePath = "\(accumulatedBasePath)/\(pathComponent)"
+                if remaining == [[]] && !isEmptyDirectoryCheck(absolutePath) {
+                    return TextFile(name: pathComponent, utf8Content: "")
+                } else {
+                    return Folder(name: pathComponent, content: _makeStructure(paths: remaining.filter { !$0.isEmpty }, accumulatedBasePath: absolutePath))
+                }
+            }
+        }
+        
+        if filePaths.allSatisfy({ $0.hasPrefix("/")}) {
+            let subPaths = filePaths.map { $0.dropFirst() }.filter { !$0.isEmpty }
+            return [Folder(name: "", content: _makeStructure(paths: subPaths.map { String($0).components(separatedBy: CharacterSet(charactersIn: "/")) }, accumulatedBasePath: ""))]
+        }
+        
+        return _makeStructure(paths: filePaths.map { $0.components(separatedBy: CharacterSet(charactersIn: "/")) }, accumulatedBasePath: "")
+    }
+}
+
+/// A node in a tree structure that can be printed into a visual representation for debugging.
+private struct DumpableNode {
+    var name: String
+    var children: [DumpableNode]?
+    
+    init(_ file: File) {
+        if let folder = file as? Folder {
+            name = file.name
+            children = folder.content.map { DumpableNode($0) }
+        } else {
+            name = file.name
+            children = nil
+        }
+    }
+}
+
+extension File {
+    /// Returns a stable string representation of the file and folder hierarchy that can be checked in tests.
+    ///
+    /// ## Example
+    /// ```swift
+    /// Folder(name: "one", content: [
+    ///     Folder(name: "two", content: [
+    ///         TextFile(name: "a.json", utf8Content: ""),
+    ///         TextFile(name: "b.json", utf8Content: ""),
+    ///     ])
+    /// ])
+    /// ```
+    /// The string `dump()` for the folder hierarchy above is shown below:
+    /// ```
+    /// one/
+    /// ╰─ two/
+    ///    ├─ a.json
+    ///    ╰─ b.json
+    /// ```
+    public func dump() -> String {
+        Self.dump(.init(self))
+            .trimmingCharacters(in: .newlines) // remove the trailing newline
+    }
+
+    private static func dump(_ node: DumpableNode, decorator: String = "") -> String {
+        var result = ""
+        result.append(decorator)
+        if !decorator.isEmpty {
+            result.append("─ ")
+        }
+        result.append(node.name)
+        guard let children = node.children else {
+            return result + "\n"
+        }
+        result.append("/\n")
+        
+        let sortedChildren = children.sorted(by: { lhs, rhs in
+            // Sort files before folders if the folder name is a prefix of the file name
+            switch (lhs.children, rhs.children) {
+            case (nil, nil):
+                return lhs.name < rhs.name
+            case (nil, _) where lhs.name.hasPrefix(rhs.name):
+                return true
+            case (_, nil) where rhs.name.hasPrefix(lhs.name):
+                return false
+            default:
+                return lhs.name < rhs.name
+            }
+        })
+        
+        for (index, child) in sortedChildren.enumerated() {
+            var decorator = decorator
+            if decorator.hasSuffix("├") {
+                decorator = decorator.dropLast() + "│  "
+            }
+            if decorator.hasSuffix("╰") {
+                decorator = decorator.dropLast() + "   "
+            }
+            let newDecorator = decorator + (index == sortedChildren.count-1 ? "╰" : "├")
+            result.append(dump(child, decorator: newDecorator))
+        }
+        return result
+    }
+}

Sources/SwiftDocCTestUtilities/TestFileSystem.swift

@@ -54,7 +54,7 @@ public class TestFileSystem: FileManagerProtocol, DocumentationWorkspaceDataProv
 
     /// Thread safe access to the file system.
     private var filesLock = NSRecursiveLock()
-    
+
     /// A plain index of paths and their contents.
     var files = [String: Data]()
 
@@ -82,7 +82,7 @@ public class TestFileSystem: FileManagerProtocol, DocumentationWorkspaceDataProv
             let files = try addFolder(folder)
 
             func asCatalog(_ file: File) -> Folder? {
-                if let folder = file as? Folder, folder.absoluteURL.pathExtension == "docc" {
+                if let folder = file as? Folder, URL(fileURLWithPath: folder.name).pathExtension == "docc" {
                     return folder
                 }
                 return nil
@@ -100,7 +100,7 @@ public class TestFileSystem: FileManagerProtocol, DocumentationWorkspaceDataProv
                 let info = try DocumentationBundle.Info(
                     from: try catalog.recursiveContent.mapFirst(where: { $0 as? InfoPlist })?.data(),
                     bundleDiscoveryOptions: nil,
-                    derivedDisplayName: catalog.absoluteURL.deletingPathExtension().lastPathComponent
+                    derivedDisplayName: URL(fileURLWithPath: catalog.name).deletingPathExtension().lastPathComponent
                 )
 
                 let bundle = DocumentationBundle(
@@ -334,11 +334,30 @@ public class TestFileSystem: FileManagerProtocol, DocumentationWorkspaceDataProv
         }
     }
 
-    func dump() -> String {
+    /// Returns a stable string representation of the file system from a given subpath.
+    ///
+    /// - Parameter path: The path to the sub hierarchy to dump to a string representation.
+    /// - Returns: A stable string representation that can be checked in tests.
+    public func dump(subHierarchyFrom path: String = "/") -> String {
         filesLock.lock()
         defer { filesLock.unlock() }
-
-        return files.keys.sorted().joined(separator: "\n")
+        
+        let relevantFilePaths: [String]
+        if path == "/" {
+            relevantFilePaths = Array(files.keys)
+        } else {
+            let lengthToRemove = path.distance(from: path.startIndex, to: path.lastIndex(of: "/")!) + 1
+            
+            relevantFilePaths = files.keys
+                .filter { $0.hasPrefix(path) }
+                .map { String($0.dropFirst(lengthToRemove)) }
+        }
+        return Folder.makeStructure(
+            filePaths: relevantFilePaths,
+            isEmptyDirectoryCheck: { files[$0] == Self.folderFixtureData }
+        )
+        .map { $0.dump() }
+        .joined(separator: "\n")
     }
 
     // This is a convenience utility for testing, not FileManagerProtocol API