Fix TS link resolution in first comment of file

Resolves #2994

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,10 @@ title: Changelog
 
 ## Unreleased
 
+### Bug Fixes
+
+- Fixed link resolution not working correctly in first comment on the file in some cases, #2994.
+
 ## v0.28.10 (2025-08-10)
 
 ### Bug Fixes

src/lib/converter/comments/discovery.ts

@@ -357,15 +357,11 @@ function findJsDocForComment(
     if (ranges[0].kind === ts.SyntaxKind.MultiLineCommentTrivia) {
         const jsDocs = ts
             .getJSDocCommentsAndTags(node)
-            .map((doc) => ts.findAncestor(doc, ts.isJSDoc)) as ts.JSDoc[];
+            .map((doc) => ts.findAncestor(doc, ts.isJSDoc)!);
 
         if (ts.isSourceFile(node)) {
             if (node.statements.length) {
-                jsDocs.push(
-                    ...(ts
-                        .getJSDocCommentsAndTags(node.statements[0])
-                        .map((doc) => ts.findAncestor(doc, ts.isJSDoc)) as ts.JSDoc[]),
-                );
+                jsDocs.push(...node.statements[0].getChildren().filter(ts.isJSDoc));
             }
         }
 

src/lib/types/ts-internal/index.d.ts

@@ -23,22 +23,8 @@ declare module "typescript" {
     // https://github.com/microsoft/TypeScript/blob/v5.0.2/src/compiler/utilities.ts#L7432
     export function getCheckFlags(symbol: ts.Symbol): CheckFlags;
 
-    // https://github.com/microsoft/TypeScript/blob/v5.0.2/src/compiler/utilities.ts#L4171
-    export function getJSDocCommentsAndTags(
-        hostNode: Node,
-        noCache?: boolean,
-    ): readonly (JSDoc | JSDocTag)[];
-
-    export function getInterfaceBaseTypeNodes(
-        node: InterfaceDeclaration,
-    ): NodeArray<ExpressionWithTypeArguments> | undefined;
-
     export function getAllSuperTypeNodes(node: ts.Node): readonly ts.TypeNode[];
 
-    export interface Signature {
-        thisParameter?: ts.Symbol;
-    }
-
     // https://github.com/microsoft/TypeScript/blob/e213b2af3430bdc9cf5fbc76a8634d832e7aaaaa/src/compiler/types.ts#L5298-L5299
     export interface UnionType {
         /* @internal */

src/test/converter2/issues/gh2994.d.ts

@@ -0,0 +1,13 @@
+/**
+ * {@link x} <-- should be resolved with TS resolution
+ * @packageDocumentation
+ */
+
+/** Required comment */
+import { x } from "gh2994";
+
+export var y: 2;
+
+declare module "gh2994" {
+    var x: 1;
+}

src/test/issues.c2.test.ts

@@ -17,7 +17,7 @@ import type { InlineTagDisplayPart } from "../lib/models/Comment.js";
 import { getConverter2App, getConverter2Project } from "./programs.js";
 import { TestLogger } from "./TestLogger.js";
 import { equalKind, getComment, getLinks, getSigComment, query, querySig, reflToTree } from "./utils.js";
-import { DefaultTheme, KindRouter, PageEvent } from "../index.js";
+import { DefaultTheme, KindRouter, PageEvent, ReflectionSymbolId } from "../index.js";
 
 const app = getConverter2App();
 
@@ -2144,4 +2144,10 @@ describe("Issue Tests", () => {
         equal(x.inheritedFrom?.reflection?.getFullName(), undefined);
         equal(x.inheritedFrom?.name, "Tricky.x");
     });
+
+    it("#2994 uses TS link resolution in first comment of file", () => {
+        const project = convert();
+        const link = project.comment?.summary.find(part => part.kind === "inline-tag");
+        ok(link?.target instanceof ReflectionSymbolId);
+    });
 });