emit ExternalLocationReferences into assets digest (#476)

rdar://105226975

Author: QuietMisdreavus

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

@@ -13,7 +13,7 @@ import Foundation
 public extension RenderNode {
     /// All image, video, file, and download references of this node, grouped by their type.
     var assetReferences: [RenderReferenceType: [RenderReference]] {
-        let assetTypes = [RenderReferenceType.image, .video, .file, .download]
+        let assetTypes = [RenderReferenceType.image, .video, .file, .download, .externalLocation]
         return .init(grouping: references.values.lazy.filter({ assetTypes.contains($0.type) }), by: { $0.type })
     }    
 }

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

@@ -22,7 +22,7 @@ import Foundation
 public struct ExternalLocationReference: RenderReference, URLReference {
     public static var baseURL: URL = DownloadReference.baseURL
 
-    public private(set) var type: RenderReferenceType = .download
+    public private(set) var type: RenderReferenceType = .externalLocation
 
     public var identifier: RenderReferenceIdentifier
 

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

@@ -26,7 +26,7 @@ public protocol RenderReference: Codable {
 
 /// The type of a reference.
 public enum RenderReferenceType: String, Codable, Equatable {
-    case image, video, file, fileType, xcodeRequirement, topic, section, download, link
+    case image, video, file, fileType, xcodeRequirement, topic, section, download, link, externalLocation
     case unresolvable
 }
 

Sources/SwiftDocC/Model/Rendering/RenderNode/CodableRenderReference.swift

@@ -43,6 +43,8 @@ struct CodableRenderReference: Codable {
             reference = try UnresolvedRenderReference(from: decoder)
         case .link:
             reference = try LinkReference(from: decoder)
+        case .externalLocation:
+            reference = try ExternalLocationReference(from: decoder)
         }
     }
 

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

@@ -1816,7 +1816,7 @@
                 "properties": {
                     "type": {
                         "type": "string",
-                        "enum": ["download"]
+                        "enum": ["download", "externalLocation"]
                     },
                     "identifier": {
                         "type": "string"

Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertFileWritingConsumer.swift

@@ -161,6 +161,14 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer {
         let assetsURL = targetFolder.appendingPathComponent("assets.json", isDirectory: false)
         let data = try encode(digest)
         try fileManager.createFile(at: assetsURL, contents: data)
+
+        let externalAssetsDigest = Digest.ExternalAssets(
+            externalLocations: (uniqueAssets[.externalLocation] as? [ExternalLocationReference]) ?? []
+        )
+
+        let externalAssetsURL = targetFolder.appendingPathComponent("external-assets.json", isDirectory: false)
+        let externalAssetsData = try encode(externalAssetsDigest)
+        try fileManager.createFile(at: externalAssetsURL, contents: externalAssetsData)
     }
 
     func consume(benchmarks: Benchmark) throws {
@@ -217,6 +225,10 @@ enum Digest {
         let videos: [VideoReference]
         let downloads: [DownloadReference]
     }
+
+    struct ExternalAssets: Codable {
+        let externalLocations: [ExternalLocationReference]
+    }
 
     struct Diagnostic: Codable {
         struct Location: Codable {

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -31,6 +31,10 @@ class ConvertActionTests: XCTestCase {
         withExtension: "symbols.json",
         subdirectory: "Test Resources"
     )!
+
+    let projectZipFile = Bundle.module.url(
+        forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+        .appendingPathComponent("project.zip")
 
     /// A symbol graph file that has missing symbols.
     let incompleteSymbolGraphFile = TextFile(name: "TechnologyX.symbols.json", utf8Content: """
@@ -1159,6 +1163,132 @@ class ConvertActionTests: XCTestCase {
         XCTAssertEqual(resultAssets.images.map({ $0.identifier.identifier }).sorted(), images.map({ $0.identifier.identifier }).sorted())
     }
 
+    func testDownloadMetadataIsWritenToOutputFolder() throws {
+        let bundle = Folder(name: "unit-test.docc", content: [
+            CopyOfFile(original: projectZipFile),
+            CopyOfFile(original: imageFile, newName: "referenced-tutorials-image.png"),
+
+            TextFile(name: "MyTechnology.tutorial", utf8Content: """
+            @Tutorial(time: 10, projectFiles: project.zip) {
+              @Intro(title: "TechologyX") {}
+
+              @Section(title: "Section") {
+                @Steps {}
+              }
+
+              @Assessments {
+                @MultipleChoice {
+                  text
+                  @Choice(isCorrect: true) {
+                    text
+                    @Justification(reaction: "reaction text") {}
+                  }
+
+                  @Choice(isCorrect: false) {
+                    text
+                    @Justification(reaction: "reaction text") {}
+                  }
+                }
+              }
+            }
+            """),
+
+            TextFile(name: "TechnologyX.tutorial", utf8Content: """
+            @Tutorials(name: TechnologyX) {
+               @Intro(title: "Technology X") {
+                  Learn about some stuff in Technology X.
+               }
+
+               @Volume(name: "Volume 1") {
+                  This volume contains Chapter 1.
+
+                  @Image(source: referenced-tutorials-image.png, alt: "Some alt text")
+
+                  @Chapter(name: "Chapter 1") {
+                     In this chapter, you'll learn about Tutorial 1.
+
+                     @Image(source: referenced-tutorials-image.png, alt: "Some alt text")
+                     @TutorialReference(tutorial: "doc:MyTechnology")
+                  }
+               }
+            }
+            """),
+
+            TextFile(name: "MySample.md", utf8Content: """
+            # My Sample
+
+            @Metadata {
+                @CallToAction(url: "https://example.com/sample.zip", purpose: download)
+            }
+
+            This is a page with a download button.
+            """),
+
+            TextFile(name: "TestBundle.md", utf8Content: """
+            # ``TestBundle``
+
+            This is a test.
+
+            ## Topics
+
+            ### Pages
+
+            - <doc:TechnologyX>
+            - <doc:MySample>
+            """),
+
+            // A symbol graph
+            CopyOfFile(original: Bundle.module.url(forResource: "TopLevelCuration.symbols", withExtension: "json", subdirectory: "Test Resources")!),
+
+            InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
+        ])
+
+        let testDataProvider = try TestFileSystem(folders: [bundle, Folder.emptyHTMLTemplateDirectory])
+        let targetDirectory = URL(fileURLWithPath: testDataProvider.currentDirectoryPath)
+            .appendingPathComponent("target", isDirectory: true)
+
+        var action = try ConvertAction(
+            documentationBundleURL: bundle.absoluteURL,
+            outOfProcessResolver: nil,
+            analyze: false,
+            targetDirectory: targetDirectory,
+            htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
+            emitDigest: true,
+            currentPlatforms: nil,
+            dataProvider: testDataProvider,
+            fileManager: testDataProvider,
+            temporaryDirectory: createTemporaryDirectory())
+        let result = try action.perform(logHandle: .standardOutput)
+
+        func contentsOfJSONFile<Result: Decodable>(url: URL) -> Result? {
+            guard let data = testDataProvider.contents(atPath: url.path) else {
+                return nil
+            }
+            return try? JSONDecoder().decode(Result.self, from: data)
+        }
+
+        // Verify downloads
+        guard let resultAssets: Digest.Assets = contentsOfJSONFile(url: result.outputs[0].appendingPathComponent("assets.json")) else {
+            XCTFail("Can't find assets.json in output")
+            return
+        }
+        XCTAssertEqual(resultAssets.downloads.count, 1)
+
+        XCTAssert(resultAssets.downloads.contains(where: {
+            $0.identifier.identifier == "project.zip"
+        }))
+
+        guard let externalAssets: Digest.ExternalAssets = contentsOfJSONFile(url: result.outputs[0].appendingPathComponent("external-assets.json")) else {
+            XCTFail("Can't find external-assets.json in output")
+            return
+        }
+        XCTAssertEqual(externalAssets.externalLocations.count, 1)
+
+        XCTAssert(externalAssets.externalLocations.contains(where: {
+            $0.identifier.identifier == "https://example.com/sample.zip"
+        }))
+    }
+
     func testMetadataIsWrittenToOutputFolder() throws {
         // Example documentation bundle that contains an image
         let bundle = Folder(name: "unit-test.docc", content: [