From a5305e3e6f3758c27396485f0546761eca8af8b0 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Sat, 27 Sep 2025 01:31:08 +0200
Subject: [PATCH] Added the "archiveReference" property to the PreparedURIPaths
 pseudo-type for the PrepareURIPathUseCase use case in the library target.

---
 .../Use Cases/PrepareURIPathUseCase.swift     | 28 +++++++++++--------
 .../PrepareURIPathUseCaseTests.swift          |  4 +--
 2 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift b/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift
index 493df4a..9611a9b 100644
--- a/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift	
+++ b/Sources/DocCMiddleware/Internal/Use Cases/PrepareURIPathUseCase.swift	
@@ -18,8 +18,8 @@ struct PrepareURIPathUseCase {
     
     // MARK: Type aliases
     
-    /// A pseudo-type that contains the archive name and URI path, plus the resource URI paths used for routing the documentation contents.
-    typealias PreparedURIPaths = (archiveName: String, archivePath: String, resourcePath: String)
+    /// A pseudo-type that contains the archive name, reference and URI path, plus the resource URI and relative paths used for routing the documentation contents.
+    typealias PreparedURIPaths = (archiveName: String, archiveReference: String, archivePath: String, resourcePath: String)
     
     // MARK: Properties
     
@@ -43,35 +43,41 @@ struct PrepareURIPathUseCase {
     ///
     /// The necessary data to extract from a given URI path is:
     /// 1. the `DocC` documentation archive name;
-    /// 2. the `DocC` documentation archive URI path;
-    /// 3. the `DocC` documentation resource URI path.
+    /// 2. the `DocC` documentation archive reference;
+    /// 3. the `DocC` documentation archive URI path;
+    /// 4. the `DocC` documentation resource URI path.
     ///
     /// > important: It is assumed that the `uriPath` parameter is a URI path that does not contain any percent encoded strings.
     ///
     /// - Parameter uriPath: A URI path to extract the data from.
-    /// - Returns: A pseudo-type that contains the archive' name and URI path, plus the resource URI paths.
+    /// - Returns: A pseudo-type that contains the archive' name, reference and URI path, plus the resource URI paths.
     func callAsFunction(_ uriPath: String) -> PreparedURIPaths? {
         guard let uriRest = restOfURIPath(from: uriPath) else {
             return nil
         }
         
-        let documentationName = uriRest
+        let archiveName = uriRest
             .split(separator: .Path.forwardSlash)
             .map(String.init)
             .first
 
-        let archiveName: String = if let documentationName {
-            documentationName.lowercased()
+        let archiveReference: String = if let archiveName {
+            archiveName.lowercased()
         } else {
             .empty
         }
-        let archivePath: String = if let documentationName {
-            .init(format: .Format.Path.archive, documentationName)
+        let archivePath: String = if let archiveName {
+            .init(format: .Format.Path.archive, archiveName)
         } else {
             .empty
         }
 
-        return (archiveName, archivePath, uriRest)
+        return (
+            archiveName ?? .empty,
+            archiveReference,
+            archivePath,
+            uriRest
+        )
     }
     
 }
diff --git a/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift b/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift
index 30b3b53..e73ffa6 100644
--- a/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift	
+++ b/Tests/DocCMiddleware/Tests/Internal/Use Cases/PrepareURIPathUseCaseTests.swift	
@@ -134,8 +134,8 @@ private extension Input {
 private extension Output {
     /// A list of expected outputs for the URI path samples, regardless their match against suffixed or not suffixed root URI paths.
     static let prepareURIPaths: [PrepareURIPathUseCase.PreparedURIPaths?] = [
-        ("somearchive", "/SomeArchive.doccarchive", "/SomeArchive/some/content/path"),
-        (.empty, .empty, .Path.forwardSlash),
+        ("SomeArchive", "somearchive", "/SomeArchive.doccarchive", "/SomeArchive/some/content/path"),
+        (.empty, .empty, .empty, .Path.forwardSlash),
         nil
     ]
 }