make CallToAction url arguments encode verbatim in Render JSON (#467)

rdar://104558809

Author: QuietMisdreavus

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

@@ -0,0 +1,54 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+/// A specialized ``DownloadReference`` used for references to external links.
+///
+/// `@CallToAction` directives can link either to a local file or to a URL, whether relative or
+/// absolute. Directives that use the `file` argument will create a ``DownloadReference`` and copy
+/// the file from the catalog into the resulting archive.
+///
+/// An `ExternalLocationReference` is intended to encode to Render JSON compatible with a
+/// ``DownloadReference``, but with the `url` set to the text given in the `@CallToAction`'s `url`
+/// argument.
+public struct ExternalLocationReference: RenderReference, URLReference {
+    public static var baseURL: URL = DownloadReference.baseURL
+
+    public private(set) var type: RenderReferenceType = .download
+
+    public var identifier: RenderReferenceIdentifier
+
+    enum CodingKeys: String, CodingKey {
+        case type
+        case identifier
+        case url
+    }
+
+    public init(identifier: RenderReferenceIdentifier) {
+        self.identifier = identifier
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        self.identifier = try container.decode(RenderReferenceIdentifier.self, forKey: .identifier)
+        self.type = try container.decode(RenderReferenceType.self, forKey: .type)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(type.rawValue, forKey: .type)
+        try container.encode(identifier, forKey: .identifier)
+
+        // Enter the given URL verbatim into the Render JSON
+        try container.encode(identifier.identifier, forKey: .url)
+    }
+}

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -789,11 +789,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
                         isActive: true,
                         overridingTitle: callToAction.buttonLabel,
                         overridingTitleInlineContent: nil))
-                downloadReferences[url.description] = DownloadReference(
-                    identifier: downloadIdentifier,
-                    renderURL: url,
-                    checksum: nil
-                )
+                externalLocationReferences[url.description] = ExternalLocationReference(identifier: downloadIdentifier)
             } else if let fileReference = callToAction.file {
                 let downloadIdentifier = createAndRegisterRenderReference(forMedia: fileReference, assetContext: .download)
                 node.sampleDownload = .init(action: .reference(
@@ -830,6 +826,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
         addReferences(videoReferences, to: &node)
         addReferences(linkReferences, to: &node)
         addReferences(downloadReferences, to: &node)
+        addReferences(externalLocationReferences, to: &node)
         // See Also can contain external links, we need to separately transfer
         // link references from the content compiler
         addReferences(contentCompiler.linkReferences, to: &node)
@@ -1626,6 +1623,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
     var linkReferences: [String: LinkReference] = [:]
     var requirementReferences: [String: XcodeRequirementReference] = [:]
     var downloadReferences: [String: DownloadReference] = [:]
+    var externalLocationReferences: [String: ExternalLocationReference] = [:]
 
     private var bundleAvailability: [BundleModuleIdentifier: [AvailabilityRenderItem]] = [:]
 

Tests/SwiftDocCTests/Rendering/SampleDownloadTests.swift

@@ -161,5 +161,103 @@ class SampleDownloadTests: XCTestCase {
 
         XCTAssertEqual(origIdent, decodedIdent)
     }
-    
+
+    func testSampleDownloadRelativeURL() throws {
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/SampleBundle/RelativeURLSample",
+            sourceLanguage: .swift
+        )
+        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+        let sampleCodeDownload = try XCTUnwrap(renderNode.sampleDownload)
+        guard case .reference(identifier: let ident, isActive: true, overridingTitle: "Download", overridingTitleInlineContent: nil) = sampleCodeDownload.action else {
+            XCTFail("Unexpected action in callToAction")
+            return
+        }
+        XCTAssertEqual(ident.identifier, "files/ExternalSample.zip")
+
+        // Ensure that the encoded URL still references the entered URL
+        let downloadReference = try XCTUnwrap(renderNode.references[ident.identifier] as? ExternalLocationReference)
+
+        let encoder = JSONEncoder()
+        let decoder = JSONDecoder()
+
+        let encodedReference = try encoder.encode(downloadReference)
+        let decodedReference = try decoder.decode(DownloadReference.self, from: encodedReference)
+
+        XCTAssertEqual(decodedReference.url.description, "files/ExternalSample.zip")
+    }
+
+    func testExternalLocationRoundtrip() throws {
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/SampleBundle/RelativeURLSample",
+            sourceLanguage: .swift
+        )
+        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+        let sampleCodeDownload = try XCTUnwrap(renderNode.sampleDownload)
+        guard case .reference(identifier: let ident, isActive: true, overridingTitle: "Download", overridingTitleInlineContent: nil) = sampleCodeDownload.action else {
+            XCTFail("Unexpected action in callToAction")
+            return
+        }
+        XCTAssertEqual(ident.identifier, "files/ExternalSample.zip")
+
+        // Make sure that the ExternalLocationReference we get can round-trip as itself as well as through a DownloadReference
+        let downloadReference = try XCTUnwrap(renderNode.references[ident.identifier] as? ExternalLocationReference)
+
+        let encoder = JSONEncoder()
+        encoder.outputFormatting.insert(.sortedKeys)
+        let decoder = JSONDecoder()
+
+        let encodedReference = try encoder.encode(downloadReference)
+
+        // ExternalLocationReference -> ExternalLocationReference
+        // The encoded JSON should be the same before and after re-encoding.
+        do {
+            let decodedReference = try decoder.decode(ExternalLocationReference.self, from: encodedReference)
+            let reEncodedReference = try encoder.encode(decodedReference)
+
+            let firstJson = String(data: encodedReference, encoding: .utf8)
+            let finalJson = String(data: reEncodedReference, encoding: .utf8)
+
+            XCTAssertEqual(firstJson, finalJson)
+        }
+
+        // ExternalLocationReference -> DownloadReference -> ExternalLocationReference
+        // The reference identifier should be the same all throughout, and the final ExternalLocationReference
+        // should encode to the same JSON as the initial reference.
+        do {
+            let decodedReference = try decoder.decode(DownloadReference.self, from: encodedReference)
+
+            XCTAssertEqual(decodedReference.identifier, downloadReference.identifier)
+
+            let encodedDownload = try encoder.encode(decodedReference)
+            let reDecodedReference = try decoder.decode(ExternalLocationReference.self, from: encodedDownload)
+
+            XCTAssertEqual(reDecodedReference.identifier, downloadReference.identifier)
+
+            let reEncodedReference = try encoder.encode(reDecodedReference)
+
+            let firstJson = String(data: encodedReference, encoding: .utf8)
+            let finalJson = String(data: reEncodedReference, encoding: .utf8)
+
+            XCTAssertEqual(firstJson, finalJson)
+        }
+    }
 }

Tests/SwiftDocCTests/Test Bundles/SampleBundle.docc/RelativeURLSample.md

@@ -0,0 +1,9 @@
+# Relative URL Sample
+
+@Metadata {
+    @CallToAction(url: "files/ExternalSample.zip", purpose: download)
+}
+
+This sample references a file on the web server.
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/SampleBundle.docc/SomeSample.md

@@ -12,5 +12,6 @@ This is a great framework, I tell you what.
 
 - <doc:MySample>
 - <doc:MyLocalSample>
+- <doc:RelativeURLSample>
 
-<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2022-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->