Improve link resolution prioritization

Ref: Gerrit0/typedoc-plugin-zod#8

Author: Gerrit0

CHANGELOG.md

@@ -8,6 +8,8 @@ title: Changelog
 
 -   `@include` and `@includeCode` now work in the readme file, #2814.
 -   TypeDoc will now avoid making references to references, #2811.
+-   Improved link resolution logic to prioritize type alias properties with the
+    same symbol over type literal properties within function parameters.
 
 ## v0.27.5 (2024-12-14)
 

src/lib/converter/comments/linkResolver.ts

@@ -13,6 +13,7 @@ import {
     parseDeclarationReference,
 } from "./declarationReference.js";
 import { resolveDeclarationReference } from "./declarationReferenceResolver.js";
+import { maxElementByScore } from "../../utils/array.js";
 
 const urlPrefix = /^(http|ftp)s?:\/\//;
 
@@ -138,14 +139,32 @@ function resolveLinkTag(
 
         if (tsTargets.length) {
             // Find the target most likely to have a real url in the generated documentation
-            target =
-                tsTargets.find((r) => r.kindOf(ReflectionKind.SomeExport)) ||
-                tsTargets.find(
-                    (r) =>
-                        r.kindOf(ReflectionKind.SomeMember) &&
-                        r.parent?.kindOf(ReflectionKind.SomeExport),
-                ) ||
-                tsTargets[0];
+            // 1. A direct export (class, interface, variable)
+            // 2. A property of a direct export (class/interface property)
+            // 3. A property of a type of an export (property on type alias)
+            // 4. Whatever the first symbol found was
+            target = maxElementByScore(tsTargets, (r) => {
+                if (r.kindOf(ReflectionKind.SomeExport)) {
+                    return 4;
+                }
+                if (
+                    r.kindOf(ReflectionKind.SomeMember) &&
+                    r.parent?.kindOf(ReflectionKind.SomeExport)
+                ) {
+                    return 3;
+                }
+                if (
+                    r.kindOf(ReflectionKind.SomeMember) &&
+                    r.parent?.kindOf(ReflectionKind.TypeLiteral) &&
+                    r.parent.parent?.kindOf(
+                        ReflectionKind.TypeAlias | ReflectionKind.Variable,
+                    )
+                ) {
+                    return 2;
+                }
+
+                return 1;
+            })!;
             pos = end;
             defaultDisplayText =
                 part.tsLinkText ||

src/lib/utils/array.ts

@@ -196,3 +196,25 @@ export function joinArray<T>(
     }
     return "";
 }
+
+export function maxElementByScore<T>(
+    arr: readonly T[],
+    score: (a: T) => number,
+): T | undefined {
+    if (arr.length === 0) {
+        return undefined;
+    }
+
+    let largest = arr[0];
+    let largestScore = score(arr[0]);
+
+    for (let i = 1; i < arr.length; ++i) {
+        const itemScore = score(arr[i]);
+        if (itemScore > largestScore) {
+            largest = arr[i];
+            largestScore = itemScore;
+        }
+    }
+
+    return largest;
+}

src/test/converter/exports/specs.json

@@ -308,7 +308,7 @@
               "url": "typedoc://mod.ts#L13"
             }
           ],
-          "target": 31
+          "target": 30
         },
         {
           "id": 40,
@@ -412,7 +412,7 @@
               "url": "typedoc://mod.ts#L40"
             }
           ],
-          "target": 34
+          "target": 29
         }
       ],
       "groups": [

src/test/converter/exports/specs.nodoc.json

@@ -34,7 +34,7 @@
               "url": "typedoc://mod.ts#L13"
             }
           ],
-          "target": 31
+          "target": 30
         },
         {
           "id": 43,

src/test/utils/array.test.ts

@@ -3,6 +3,7 @@ import {
     binaryFindPartition,
     insertOrderSorted,
     insertPrioritySorted,
+    maxElementByScore,
     removeIfPresent,
 } from "../../lib/utils/array.js";
 
@@ -138,4 +139,24 @@ describe("Array utils", () => {
             equal(arr, [2, 1]);
         });
     });
+
+    describe("maxElementByScore", () => {
+        it("Gets the max element", () => {
+            const arr = [1, 2, 3];
+            const item = maxElementByScore(arr, (x) => x);
+            equal(item, 3);
+        });
+
+        it("Prioritizes elements earlier in the array", () => {
+            const arr = [1, 2, 3];
+            const item = maxElementByScore(arr, () => 1);
+            equal(item, 1);
+        });
+
+        it("Returns undefined for an empty array", () => {
+            const arr: unknown[] = [];
+            const item = maxElementByScore(arr, () => 1);
+            equal(item, undefined);
+        });
+    });
 });