From 3a02414fb0bd1ad2e4f07827dc86d1de5d862592 Mon Sep 17 00:00:00 2001
From: Istvan Soos <istvan.soos@gmail.com>
Date: Fri, 18 Oct 2024 15:31:31 +0200
Subject: [PATCH] Prefer versions with documentation when selecting redirect
 target on /documentation/ URLs.

---
 app/lib/frontend/handlers/documentation.dart |  6 ++++-
 app/lib/task/backend.dart                    | 23 ++++++++++++++++++--
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/app/lib/frontend/handlers/documentation.dart b/app/lib/frontend/handlers/documentation.dart
index 67e8f70525..790bf7020d 100644
--- a/app/lib/frontend/handlers/documentation.dart
+++ b/app/lib/frontend/handlers/documentation.dart
@@ -167,7 +167,11 @@ Future<ResolvedDocUrlVersion> _resolveDocUrlVersion(
     }
 
     // Select the closest version (may be the same as version) that has a finished analysis.
-    final closest = await taskBackend.closestFinishedVersion(package, version);
+    final closest = await taskBackend.closestFinishedVersion(
+      package,
+      version,
+      preferDocsCompleted: true,
+    );
     return ResolvedDocUrlVersion(
       version: closest ?? version,
       urlSegment: closest ?? version,
diff --git a/app/lib/task/backend.dart b/app/lib/task/backend.dart
index fa3ff61329..a366672eca 100644
--- a/app/lib/task/backend.dart
+++ b/app/lib/task/backend.dart
@@ -1096,8 +1096,15 @@ class TaskBackend {
   /// If [version] or newer exists with finished analysis, it will be preferred, otherwise
   /// older versions may be considered too.
   ///
+  /// When [preferDocsCompleted] is set, a successfully completed but potentially older
+  /// version is preferred over a completed version without documentation.
+  ///
   /// Returns `null` if no such version exists.
-  Future<String?> closestFinishedVersion(String package, String version) async {
+  Future<String?> closestFinishedVersion(
+    String package,
+    String version, {
+    bool preferDocsCompleted = false,
+  }) async {
     final cachedValue =
         await cache.closestFinishedVersion(package, version).get(() async {
       final semanticVersion = Version.parse(version);
@@ -1108,7 +1115,19 @@ class TaskBackend {
         if (state == null || state.hasNeverFinished) {
           continue;
         }
-        final candidates = state.versions?.entries
+        List<Version>? candidates;
+        if (preferDocsCompleted) {
+          final finishedDocCandidates = state.versions?.entries
+              .where((e) => e.value.docs)
+              .map((e) => Version.parse(e.key))
+              .toList();
+          if (finishedDocCandidates != null &&
+              finishedDocCandidates.isNotEmpty) {
+            candidates = finishedDocCandidates;
+          }
+        }
+
+        candidates ??= state.versions?.entries
             .where((e) => e.value.finished)
             .map((e) => Version.parse(e.key))
             .toList();