Allow relative references to images across bundle identifiers (#1178)

Fixes an issue where roundtripping a `URLReference` would yield different results depending on the bundle identifier of the catalog.

Paths to images and other downloadable content would always get rendered into JSON with the bundle identifier of the current bundle, discarding the original path, regardless of whether they already contained a reference to a different bundle.

This causes issues when the resolved information from an out of process resolver contains a relative path, e.g. `/images/com.example.bundle/image.png`, as the path would always be rewritten to be the catalog's bundle identifier.

This fix makes it such that if the path is already relative to the base URL of the reference type, the URL is left unchanged.

Fixes rdar://146108301.

Author: anferbui

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

@@ -74,7 +74,7 @@ public struct ImageReference: MediaReference, URLReference, Equatable {
         var result = [VariantProxy]()
         // sort assets by URL path for deterministic sorting of images
         asset.variants.sorted(by: \.value.path).forEach { (key, value) in
-            let url = value.isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent, prefixComponent: encoder.assetPrefixComponent)
+            let url = renderURL(for: value, prefixComponent: encoder.assetPrefixComponent)
             result.append(VariantProxy(url: url, traits: key, svgID: asset.metadata[value]?.svgID))
         }
         try container.encode(result, forKey: .variants)

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

@@ -65,6 +65,27 @@ public protocol URLReference {
 }
 
 extension URLReference {
+    /// Transforms the given URL to ensure that it is relative to the base URL of the conforming type.
+    ///
+    /// The converter that writes the built documentation to the file system is responsible for copying the referenced file to this destination.
+    /// - Parameters:
+    ///   - url: The URL of the file.
+    ///   - prefixComponent: An optional path component to add before the path of the file.
+    /// - Returns: The transformed URL for the given file path.
+    func renderURL(for url: URL, prefixComponent: String?) -> URL {
+        // Web URLs should be left as-is
+        guard !url.isAbsoluteWebURL else {
+            return url
+        }
+        
+        // URLs which are already relative to the base URL should be left as-is
+        guard !url.pathComponents.starts(with: Self.baseURL.pathComponents) else {
+            return url
+        }
+
+        return destinationURL(for: url.lastPathComponent, prefixComponent: prefixComponent)
+    }
+    
     /// Returns the URL for a given file path relative to the base URL of the conforming type.
     ///
     /// The converter that writes the built documentation to the file system is responsible for copying the referenced file to this destination.

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

@@ -81,7 +81,7 @@ public struct VideoReference: MediaReference, URLReference, Equatable {
         // convert the data asset to a serializable object
         var result = [VariantProxy]()
         asset.variants.sorted(by: \.value.path).forEach { (key, value) in
-            let url = value.isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent, prefixComponent: encoder.assetPrefixComponent)
+            let url = renderURL(for: value, prefixComponent: encoder.assetPrefixComponent)
             result.append(VariantProxy(url: url, traits: key))
         }
         try container.encode(result, forKey: .variants)

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

@@ -93,12 +93,6 @@ public struct DownloadReference: RenderReference, URLReference, Equatable {
     }
 }
 
-extension DownloadReference {
-    private func renderURL(for url: URL, prefixComponent: String?) -> URL {
-        url.isAbsoluteWebURL ? url : destinationURL(for: url.lastPathComponent, prefixComponent: prefixComponent)
-    }
-}
-
 // Diffable conformance
 extension DownloadReference: RenderJSONDiffable {
     /// Returns the difference between this DownloadReference and the given one.

Tests/SwiftDocCTests/Rendering/URLReferenceTests.swift

@@ -0,0 +1,91 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import XCTest
+@testable import SwiftDocC
+
+class URLReferenceTests: XCTestCase {
+    struct MockReference: URLReference {
+        static var baseURL: URL = URL(string: "/mocks/")!
+    }
+    func testRenderURLIgnoresAbsoluteWebURLs() throws {
+        let testUrl = try XCTUnwrap(URL(string: "https://example.com/"))
+        let urlReference = MockReference()
+        XCTAssertEqual(urlReference.renderURL(for: testUrl, prefixComponent: nil), testUrl)
+    }
+    
+    func testRenderURLIgnoresPrefacedURLs() throws {
+        let testUrl = try XCTUnwrap(URL(string: "/mocks/example.com/mock-name"))
+        let urlReference = MockReference()
+        XCTAssertEqual(urlReference.renderURL(for: testUrl, prefixComponent: nil), testUrl)
+    }
+    
+    func testRenderURLPreparesUnprefacedURLs() throws {
+        let testUrl = try XCTUnwrap(URL(string: "file://full/path/to/mock-name"))
+        let expectedUrl = try XCTUnwrap(URL(string: "/mocks/mock-name"))
+        let urlReference = MockReference()
+        XCTAssertEqual(urlReference.renderURL(for: testUrl, prefixComponent: nil), expectedUrl)
+    }
+    
+    func testImageReferenceRoundtripsAcrossBundles() throws {
+        // Encode the reference in bundle 1
+        var encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle1")
+        var asset = DataAsset()
+        asset.register(URL(string: "image.png")!, with: .init())
+        let reference = ImageReference(identifier: .init("image"), imageAsset: asset)
+        
+        // Verify it was encoded correctly
+        var jsonData = try XCTUnwrap(try encoder.encode(reference))
+        var decodedReference = try RenderJSONDecoder.makeDecoder().decode(ImageReference.self, from: jsonData)
+        XCTAssertEqual(Array(decodedReference.asset.metadata.keys), [URL(string: "/images/com.example.bundle1/image.png")!])
+        
+        // Re-encode the reference from bundle 1 in bundle 2 and ensure that the URL has not changed
+        encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle2")
+        jsonData = try XCTUnwrap(try encoder.encode(decodedReference))
+        decodedReference = try RenderJSONDecoder.makeDecoder().decode(ImageReference.self, from: jsonData)
+        XCTAssertEqual(Array(decodedReference.asset.metadata.keys), [URL(string: "/images/com.example.bundle1/image.png")!])
+    }
+    
+    func testDownloadReferenceRoundtripsAcrossBundles() throws {
+        // Encode the reference in bundle 1
+        var encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle1")
+        let reference = DownloadReference(identifier: .init("download"), renderURL: URL(string: "download.zip")!, checksum: nil)
+        
+        // Verify it was encoded correctly
+        var jsonData = try XCTUnwrap(try encoder.encode(reference))
+        var decodedReference = try RenderJSONDecoder.makeDecoder().decode(DownloadReference.self, from: jsonData)
+        XCTAssertEqual(decodedReference.url, URL(string: "/downloads/com.example.bundle1/download.zip")!)
+        
+        // Re-encode the reference from bundle 1 in bundle 2 and ensure that the URL has not changed
+        encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle2")
+        jsonData = try XCTUnwrap(try encoder.encode(decodedReference))
+        decodedReference = try RenderJSONDecoder.makeDecoder().decode(DownloadReference.self, from: jsonData)
+        XCTAssertEqual(decodedReference.url, URL(string: "/downloads/com.example.bundle1/download.zip")!)
+    }
+    
+    func testVideoReferenceRoundtripsAcrossBundles() throws {
+        // Encode the reference in bundle 1
+        var encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle1")
+        var asset = DataAsset()
+        asset.register(URL(string: "video.mov")!, with: .init())
+        let reference = VideoReference(identifier: .init("video"), videoAsset: asset, poster: nil)
+        
+        // Verify it was encoded correctly
+        var jsonData = try XCTUnwrap(try encoder.encode(reference))
+        var decodedReference = try RenderJSONDecoder.makeDecoder().decode(VideoReference.self, from: jsonData)
+        XCTAssertEqual(Array(decodedReference.asset.metadata.keys), [URL(string: "/videos/com.example.bundle1/video.mov")!])
+
+        // Re-encode the reference from bundle 1 in bundle 2 and ensure that the URL has not changed
+        encoder = RenderJSONEncoder.makeEncoder(assetPrefixComponent: "com.example.bundle2")
+        jsonData = try XCTUnwrap(try encoder.encode(decodedReference))
+        decodedReference = try RenderJSONDecoder.makeDecoder().decode(VideoReference.self, from: jsonData)
+        XCTAssertEqual(Array(decodedReference.asset.metadata.keys), [URL(string: "/videos/com.example.bundle1/video.mov")!])
+    }
+}