Invalid declaration reference parsing should fail

Ref: #2360

CHANGELOG.md

@@ -16,6 +16,7 @@
 ### Bug Fixes
 
 -   Fixed link discovery if nested (`Foo#bar`) links were used and `--useTsLinkResolution` is enabled in some cases, #2360.
+-   Links with invalid declaration references will no longer silently link to the wrong page in some cases, #2360.
 -   Fixed duplicate definitions in type hierarchy when using packages mode, #2327.
 -   `@inheritDoc` was not properly resolved across packages in packages mode, #2331.
 -   Added warning for attempted `@interface` use on union types, #2352.

src/lib/converter/comments/declarationReference.ts

@@ -442,6 +442,8 @@ export function parseDeclarationReference(
         pos = ref[1];
     }
 
+    if (!moduleSource && !symbolReference) return;
+
     return [
         {
             moduleSource,

src/lib/validation/links.ts

@@ -29,8 +29,18 @@ export function validateLinks(
     for (const id in project.reflections) {
         const reflection = project.reflections[id];
         for (const broken of getBrokenLinks(reflection.comment)) {
+            // #2360, "@" is a future reserved character in TSDoc component paths
+            // If a link starts with it, and doesn't include a module source indicator "!"
+            // then the user probably is trying to link to a package containing "@" with an absolute link.
+            let extra = "";
+            if (broken.startsWith("@") && !broken.includes("!")) {
+                extra = `\n\tYou may have wanted "${broken.replace(
+                    /[.#~]/,
+                    "!",
+                )}"`;
+            }
             logger.warn(
-                `Failed to resolve link to "${broken}" in comment for ${reflection.getFriendlyFullName()}.`,
+                `Failed to resolve link to "${broken}" in comment for ${reflection.getFriendlyFullName()}.${extra}`,
             );
         }
     }

src/test/declarationReference.test.ts

@@ -211,12 +211,9 @@ describe("Declaration References", () => {
             });
         });
 
-        it("Doesn't crash with an empty reference", () => {
-            equal(parse(""), {
-                moduleSource: undefined,
-                resolutionStart: "local",
-                symbolReference: undefined,
-            });
+        it("Doesn't crash with an empty/invalid reference", () => {
+            equal(parse(""), undefined);
+            equal(parse("@test/foo"), undefined);
         });
     });
 });