feat: treat jsdoc with @typescript-eslint/parser

Author: baseballyama

src/context/index.ts

@@ -18,13 +18,17 @@ import { LetDirectiveCollections } from "./let-directive-collection";
 import { parseAttributes } from "../parser/html";
 import { sortedLastIndex } from "../utils";
 import {
-  isTypeScript,
+  getLanguage,
   type NormalizedParserOptions,
 } from "../parser/parser-options";
 
 export class ScriptsSourceCode {
   private raw: string;
 
+  public getRaw(): string {
+    return this.raw;
+  }
+
   private trimmedRaw: string;
 
   public readonly attrs: Record<string, string | undefined>;
@@ -175,7 +179,7 @@ export class Context {
   public readonly snippets: SvelteSnippetBlock[] = [];
 
   // ----- States ------
-  private readonly state: { isTypeScript?: boolean } = {};
+  private readonly state: { language?: "js" | "ts" | "jsdoc" | string } = {};
 
   private readonly blocks: Block[] = [];
 
@@ -321,11 +325,17 @@ export class Context {
   }
 
   public isTypeScript(): boolean {
-    if (this.state.isTypeScript != null) {
-      return this.state.isTypeScript;
+    return this.getLanguage() === "ts";
+  }
+
+  public getLanguage(): "js" | "ts" | "jsdoc" | string {
+    if (this.state.language != null) {
+      return this.state.language;
     }
     const lang = this.sourceCode.scripts.attrs.lang;
-    return (this.state.isTypeScript = isTypeScript(this.parserOptions, lang));
+    const code = this.sourceCode.scripts.getRaw();
+    const language = getLanguage(this.parserOptions, lang, code);
+    return (this.state.language = language);
   }
 
   public stripScriptCode(start: number, end: number): void {

src/parser/index.ts

@@ -36,7 +36,7 @@ import {
 } from "./style-context";
 import { getGlobalsForSvelte, getGlobalsForSvelteScript } from "./globals";
 import type { NormalizedParserOptions } from "./parser-options";
-import { isTypeScript, normalizeParserOptions } from "./parser-options";
+import { getLanguage, normalizeParserOptions } from "./parser-options";
 import { getFragmentFromRoot } from "./compat";
 import {
   isEnableRunes,
@@ -140,18 +140,24 @@ function parseAsSvelte(
   );
 
   const scripts = ctx.sourceCode.scripts;
-  const resultScript = ctx.isTypeScript()
-    ? parseTypeScriptInSvelte(
-        scripts.getCurrentVirtualCodeInfo(),
-        scripts.attrs,
-        parserOptions,
-        { slots: ctx.slots, svelteParseContext },
-      )
-    : parseScriptInSvelte(
-        scripts.getCurrentVirtualCode(),
-        scripts.attrs,
-        parserOptions,
-      );
+  const language = ctx.getLanguage();
+
+  const resultScript =
+    language === "ts" || language === "jsdoc"
+      ? parseTypeScriptInSvelte(
+          scripts.getCurrentVirtualCodeInfo(),
+          {
+            ...scripts.attrs,
+            lang: language === "jsdoc" ? "ts" : scripts.attrs.lang,
+          },
+          parserOptions,
+          { slots: ctx.slots, svelteParseContext },
+        )
+      : parseScriptInSvelte(
+          scripts.getCurrentVirtualCode(),
+          scripts.attrs,
+          parserOptions,
+        );
   ctx.scriptLet.restore(resultScript);
   ctx.tokens.push(...resultScript.ast.tokens);
   ctx.comments.push(...resultScript.ast.comments);
@@ -249,10 +255,17 @@ function parseAsScript(
   parserOptions: NormalizedParserOptions,
   svelteParseContext: SvelteParseContext,
 ): ParseResult {
-  const lang = parserOptions.filePath?.split(".").pop();
-  const resultScript = isTypeScript(parserOptions, lang)
-    ? parseTypeScript(code, { lang }, parserOptions, svelteParseContext)
-    : parseScript(code, { lang }, parserOptions);
+  const rawLang = parserOptions.filePath?.split(".").pop();
+  const lang = getLanguage(parserOptions, rawLang, code);
+  const resultScript =
+    lang === "ts" || lang === "jsdoc"
+      ? parseTypeScript(
+          code,
+          { lang: lang === "jsdoc" ? "ts" : rawLang },
+          parserOptions,
+          svelteParseContext,
+        )
+      : parseScript(code, { lang: rawLang }, parserOptions);
 
   // Add $$xxx variable
   addGlobalVariables(

src/parser/parser-options.ts

@@ -63,35 +63,50 @@ const TS_PARSER_NAMES = [
   "typescript-eslint-parser-for-extra-files",
 ];
 
-export function isTypeScript(
+export function getLanguage(
   parserOptions: NormalizedParserOptions,
   lang: string | undefined,
-): boolean {
-  if (!lang) {
-    return false;
+  code: string | undefined,
+): "js" | "ts" | "jsdoc" | string {
+  const hasJsDoc = code ? jsdocTags.some((tag) => tag.test(code)) : false;
+  if (!lang && !hasJsDoc) {
+    return "js";
   }
-  const parserValue = getParserForLang(lang, parserOptions?.parser);
+
+  function getFinalLang(isTS: boolean): string {
+    if (isTS) {
+      if (lang) return lang;
+      return hasJsDoc ? "jsdoc" : "ts";
+    }
+    return lang || "js";
+  }
+
+  const parserValue = getParserForLang(
+    lang || (hasJsDoc ? "ts" : undefined),
+    parserOptions?.parser,
+  );
   if (typeof parserValue !== "string") {
-    return (
+    const isTS =
       maybeTSESLintParserObject(parserValue) ||
-      isTSESLintParserObject(parserValue)
-    );
+      isTSESLintParserObject(parserValue);
+    return getFinalLang(isTS);
   }
   const parserName = parserValue;
   if (TS_PARSER_NAMES.includes(parserName)) {
-    return true;
+    return getFinalLang(true);
   }
   if (TS_PARSER_NAMES.some((nm) => parserName.includes(nm))) {
     let targetPath = parserName;
     while (targetPath) {
       const pkgPath = path.join(targetPath, "package.json");
       if (fs.existsSync(pkgPath)) {
         try {
-          return TS_PARSER_NAMES.includes(
+          const isTS = TS_PARSER_NAMES.includes(
             JSON.parse(fs.readFileSync(pkgPath, "utf-8"))?.name,
           );
+          return getFinalLang(isTS);
         } catch {
-          return false;
+          return getFinalLang(false);
         }
       }
       const parent = path.dirname(targetPath);
@@ -102,5 +117,23 @@ export function isTypeScript(
     }
   }
 
-  return false;
+  return getFinalLang(false);
 }
+
+const jsdocTags = [
+  /@type\s/,
+  /@param\s/,
+  /@arg\s/,
+  /@argument\s/,
+  /@returns\s/,
+  /@return\s/,
+  /@typedef\s/,
+  /@callback\s/,
+  /@template\s/,
+  /@class\s/,
+  /@constructor\s/,
+  /@this\s/,
+  /@extends\s/,
+  /@augments\s/,
+  /@enum\s/,
+] as const;

tests/fixtures/integrations/parser-object-tests/ts-multiple-parser-setup.ts

@@ -8,7 +8,7 @@ export function getConfig(): Linter.Config {
   return {
     languageOptions: {
       parser,
-      parserOptions: generateParserOptions({ parser: { ts } }),
+      parserOptions: generateParserOptions({ parser: ts }),
       globals: {
         ...globals.browser,
         ...globals.es2021,

tests/fixtures/integrations/type-info-tests/jsdoc-input.svelte

@@ -0,0 +1,6 @@
+<script>
+  /** @param {number} x */
+  function test(x) {
+    return x + 1;
+  }
+</script>

tests/fixtures/integrations/type-info-tests/jsdoc-output.json

@@ -0,0 +1,9 @@
+[
+  {
+    "ruleId": "@typescript-eslint/no-unsafe-return",
+    "code": "return x + 1;",
+    "line": 4,
+    "column": 5,
+    "message": "Unsafe return of a value of type `any`."
+  }
+]

tests/fixtures/integrations/type-info-tests/jsdoc-setup.ts

@@ -0,0 +1,31 @@
+import type { Linter } from "eslint";
+import { generateParserOptions } from "../../../src/parser/test-utils";
+import { rules } from "@typescript-eslint/eslint-plugin";
+import * as ts from "@typescript-eslint/parser";
+import * as parser from "../../../../src";
+import globals from "globals";
+
+export function getConfig(): Linter.Config {
+  return {
+    plugins: {
+      "@typescript-eslint": {
+        rules: rules as any,
+      },
+    },
+    languageOptions: {
+      parser,
+      parserOptions: generateParserOptions({ parser: ts }),
+      globals: {
+        ...globals.browser,
+        ...globals.es2021,
+      },
+    },
+    rules: {
+      "@typescript-eslint/no-unsafe-argument": "error",
+      "@typescript-eslint/no-unsafe-assignment": "error",
+      "@typescript-eslint/no-unsafe-call": "error",
+      "@typescript-eslint/no-unsafe-member-access": "error",
+      "@typescript-eslint/no-unsafe-return": "error",
+    },
+  };
+}

tests/fixtures/parser/ast/jsdoc-input.svelte

@@ -0,0 +1,6 @@
+<script>
+  /** @param {number} x */
+  function test(x) {
+    return x + 1;
+  }
+</script>

tests/fixtures/parser/ast/jsdoc-no-unused-vars-result.json

@@ -0,0 +1,8 @@
+[
+  {
+    "ruleId": "no-unused-vars",
+    "code": "test",
+    "line": 3,
+    "column": 12
+  }
+]