fix(no-undefined-types): treat variables imported by @import tags…

… as defined; fixes #1244
gajus · Jun 24, 2024 · 54ac4fd · 54ac4fd
1 parent ce066df
commit 54ac4fd
Show file tree

Hide file tree

Showing 6 changed files with 229 additions and 7 deletions.
diff --git a/.README/rules/no-undefined-types.md b/.README/rules/no-undefined-types.md
@@ -17,7 +17,7 @@ the tag types in the table below:
 `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`),
 `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`,
 `@template` (for "closure" or "typescript" `settings.jsdoc.mode` only),
-`@typedef`.
+`@import` (for TypeScript), `@typedef`.
 
 The following tags will also be checked but only when the mode is `closure`:
 

diff --git a/docs/rules/no-undefined-types.md b/docs/rules/no-undefined-types.md
@@ -23,7 +23,7 @@ the tag types in the table below:
 `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`),
 `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`,
 `@template` (for "closure" or "typescript" `settings.jsdoc.mode` only),
-`@typedef`.
+`@import` (for TypeScript), `@typedef`.
 
 The following tags will also be checked but only when the mode is `closure`:
 
@@ -307,6 +307,36 @@ const a = new Todo();
  */
 // Settings: {"jsdoc":{"structuredTags":{"namepathOrURLReferencer":{"name":"namepath-or-url-referencing"}}}}
 // Message: The type 'SomeType' is undefined.
+
+/**
+ * @import BadImportIgnoredByThisRule
+ */
+/**
+ * @import LinterDef, { Sth as Something, Another as Another2 } from "eslint"
+ */
+/**
+ * @import { Linter } from "eslint"
+ */
+/**
+ * @import LinterDefault from "eslint"
+ */
+/**
+ * @import {Linter as Lintee} from "eslint"
+ */
+/**
+ * @import * as Linters from "eslint"
+ */
+
+/**
+ * @type {BadImportIgnoredByThisRule}
+ */
+/**
+ * @type {Sth}
+ */
+/**
+ * @type {Another}
+ */
+// Message: The type 'BadImportIgnoredByThisRule' is undefined.
 ````
 
 
@@ -777,8 +807,45 @@ function quux(foo) {
 
 quux(0);
 
+/**
+ * @import BadImportIgnoredByThisRule
+ */
+/**
+ * @import LinterDef, { Sth as Something, Another as Another2 } from "eslint"
+ */
 /**
  * @import { Linter } from "eslint"
  */
+/**
+ * @import LinterDefault from "eslint"
+ */
+/**
+ * @import {Linter as Lintee} from "eslint"
+ */
+/**
+ * @import * as Linters from "eslint"
+ */
+
+/**
+ * @type {LinterDef}
+ */
+/**
+ * @type {Something}
+ */
+/**
+ * @type {Another2}
+ */
+/**
+ * @type {Linter}
+ */
+/**
+ * @type {LinterDefault}
+ */
+/**
+ * @type {Lintee}
+ */
+/**
+ * @type {Linters}
+ */
 ````
 
diff --git a/package.json b/package.json
@@ -11,6 +11,7 @@
     "debug": "^4.3.4",
     "escape-string-regexp": "^4.0.0",
     "esquery": "^1.5.0",
+    "parse-imports": "^2.0.0",
     "semver": "^7.6.2",
     "spdx-expression-parse": "^4.0.0"
   },

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/rules/noUndefinedTypes.js b/src/rules/noUndefinedTypes.js
@@ -1,12 +1,13 @@
-import iterateJsdoc, {
-  parseComment,
-} from '../iterateJsdoc.js';
+import { parseImportsSync } from 'parse-imports';
 import {
   getJSDocComment,
   parse as parseType,
   traverse,
   tryParse as tryParseType,
 } from '@es-joy/jsdoccomment';
+import iterateJsdoc, {
+  parseComment,
+} from '../iterateJsdoc.js';
 
 const extraTypes = [
   'null', 'undefined', 'void', 'string', 'boolean', 'object',
@@ -109,13 +110,15 @@ export default iterateJsdoc(({
       .filter(Boolean));
   }
 
-  const typedefDeclarations = sourceCode.getAllComments()
+  const comments = sourceCode.getAllComments()
     .filter((comment) => {
       return (/^\*\s/u).test(comment.value);
     })
     .map((commentNode) => {
       return parseComment(commentNode, '');
-    })
+    });
+
+  const typedefDeclarations = comments
     .flatMap((doc) => {
       return doc.tags.filter(({
         tag,
@@ -127,6 +130,51 @@ export default iterateJsdoc(({
       return tag.name;
     });
 
+
+  const importTags = settings.mode === 'typescript' ? /** @type {string[]} */ (comments.flatMap((doc) => {
+    return doc.tags.filter(({
+      tag,
+    }) => {
+      return tag === 'import';
+    });
+  }).flatMap((tag) => {
+    const {
+      type, name, description
+    } = tag;
+    const typePart = type ? `{${type}} `: '';
+    const imprt = 'import ' + (description
+      ? `${typePart}${name} ${description}`
+      : `${typePart}${name}`);
+
+    let imports;
+    try {
+      // Should technically await non-sync, but ESLint doesn't support async rules;
+      //  thankfully, the Wasm load time is safely fast
+      imports = parseImportsSync(imprt);
+    } catch (err) {
+      return null;
+    }
+
+    return [...imports].flatMap(({importClause}) => {
+      /* c8 ignore next */
+      const {default: dflt, named, namespace} = importClause || {};
+      const types = [];
+      if (dflt) {
+        types.push(dflt);
+      }
+      if (namespace) {
+        types.push(namespace);
+      }
+      if (named) {
+        for (const {binding} of named) {
+          types.push(binding);
+        }
+      }
+
+      return types;
+    });
+  }).filter(Boolean)) : [];
+
   const ancestorNodes = [];
 
   let currentNode = node;
@@ -193,6 +241,7 @@ export default iterateJsdoc(({
     )
     .concat(extraTypes)
     .concat(typedefDeclarations)
+    .concat(importTags)
     .concat(definedTypes)
     .concat(/** @type {string[]} */ (definedPreferredTypes))
     .concat(

diff --git a/test/rules/assertions/noUndefinedTypes.js b/test/rules/assertions/noUndefinedTypes.js
@@ -558,6 +558,52 @@ export default {
         },
       },
     },
+    {
+      code: `
+        /**
+         * @import BadImportIgnoredByThisRule
+         */
+        /**
+         * @import LinterDef, { Sth as Something, Another as Another2 } from "eslint"
+         */
+        /**
+         * @import { Linter } from "eslint"
+         */
+        /**
+         * @import LinterDefault from "eslint"
+         */
+        /**
+         * @import {Linter as Lintee} from "eslint"
+         */
+        /**
+         * @import * as Linters from "eslint"
+         */
+
+        /**
+         * @type {BadImportIgnoredByThisRule}
+         */
+        /**
+         * @type {Sth}
+         */
+        /**
+         * @type {Another}
+         */
+      `,
+      errors: [
+        {
+          line: 22,
+          message: 'The type \'BadImportIgnoredByThisRule\' is undefined.',
+        },
+        {
+          line: 25,
+          message: 'The type \'Sth\' is undefined.',
+        },
+        {
+          line: 28,
+          message: 'The type \'Another\' is undefined.',
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -1438,9 +1484,46 @@ export default {
     },
     {
       code: `
+        /**
+         * @import BadImportIgnoredByThisRule
+         */
+        /**
+         * @import LinterDef, { Sth as Something, Another as Another2 } from "eslint"
+         */
         /**
          * @import { Linter } from "eslint"
          */
+        /**
+         * @import LinterDefault from "eslint"
+         */
+        /**
+         * @import {Linter as Lintee} from "eslint"
+         */
+        /**
+         * @import * as Linters from "eslint"
+         */
+
+        /**
+         * @type {LinterDef}
+         */
+        /**
+         * @type {Something}
+         */
+        /**
+         * @type {Another2}
+         */
+        /**
+         * @type {Linter}
+         */
+        /**
+         * @type {LinterDefault}
+         */
+        /**
+         * @type {Lintee}
+         */
+        /**
+         * @type {Linters}
+         */
       `,
     },
   ],