chore: migrate @typedefjsdoc to @import (#729)

Co-authored-by: JounQin <[email protected]>

Author: yashtech00

.prettierrc

@@ -3,6 +3,7 @@
   "singleQuote": true,
   "plugins": [
     "@prettier/plugin-pug",
+    "prettier-plugin-jsdoc",
     "prettier-plugin-pkg",
     "prettier-plugin-svelte"
   ],

eslint-plugin-prettier.js

@@ -6,14 +6,25 @@
 // @ts-check
 
 /**
- * @typedef {import('eslint').AST.Range} Range
- * @typedef {import('eslint').AST.SourceLocation} SourceLocation
- * @typedef {import('eslint').ESLint.Plugin} Plugin
- * @typedef {import('eslint').ESLint.ObjectMetaProperties} ObjectMetaProperties
- * @typedef {import('prettier').FileInfoOptions} FileInfoOptions
- * @typedef {import('prettier').Options} PrettierOptions
- * @typedef {PrettierOptions & { onDiskFilepath: string, parserMeta?: ObjectMetaProperties['meta'], parserPath?: string, usePrettierrc?: boolean }} Options
- * @typedef {(source: string, options: Options, fileInfoOptions: FileInfoOptions) => string} PrettierFormat
+ * @import {AST, ESLint, Linter, Rule, SourceCode} from 'eslint'
+ * @import {FileInfoOptions, Options as PrettierOptions} from 'prettier'
+ * @import {Difference} from 'prettier-linter-helpers'
+ */
+
+/**
+ * @typedef {PrettierOptions & {
+ *   onDiskFilepath: string;
+ *   parserMeta?: ESLint.ObjectMetaProperties['meta'];
+ *   parserPath?: string;
+ *   usePrettierrc?: boolean;
+ * }} Options
+ *
+ *
+ * @typedef {(
+ *   source: string,
+ *   options: Options,
+ *   fileInfoOptions: FileInfoOptions,
+ * ) => string} PrettierFormat
  */
 
 'use strict';
@@ -39,9 +50,7 @@ const { INSERT, DELETE, REPLACE } = generateDifferences;
 // ------------------------------------------------------------------------------
 
 // Lazily-loaded Prettier.
-/**
- * @type {PrettierFormat}
- */
+/** @type {PrettierFormat} */
 let prettierFormat;
 
 // ------------------------------------------------------------------------------
@@ -51,13 +60,14 @@ let prettierFormat;
 /**
  * Reports a difference.
  *
- * @param {import('eslint').Rule.RuleContext} context - The ESLint rule context.
- * @param {import('prettier-linter-helpers').Difference} difference - The difference object.
+ * @param {Rule.RuleContext} context - The ESLint rule context.
+ * @param {Difference} difference - The difference object.
  * @returns {void}
  */
 function reportDifference(context, difference) {
   const { operation, offset, deleteText = '', insertText = '' } = difference;
-  const range = /** @type {Range} */ ([offset, offset + deleteText.length]);
+  /** @type {AST.Range} */
+  const range = [offset, offset + deleteText.length];
   // `context.getSourceCode()` was deprecated in ESLint v8.40.0 and replaced
   // with the `sourceCode` property.
   // TODO: Only use property when our eslint peerDependency is >=8.40.0.
@@ -80,9 +90,7 @@ function reportDifference(context, difference) {
 //  Module Definition
 // ------------------------------------------------------------------------------
 
-/**
- * @type {Plugin}
- */
+/** @type {ESLint.Plugin} */
 const eslintPluginPrettier = {
   meta: { name, version },
   configs: {
@@ -131,18 +139,17 @@ const eslintPluginPrettier = {
         },
       },
       create(context) {
-        const usePrettierrc =
-          !context.options[1] || context.options[1].usePrettierrc !== false;
-        /**
-         * @type {FileInfoOptions}
-         */
-        const fileInfoOptions =
-          (context.options[1] && context.options[1].fileInfoOptions) || {};
+        const options = /** @type {Options | undefined} */ (context.options[1]);
+        const usePrettierrc = !options || options.usePrettierrc !== false;
+        /** @type {FileInfoOptions} */
+        const fileInfoOptions = options?.fileInfoOptions || {};
 
         // `context.getSourceCode()` was deprecated in ESLint v8.40.0 and replaced
         // with the `sourceCode` property.
         // TODO: Only use property when our eslint peerDependency is >=8.40.0.
-        const sourceCode = context.sourceCode ?? context.getSourceCode();
+        const sourceCode = /** @type {SourceCode} */ (
+          context.sourceCode ?? context.getSourceCode()
+        );
         // `context.getFilename()` was deprecated in ESLint v8.40.0 and replaced
         // with the `filename` property.
         // TODO: Only use property when our eslint peerDependency is >=8.40.0.
@@ -169,12 +176,12 @@ const eslintPluginPrettier = {
               );
             }
 
-            /**
-             * @type {PrettierOptions}
-             */
+            /** @type {PrettierOptions} */
             const eslintPrettierOptions = context.options[0] || {};
 
-            const parser = context.languageOptions?.parser;
+            const parser = /** @type {Linter.Parser | undefined} */ (
+              context.languageOptions?.parser
+            );
 
             // prettier.format() may throw a SyntaxError if it cannot parse the
             // source code it is given. Usually for JS files this isn't a
@@ -184,9 +191,7 @@ const eslintPluginPrettier = {
             // files throw an error if they contain unclosed elements, such as
             // `<template><div></template>. In this case report an error at the
             // point at which parsing failed.
-            /**
-             * @type {string}
-             */
+            /** @type {string} */
             let prettierSource;
             try {
               prettierSource = prettierFormat(
@@ -213,10 +218,12 @@ const eslintPluginPrettier = {
 
               let message = 'Parsing error: ' + err.message;
 
-              const error =
-                /** @type {SyntaxError & {codeFrame: string; loc?: SourceLocation}} */ (
-                  err
-                );
+              const error = /**
+               * @type {SyntaxError & {
+               *   codeFrame: string;
+               *   loc?: AST.SourceLocation;
+               * }}
+               */ (err);
 
               // Prettier's message contains a codeframe style preview of the
               // invalid code and the line/column at which the error occurred.
@@ -243,7 +250,10 @@ const eslintPluginPrettier = {
               const differences = generateDifferences(source, prettierSource);
 
               for (const difference of differences) {
-                reportDifference(context, difference);
+                reportDifference(
+                  /** @type {Rule.RuleContext} */ (context),
+                  difference,
+                );
               }
             }
           },

package.json

@@ -92,6 +92,7 @@
     "lint-staged": "^15.5.0",
     "mocha": "^11.1.0",
     "prettier": "^3.5.3",
+    "prettier-plugin-jsdoc": "^1.3.2",
     "prettier-plugin-pkg": "^0.19.0",
     "prettier-plugin-svelte": "^3.3.3",
     "simple-git-hooks": "^2.12.1",

pnpm-lock.yaml

@@ -291,9 +291,7 @@ runFixture('*.mdx', [
   ],
 ]);
 
-/**
- * @see https://github.com/sveltejs/svelte/blob/226bf419f9b9b5f1a6da33bd6403dd70afe58b52/packages/svelte/package.json#L73
- */
+/** @see https://github.com/sveltejs/svelte/blob/226bf419f9b9b5f1a6da33bd6403dd70afe58b52/packages/svelte/package.json#L73 */
 const svelteUnsupported = +process.versions.node.split('.')[0] < 16;
 
 runFixture(
@@ -387,10 +385,10 @@ runFixture('invalid-prettierrc/*', [
 // ------------------------------------------------------------------------------
 
 /**
- * Reads a fixture file and returns an "invalid" case for use by RuleTester.
- * The fixture format aims to reduce the pain of debugging offsets by keeping
- * the lines and columns of the test code as close to what the rule will report
- * as possible.
+ * Reads a fixture file and returns an "invalid" case for use by RuleTester. The
+ * fixture format aims to reduce the pain of debugging offsets by keeping the
+ * lines and columns of the test code as close to what the rule will report as
+ * possible.
  *
  * @param {string} name - Fixture basename.
  * @returns {object} A {code, output, options, errors} test object.
@@ -421,7 +419,8 @@ function loadInvalidFixture(name) {
 }
 
 /**
- * Builds a dummy javascript file path to trick prettier into resolving a specific .prettierrc file.
+ * Builds a dummy javascript file path to trick prettier into resolving a
+ * specific .prettierrc file.
  *
  * @param {string} dir - Prettierrc fixture basename.
  * @param {string} file
@@ -433,14 +432,18 @@ function getPrettierRcJsFilename(dir, file = 'dummy.js') {
   );
 }
 
+/**
+ * @type {ESLint}
+ * @import {ESLint} from 'eslint'
+ */
 let eslint;
 
 /**
- *
  * @param {string} pattern
- * @param {import('eslint').Linter.LintMessage[][]} asserts
+ * @param {Linter.LintMessage[][]} asserts
  * @param {boolean} [skip]
  * @returns {Promise<void>}
+ * @import {Linter} from 'eslint'
  */
 async function runFixture(pattern, asserts, skip) {
   if (!eslint) {

test/prettier.mjs

@@ -1,15 +1,21 @@
 // @ts-check
 
 /**
- * @typedef {import('prettier').FileInfoOptions} FileInfoOptions
- * @typedef {import('eslint').ESLint.ObjectMetaProperties} ObjectMetaProperties
- * @typedef {import('prettier').Options & { onDiskFilepath: string, parserMeta?: ObjectMetaProperties['meta'], parserPath?: string, usePrettierrc?: boolean }} Options
+ * @typedef {PrettierOptions & {
+ *   onDiskFilepath: string;
+ *   parserMeta?: ESLint.ObjectMetaProperties['meta'];
+ *   parserPath?: string;
+ *   usePrettierrc?: boolean;
+ * }} Options
+ * @import {FileInfoOptions, Options as PrettierOptions} from 'prettier'
+ * @import {ESLint} from 'eslint'
  */
 
 const { runAsWorker } = require('synckit');
 
 /**
- * @type {typeof import('prettier')}
+ * @type {typeof Prettier}
+ * @import * as Prettier from 'prettier'
  */
 let prettier;
 
@@ -176,9 +182,7 @@ runAsWorker(
       }
     }
 
-    /**
-     * @type {import('prettier').Options}
-     */
+    /** @type {PrettierOptions} */
     const prettierOptions = {
       ...initialOptions,
       ...prettierRcOptions,