externalSymbolLinkMappings now handles symbol IDs

Resolves #2725

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+### Bug Fixes
+
+-   `externalSymbolLinkMappings` now uses the TypeScript reported link target if available, #2725.
+
 ## v0.26.8 (2024-10-04)
 
 ### Features

src/lib/converter/converter.ts

@@ -229,7 +229,21 @@ export class Converter extends ChildableComponent<
     constructor(owner: Application) {
         super(owner);
 
-        this.addUnknownSymbolResolver((ref) => {
+        const userConfiguredSymbolResolver: ExternalSymbolResolver = (
+            ref,
+            refl,
+            _part,
+            symbolId,
+        ) => {
+            if (symbolId) {
+                return userConfiguredSymbolResolver(
+                    symbolId.toDeclarationReference(),
+                    refl,
+                    undefined,
+                    undefined,
+                );
+            }
+
             // Require global links, matching local ones will likely hide mistakes where the
             // user meant to link to a local type.
             if (ref.resolutionStart !== "global" || !ref.symbolReference) {
@@ -256,7 +270,9 @@ export class Converter extends ChildableComponent<
             if (typeof modLinks["*"] === "string") {
                 return modLinks["*"];
             }
-        });
+        };
+
+        this.addUnknownSymbolResolver(userConfiguredSymbolResolver);
     }
 
     /**

src/test/converter2/issues/gh2725.ts

@@ -0,0 +1,6 @@
+import { Node } from "typescript";
+
+/**
+ * {@link Node}
+ */
+export const node = true;

src/test/issues.c2.test.ts

@@ -1786,4 +1786,16 @@ describe("Issue Tests", () => {
         equal(query(project, "big").defaultValue, "123n");
         equal(query(project, "neg").defaultValue, "-123n");
     });
+
+    it("#2725 respects symbol IDs when resolving links with user configured resolver", () => {
+        app.options.setValue("externalSymbolLinkMappings", {
+            typescript: {
+                "ts.Node": "https://typescriptlang.org",
+            },
+        });
+        const project = convert();
+        equal(getLinks(query(project, "node")), [
+            { display: "Node", target: "https://typescriptlang.org" },
+        ]);
+    });
 });