Link to the “current” docs from the package page.

Author: daveverwer

Sources/App/Controllers/API/API+PackageController+GetRoute+Model.swift

@@ -45,7 +45,7 @@ extension API.PackageController.GetRoute {
         var isArchived: Bool
         var hasBinaryTargets: Bool
         var homepageUrl: String?
-        var documentationTarget: DocumentationTarget? = nil
+        var currentDocumentationTarget: DocumentationTarget? = nil
         var weightedKeywords: [WeightedKeyword]
         var releaseReferences: [App.Version.Kind: App.Reference]
         var fundingLinks: [FundingLink]
@@ -75,7 +75,7 @@ extension API.PackageController.GetRoute {
                       isArchived: Bool,
                       hasBinaryTargets: Bool = false,
                       homepageUrl: String? = nil,
-                      documentationTarget: DocumentationTarget? = nil,
+                      currentDocumentationTarget: DocumentationTarget? = nil,
                       weightedKeywords: [WeightedKeyword] = [],
                       defaultBranchReference: App.Reference,
                       releaseReference: App.Reference?,
@@ -109,7 +109,7 @@ extension API.PackageController.GetRoute {
             self.isArchived = isArchived
             self.hasBinaryTargets = hasBinaryTargets
             self.homepageUrl = homepageUrl
-            self.documentationTarget = documentationTarget
+            self.currentDocumentationTarget = currentDocumentationTarget
             self.weightedKeywords = weightedKeywords
             self.releaseReferences = {
                 var refs = [App.Version.Kind.defaultBranch: defaultBranchReference]
@@ -171,7 +171,7 @@ extension API.PackageController.GetRoute {
                 isArchived: repository.isArchived,
                 hasBinaryTargets: result.defaultBranchVersion.hasBinaryTargets,
                 homepageUrl: repository.homepageUrl,
-                documentationTarget: result.canonicalDocumentationTarget(),
+                currentDocumentationTarget: result.currentDocumentationTarget(),
                 weightedKeywords: weightedKeywords,
                 defaultBranchReference: result.defaultBranchVersion.reference,
                 releaseReference: result.releaseVersion?.reference,

Sources/App/Controllers/PackageController+PackageResult.swift

@@ -90,4 +90,16 @@ extension PackageController.PackageResult {
           preReleaseVersion?.model
         ].canonicalDocumentationTarget()
     }
+
+    func currentDocumentationTarget() -> DocumentationTarget? {
+        guard let target = canonicalDocumentationTarget()
+        else { return nil }
+
+        switch target {
+            case .external:
+                return target
+            case .internal(_, let archive):
+                return .internal(docVersion: .current(referencing: nil), archive: archive)
+        }
+    }
 }

Sources/App/Views/PackageController/PackageShow+View.swift

@@ -280,7 +280,7 @@ extension PackageShow {
                             )
                         )
                     },
-                    .unwrap(model.documentationTarget) { target in
+                    .unwrap(model.currentDocumentationTarget) { target in
                             .li(
                                 .a(
                                     .href(SiteURL.relativeURL(owner: model.repositoryOwner,

Tests/AppTests/API+PackageController+GetRoute+ModelTests.swift

@@ -89,7 +89,7 @@ class API_PackageController_GetRoute_ModelTests: SnapshotTestCase {
                                                                        swift6Readiness: nil))
 
         // validate
-        XCTAssertEqual(model.documentationTarget, .internal(docVersion: .reference("main"), archive: "archive1"))
+        XCTAssertEqual(model.currentDocumentationTarget, .internal(docVersion: .reference("main"), archive: "archive1"))
     }
 
     func test_init_external_documentation() async throws {
@@ -115,7 +115,7 @@ class API_PackageController_GetRoute_ModelTests: SnapshotTestCase {
                                                                        swift6Readiness: nil))
 
         // validate
-        XCTAssertEqual(model.documentationTarget, .external(url: "https://example.com/package/documentation"))
+        XCTAssertEqual(model.currentDocumentationTarget, .external(url: "https://example.com/package/documentation"))
     }
 
     func test_gitHubOwnerUrl() throws {

Tests/AppTests/PackageResultTests.swift

@@ -285,4 +285,88 @@ class PackageResultTests: AppTestCase {
             XCTAssertEqual(res.canonicalDocumentationTarget(), nil)
         }
     }
+
+    func test_currentDocumentationTarget() async throws {
+        do {
+            // Test package with branch docs and stable version docs
+            let pkg = try savePackage(on: app.db, "1".url)
+            try await Repository(package: pkg,
+                                 defaultBranch: "main",
+                                 forks: 42,
+                                 license: .mit,
+                                 name: "bar1",
+                                 owner: "foo",
+                                 stars: 17,
+                                 summary: "summary").save(on: app.db)
+            try await App.Version(package: pkg,
+                                  docArchives: [.init(name: "archive1", title: "Archive 1")],
+                                  latest: .defaultBranch,
+                                  reference: .branch("main")).save(on: app.db)
+            try await App.Version(package: pkg,
+                                  // Note the name change on the default branch. The current should point to this archive.
+                                  docArchives: [.init(name: "archive2", title: "Archive 2")],
+                                  latest: .release,
+                                  reference: .tag(1, 2, 3)).save(on: app.db)
+        }
+
+        do {
+            // Test package with only branch docs hosted externally.
+            let pkg = try savePackage(on: app.db, "2".url)
+            try await Repository(package: pkg,
+                                 defaultBranch: "main",
+                                 forks: 42,
+                                 license: .mit,
+                                 name: "bar2",
+                                 owner: "foo",
+                                 stars: 17,
+                                 summary: "summary").save(on: app.db)
+            try await App.Version(package: pkg,
+                                  latest: .defaultBranch,
+                                  reference: .branch("main"),
+                                  spiManifest: .init(externalLinks: .init(documentation: "https://example.com"))).save(on: app.db)
+        }
+
+        do {
+            // Test package with no documentation
+            let pkg = try savePackage(on: app.db, "3".url)
+            try await Repository(package: pkg,
+                                 defaultBranch: "main",
+                                 forks: 42,
+                                 license: .mit,
+                                 name: "bar3",
+                                 owner: "foo",
+                                 stars: 17,
+                                 summary: "summary").save(on: app.db)
+            try await App.Version(package: pkg,
+                                  latest: .defaultBranch,
+                                  reference: .branch("main")).save(on: app.db)
+        }
+
+        do {
+            // Testing for internally hosted documentation pointing at the "current".
+            let res = try await PackageController.PackageResult.query(on: app.db, owner: "foo", repository: "bar1")
+            let currentTarget = try XCTUnwrap(res.currentDocumentationTarget())
+
+            // Validaton
+            XCTAssertEqual(currentTarget, .internal(docVersion: .current(referencing: nil), archive: "archive2"))
+        }
+
+        do {
+            // Testing for `.external` case pass-through.
+            let res = try await PackageController.PackageResult.query(on: app.db, owner: "foo", repository: "bar2")
+            let currentTarget = try XCTUnwrap(res.currentDocumentationTarget())
+
+            // Validaton
+            XCTAssertEqual(currentTarget, .external(url: "https://example.com"))
+        }
+
+        do {
+            // Testing for "no documentation" pass-through.
+            let res = try await PackageController.PackageResult.query(on: app.db, owner: "foo", repository: "bar3")
+
+            // Validaton
+            XCTAssertNil(res.currentDocumentationTarget())
+        }
+    }
+
 }

Tests/AppTests/WebpageSnapshotTests.swift

@@ -176,7 +176,7 @@ class WebpageSnapshotTests: SnapshotTestCase {
 
     func test_PackageShowView_with_documentation_link() throws {
         var model = API.PackageController.GetRoute.Model.mock
-        model.documentationTarget = .internal(docVersion: .reference("main"), archive: "archive")
+        model.currentDocumentationTarget = .internal(docVersion: .reference("main"), archive: "archive")
         let page = { PackageShow.View(path: "", model: model, packageSchema: .mock).document() }
 
         assertSnapshot(of: page, as: .html)