fix: preserve imports used in JSDoc @link tags (#111)

Co-authored-by: Anthony Fu <[email protected]>

Author: jonasschultheiss

src/__test__/cases-js.ts

@@ -7,6 +7,48 @@ import { a, b } from "./utils";
 import y from "package";
 
 const c = a() + b + x() + y();
+`,
+        },
+        {
+            code: `
+import { NoAuthenticationGuard } from "./no-authentication.guard";
+import { JwtAuthenticationGuard } from "./jwt-authentication.guard";
+
+/**
+ * You can reference {@link NoAuthenticationGuard} instead.
+ * It's recommended to use the {@link JwtAuthenticationGuard}.
+ */
+const LOCAL_ENVIRONMENT_AUTHENTICATION_GUARD = JwtAuthenticationGuard;
+`,
+        },
+        {
+            code: `
+import { SomeClass } from "./some-class";
+
+/**
+ * @see SomeClass
+ */
+const example = "test";
+`,
+        },
+        {
+            code: `
+import { MyType } from "./types";
+
+/**
+ * @type {MyType}
+ */
+let value;
+`,
+        },
+        {
+            code: `
+import { Config } from "./config";
+
+/**
+ * @param {Config} config - The configuration object
+ */
+function setup(config) {}
 `,
         },
     ],
@@ -86,6 +128,26 @@ import y from "package";
  */
 const c = 4;
 console.log(y);
+`,
+        },
+        {
+            code: `
+import { UnusedClass } from "./unused";
+import { UsedInJSDoc } from "./used";
+
+/**
+ * Reference to {@link UsedInJSDoc}
+ */
+const example = "test";
+`,
+            errors: ["'UnusedClass' is defined but never used."],
+            output: `
+import { UsedInJSDoc } from "./used";
+
+/**
+ * Reference to {@link UsedInJSDoc}
+ */
+const example = "test";
 `,
         },
     ],

src/__test__/cases-ts.ts

@@ -8,6 +8,38 @@ import y from "package";
 import TType from "Package";
 
 const c: TType = a() + b + x() + y();
+`,
+        },
+        {
+            code: `
+import { NoAuthenticationGuard } from "./no-authentication.guard";
+import { JwtAuthenticationGuard } from "./jwt-authentication.guard";
+
+/**
+ * You can reference {@link NoAuthenticationGuard} instead.
+ * It's recommended to use the {@link JwtAuthenticationGuard}.
+ */
+const LOCAL_ENVIRONMENT_AUTHENTICATION_GUARD = JwtAuthenticationGuard;
+`,
+        },
+        {
+            code: `
+import type { SomeType } from "./types";
+
+/**
+ * @see SomeType for more details
+ */
+const example = "test";
+`,
+        },
+        {
+            code: `
+import type { Config } from "./config";
+
+/**
+ * @param {Config} config - The configuration object
+ */
+function setup(config: any) {}
 `,
         },
     ],
@@ -29,6 +61,26 @@ import { a, b } from "./utils";
 import y from "package";
 
 const c = a() + b + x() + y();
+`,
+        },
+        {
+            code: `
+import type { UnusedType } from "./unused";
+import type { UsedInJSDoc } from "./used";
+
+/**
+ * Reference to {@link UsedInJSDoc}
+ */
+const example = "test";
+`,
+            errors: ["'UnusedType' is defined but never used."],
+            output: `
+import type { UsedInJSDoc } from "./used";
+
+/**
+ * Reference to {@link UsedInJSDoc}
+ */
+const example = "test";
 `,
         },
     ],

src/rules/predicates.ts

@@ -8,17 +8,57 @@ export type Predicate = (
 const commaFilter = { filter: (token: AST.Token) => token.value === "," };
 const includeCommentsFilter = { includeComments: true };
 
+/**
+ * Check if an identifier is referenced in JSDoc comments
+ * Looks for JSDoc tags like @link, @see, @type, etc.
+ */
+function isUsedInJSDoc(identifierName: string, sourceCode: SourceCode): boolean {
+    const comments = sourceCode.getAllComments();
+
+    // JSDoc tags that can reference identifiers
+    // Pattern matches: {@link Name}, {@see Name}, @type {Name}, etc.
+    const jsdocPattern = new RegExp(
+        // {@link Name} or @see Name
+        `(?:@(?:link|linkcode|linkplain|see)\\s+${identifierName}\\b)|` + 
+        // {@link Name}
+        `(?:\\{@(?:link|linkcode|linkplain)\\s+${identifierName}\\b\\})|` + 
+        // @type {Name}, @param {Name}, etc.
+        `(?:[@{](?:type|typedef|param|returns?|template|augments|extends|implements)\\s+[^}]*\\b${identifierName}\\b)`, 
+    );
+
+    return comments.some((comment) => {
+        // Only check block comments (/* ... */) as JSDoc uses block comment syntax
+        if (comment.type !== "Block") {
+            return false;
+        }
+
+        return jsdocPattern.test(comment.value);
+    });
+}
+
 function makePredicate(
     isImport: boolean,
     addFixer?: (parent: any, sourceCode: SourceCode) => Partial<Rule.ReportDescriptor> | boolean,
 ): Predicate {
     return (problem, context) => {
         const sourceCode = context.sourceCode || context.getSourceCode();
 
-        const { parent } =
+        const node =
             (problem as any).node ??
             // typescript-eslint >= 7.8 sets a range instead of a node
             sourceCode.getNodeByRangeIndex(sourceCode.getIndexFromLoc((problem as any).loc.start));
+
+        const { parent } = node;
+
+        // Check if this is an import and if it's used in JSDoc comments
+        if (parent && /^Import(|Default|Namespace)Specifier$/.test(parent.type) && isImport) {
+            const identifierName = node.name;
+            if (identifierName && isUsedInJSDoc(identifierName, sourceCode)) {
+                // Don't report if used in JSDoc
+                return false;
+            }
+        }
+
         return parent
             ? /^Import(|Default|Namespace)Specifier$/.test(parent.type) == isImport
                 ? Object.assign(problem, addFixer?.(parent, sourceCode))