eslint-plugin-jsdoc 60.1.1 → 60.3.0

package/dist/rules/preferImportTag.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"preferImportTag.cjs","names":["_iterateJsdoc","_interopRequireWildcard","require","_jsdoccomment","_parseImportsExports","e","t","WeakMap","r","n","__esModule","o","i","f","__proto__","default","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","_default","exports","iterateJsdoc","context","jsdoc","settings","sourceCode","utils","mode","enableFixer","exemptTypedefs","outputType","options","allComments","getAllComments","comments","filter","comment","test","value","map","commentNode","commentParserToESTree","parseComment","typedefs","flatMap","doc","tags","tag","isNamepathDefiningTag","imports","delimiter","iterateInlineImports","potentialType","type","parsedType","tryParseType","parseType","traverse","nde","parentNode","element","currentNode","pathSegments","nodes","extraPathSegments","quotes","propertyOrBrackets","unshift","right","pathType","meta","quote","getFixer","matchingName","extrPathSegments","node","at","keys","key","length","newNode","shift","left","nameNode","src","source","tokens","stringify","unusedPathSegments","findMatchingTypedef","undefined","pthSegments","find","typedef","typedefNode","namepathMatch","pathSegment","push","matchingTypedef","reportJSDoc","name","slice","findMatchingImport","imprt","parsedImport","parseImportsExports","estreeToString","replace","trim","namedImportsModuleSpecifier","namedImports","values","namedImportNames","names","namespaceImports","namespaceImportsDefault","namespaceImportsNamespace","namespace","namespaceImportsModuleSpecifier","lastPathSegment","includes","matchingImport","lastPthSegment","fixer","programNode","getNodeByRangeIndex","insertTextBefore","lstPathSegment","mightHaveTypePosition","tagMightHaveTypePosition","hasTypePosition","Boolean","iterateAllJsdocs","docs","description","url","fixable","schema","additionalProperties","properties","enum","module"],"sources":["../../src/rules/preferImportTag.js"],"sourcesContent":["import iterateJsdoc, {\n  parseComment,\n} from '../iterateJsdoc.js';\nimport {\n  commentParserToESTree,\n  estreeToString,\n  // getJSDocComment,\n  parse as parseType,\n  stringify,\n  traverse,\n  tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\nimport {\n  parseImportsExports,\n} from 'parse-imports-exports';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  settings,\n  sourceCode,\n  utils,\n}) => {\n  const {\n    mode,\n  } = settings;\n\n  const {\n    enableFixer = true,\n    exemptTypedefs = true,\n    outputType = 'namespaced-import',\n  } = context.options[0] || {};\n\n  const allComments = sourceCode.getAllComments();\n  const comments = allComments\n    .filter((comment) => {\n      return (/^\\*(?!\\*)/v).test(comment.value);\n    })\n    .map((commentNode) => {\n      return commentParserToESTree(\n        parseComment(commentNode, ''), mode === 'permissive' ? 'typescript' : mode,\n      );\n    });\n\n  const typedefs = comments\n    .flatMap((doc) => {\n      return doc.tags.filter(({\n        tag,\n      }) => {\n        return utils.isNamepathDefiningTag(tag);\n      });\n    });\n\n  const imports = comments\n    .flatMap((doc) => {\n      return doc.tags.filter(({\n        tag,\n      }) => {\n        return tag === 'import';\n      });\n    }).map((tag) => {\n      // Causes problems with stringification otherwise\n      tag.delimiter = '';\n      return tag;\n    });\n\n  /**\n   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag\n   */\n  const iterateInlineImports = (tag) => {\n    const potentialType = tag.type;\n    let parsedType;\n    try {\n      parsedType = mode === 'permissive' ?\n        tryParseType(/** @type {string} */ (potentialType)) :\n        parseType(/** @type {string} */ (potentialType), mode);\n    } catch {\n      return;\n    }\n\n    traverse(parsedType, (nde, parentNode) => {\n      // @ts-expect-error Adding our own property for use below\n      nde.parentNode = parentNode;\n    });\n\n    traverse(parsedType, (nde) => {\n      const {\n        element,\n        type,\n      } = /** @type {import('jsdoc-type-pratt-parser').ImportResult} */ (nde);\n      if (type !== 'JsdocTypeImport') {\n        return;\n      }\n\n      let currentNode = nde;\n\n      /** @type {string[]} */\n      const pathSegments = [];\n\n      /** @type {import('jsdoc-type-pratt-parser').NamePathResult[]} */\n      const nodes = [];\n\n      /** @type {string[]} */\n      const extraPathSegments = [];\n\n      /** @type {(import('jsdoc-type-pratt-parser').QuoteStyle|undefined)[]} */\n      const quotes = [];\n\n      const propertyOrBrackets = /** @type {import('jsdoc-type-pratt-parser').NamePathResult['pathType'][]} */ ([]);\n\n      // @ts-expect-error Referencing our own property added above\n      while (currentNode && currentNode.parentNode) {\n        // @ts-expect-error Referencing our own property added above\n        currentNode = currentNode.parentNode;\n        /* c8 ignore next 3 -- Guard */\n        if (currentNode.type !== 'JsdocTypeNamePath') {\n          break;\n        }\n\n        pathSegments.unshift(currentNode.right.value);\n        nodes.unshift(currentNode);\n        propertyOrBrackets.unshift(currentNode.pathType);\n        quotes.unshift(currentNode.right.meta.quote);\n      }\n\n      /**\n       * @param {string} matchingName\n       * @param {string[]} extrPathSegments\n       */\n      const getFixer = (matchingName, extrPathSegments) => {\n        return () => {\n          /** @type {import('jsdoc-type-pratt-parser').NamePathResult|undefined} */\n          let node = nodes.at(0);\n          if (!node) {\n            // Not really a NamePathResult, but will be converted later anyways\n            node = /** @type {import('jsdoc-type-pratt-parser').NamePathResult} */ (\n              /** @type {unknown} */\n              (nde)\n            );\n          }\n\n          const keys = /** @type {(keyof import('jsdoc-type-pratt-parser').NamePathResult)[]} */ (\n            Object.keys(node)\n          );\n\n          for (const key of keys) {\n            delete node[key];\n          }\n\n          if (extrPathSegments.length) {\n            let newNode = /** @type {import('jsdoc-type-pratt-parser').NamePathResult} */ (\n              /** @type {unknown} */\n              (node)\n            );\n            while (extrPathSegments.length && newNode) {\n              newNode.type = 'JsdocTypeNamePath';\n              newNode.right = {\n                meta: {\n                  quote: quotes.shift(),\n                },\n                type: 'JsdocTypeProperty',\n                value: /** @type {string} */ (extrPathSegments.shift()),\n              };\n\n              newNode.pathType = /** @type {import('jsdoc-type-pratt-parser').NamePathResult['pathType']} */ (\n                propertyOrBrackets.shift()\n              );\n              // @ts-expect-error Temporary\n              newNode.left = {};\n              newNode = /** @type {import('jsdoc-type-pratt-parser').NamePathResult} */ (\n                newNode.left\n              );\n            }\n\n            const nameNode = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (\n              /** @type {unknown} */\n              (newNode)\n            );\n            nameNode.type = 'JsdocTypeName';\n            nameNode.value = matchingName;\n          } else {\n            const newNode = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (\n              /** @type {unknown} */\n              (node)\n            );\n            newNode.type = 'JsdocTypeName';\n            newNode.value = matchingName;\n          }\n\n          for (const src of tag.source) {\n            if (src.tokens.type) {\n              src.tokens.type = `{${stringify(parsedType)}}`;\n              break;\n            }\n          }\n        };\n      };\n\n      /** @type {string[]} */\n      let unusedPathSegments = [];\n\n      const findMatchingTypedef = () => {\n        // Don't want typedefs to find themselves\n        if (!exemptTypedefs) {\n          return undefined;\n        }\n\n        const pthSegments = [\n          ...pathSegments,\n        ];\n        return typedefs.find((typedef) => {\n          let typedefNode = typedef.parsedType;\n          let namepathMatch;\n          while (typedefNode && typedefNode.type === 'JsdocTypeNamePath') {\n            const pathSegment = pthSegments.shift();\n            if (!pathSegment) {\n              namepathMatch = false;\n              break;\n            }\n\n            if (typedefNode.right.value !== pathSegment) {\n              if (namepathMatch === true) {\n                // It stopped matching, so stop\n                break;\n              }\n\n              extraPathSegments.push(pathSegment);\n              namepathMatch = false;\n              continue;\n            }\n\n            namepathMatch = true;\n\n            unusedPathSegments = pthSegments;\n\n            typedefNode = typedefNode.left;\n          }\n\n          return namepathMatch &&\n            // `import('eslint')` matches\n            typedefNode &&\n            typedefNode.type === 'JsdocTypeImport' &&\n            typedefNode.element.value === element.value;\n        });\n      };\n\n      // Check @typedef's first as should be longest match, allowing\n      //   for shorter abbreviations\n      const matchingTypedef = findMatchingTypedef();\n      if (matchingTypedef) {\n        utils.reportJSDoc(\n          'Inline `import()` found; using `@typedef`',\n          tag,\n          enableFixer ? getFixer(matchingTypedef.name, [\n            ...extraPathSegments,\n            ...unusedPathSegments.slice(-1),\n            ...unusedPathSegments.slice(0, -1),\n          ]) : null,\n        );\n        return;\n      }\n\n      const findMatchingImport = () => {\n        for (const imprt of imports) {\n          const parsedImport = parseImportsExports(\n            estreeToString(imprt).replace(/^\\s*@/v, '').trim(),\n          );\n\n          const namedImportsModuleSpecifier = Object.keys(parsedImport.namedImports || {})[0];\n\n          const namedImports = Object.values(parsedImport.namedImports || {})[0]?.[0];\n          const namedImportNames = (namedImports && namedImports.names && Object.keys(namedImports.names)) ?? [];\n\n          const namespaceImports = Object.values(parsedImport.namespaceImports || {})[0]?.[0];\n\n          const namespaceImportsDefault = namespaceImports && namespaceImports.default;\n          const namespaceImportsNamespace = namespaceImports && namespaceImports.namespace;\n          const namespaceImportsModuleSpecifier = Object.keys(parsedImport.namespaceImports || {})[0];\n\n          const lastPathSegment = pathSegments.at(-1);\n\n          if (\n            (namespaceImportsDefault &&\n                namespaceImportsModuleSpecifier === element.value) ||\n              (element.value === namedImportsModuleSpecifier && (\n                (lastPathSegment && namedImportNames.includes(lastPathSegment)) ||\n                lastPathSegment === 'default'\n              )) ||\n              (namespaceImportsNamespace &&\n                namespaceImportsModuleSpecifier === element.value)\n          ) {\n            return {\n              namedImportNames,\n              namedImports,\n              namedImportsModuleSpecifier,\n              namespaceImports,\n              namespaceImportsDefault,\n              namespaceImportsModuleSpecifier,\n              namespaceImportsNamespace,\n            };\n          }\n        }\n\n        return undefined;\n      };\n\n      const matchingImport = findMatchingImport();\n      if (matchingImport) {\n        const {\n          namedImportNames,\n          namedImports,\n          namedImportsModuleSpecifier,\n          namespaceImportsNamespace,\n        } = matchingImport;\n        if (!namedImportNames.length && namedImportsModuleSpecifier && namedImports.default) {\n          utils.reportJSDoc(\n            'Inline `import()` found; prefer `@import`',\n            tag,\n            enableFixer ? getFixer(namedImports.default, []) : null,\n          );\n          return;\n        }\n\n        const lastPthSegment = pathSegments.at(-1);\n        if (lastPthSegment && namedImportNames.includes(lastPthSegment)) {\n          utils.reportJSDoc(\n            'Inline `import()` found; prefer `@import`',\n            tag,\n            enableFixer ? getFixer(lastPthSegment, pathSegments.slice(0, -1)) : null,\n          );\n          return;\n        }\n\n        if (namespaceImportsNamespace) {\n          utils.reportJSDoc(\n            'Inline `import()` found; prefer `@import`',\n            tag,\n            enableFixer ? getFixer(namespaceImportsNamespace, [\n              ...pathSegments,\n            ]) : null,\n          );\n          return;\n        }\n      }\n\n      if (!pathSegments.length) {\n        utils.reportJSDoc(\n          'Inline `import()` found; prefer `@import`',\n          tag,\n          enableFixer ? (fixer) => {\n            getFixer(element.value, [])();\n\n            const programNode = sourceCode.getNodeByRangeIndex(0);\n            return fixer.insertTextBefore(\n              /** @type {import('estree').Program} */ (programNode),\n              `/** @import * as ${element.value} from '${element.value}'; */`,\n            );\n          } : null,\n        );\n        return;\n      }\n\n      const lstPathSegment = pathSegments.at(-1);\n      if (lstPathSegment && lstPathSegment === 'default') {\n        utils.reportJSDoc(\n          'Inline `import()` found; prefer `@import`',\n          tag,\n          enableFixer ? (fixer) => {\n            getFixer(element.value, [])();\n\n            const programNode = sourceCode.getNodeByRangeIndex(0);\n            return fixer.insertTextBefore(\n              /** @type {import('estree').Program} */ (programNode),\n              `/** @import ${element.value} from '${element.value}'; */`,\n            );\n          } : null,\n        );\n        return;\n      }\n\n      utils.reportJSDoc(\n        'Inline `import()` found; prefer `@import`',\n        tag,\n        enableFixer ? (fixer) => {\n          if (outputType === 'namespaced-import') {\n            getFixer(element.value, [\n              ...pathSegments,\n            ])();\n          } else {\n            getFixer(\n              /** @type {string} */ (pathSegments.at(-1)),\n              pathSegments.slice(0, -1),\n            )();\n          }\n\n          const programNode = sourceCode.getNodeByRangeIndex(0);\n          return fixer.insertTextBefore(\n            /** @type {import('estree').Program} */ (programNode),\n            outputType === 'namespaced-import' ?\n              `/** @import * as ${element.value} from '${element.value}'; */` :\n              `/** @import { ${pathSegments.at(-1)} } from '${element.value}'; */`,\n          );\n        } : null,\n      );\n    });\n  };\n\n  for (const tag of jsdoc.tags) {\n    const mightHaveTypePosition = utils.tagMightHaveTypePosition(tag.tag);\n    const hasTypePosition = mightHaveTypePosition === true && Boolean(tag.type);\n    if (hasTypePosition && (!exemptTypedefs || !utils.isNamepathDefiningTag(tag.tag))) {\n      iterateInlineImports(tag);\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Prefer `@import` tags to inline `import()` statements.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/prefer-import-tag.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          enableFixer: {\n            description: 'Whether or not to enable the fixer to add `@import` tags.',\n            type: 'boolean',\n          },\n          exemptTypedefs: {\n            description: 'Whether to allow `import()` statements within `@typedef`',\n            type: 'boolean',\n          },\n\n          // We might add `typedef` and `typedef-local-only`, but also raises\n          //   question of how deep the generated typedef should be\n          outputType: {\n            description: 'What kind of `@import` to generate when no matching `@typedef` or `@import` is found',\n            enum: [\n              'named-import',\n              'namespaced-import',\n            ],\n            type: 'string',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/preferImportTag.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+//# sourceMappingURL=preferImportTag.d.ts.map

package/dist/rules.d.ts

@@ -1250,6 +1250,10 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Whether to check typedefs for use within the file
+           */
+          checkUsedTypedefs?: boolean;
           /**
            * This array can be populated to indicate other types which
            * are automatically considered as defined (in addition to globals, etc.).
@@ -1259,7 +1263,7 @@ export interface Rules {
           /**
            * Whether to disable reporting of errors. Defaults to
            * `false`. This may be set to `true` in order to take advantage of only
-           * marking defined variables as used.
+           * marking defined variables as used or checking used typedefs.
            */
           disableReporting?: boolean;
           /**
@@ -1272,6 +1276,26 @@ export interface Rules {
         }
       ];
 
+  /** Prefer `@import` tags to inline `import()` statements. */
+  "jsdoc/prefer-import-tag": 
+    | []
+    | [
+        {
+          /**
+           * Whether or not to enable the fixer to add `@import` tags.
+           */
+          enableFixer?: boolean;
+          /**
+           * Whether to allow `import()` statements within `@typedef`
+           */
+          exemptTypedefs?: boolean;
+          /**
+           * What kind of `@import` to generate when no matching `@typedef` or `@import` is found
+           */
+          outputType?: "named-import" | "namespaced-import";
+        }
+      ];
+
   /** Reports use of `any` or `*` type */
   "jsdoc/reject-any-type": [];
 

package/package.json

@@ -172,5 +172,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "60.1.1"
+  "version": "60.3.0"
 }

package/src/index-cjs.js

@@ -37,6 +37,7 @@ import noMultiAsterisks from './rules/noMultiAsterisks.js';
 import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
 import noTypes from './rules/noTypes.js';
 import noUndefinedTypes from './rules/noUndefinedTypes.js';
+import preferImportTag from './rules/preferImportTag.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
@@ -111,6 +112,7 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'prefer-import-tag': preferImportTag,
   'reject-any-type': buildRejectOrPreferRuleDefinition({
     description: 'Reports use of `any` or `*` type',
     overrideSettings: {
@@ -283,6 +285,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/prefer-import-tag': 'off',
       'jsdoc/reject-any-type': warnOrError,
       'jsdoc/reject-function-type': warnOrError,
       'jsdoc/require-asterisk-prefix': 'off',

package/src/index.js

@@ -43,6 +43,7 @@ import noMultiAsterisks from './rules/noMultiAsterisks.js';
 import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
 import noTypes from './rules/noTypes.js';
 import noUndefinedTypes from './rules/noUndefinedTypes.js';
+import preferImportTag from './rules/preferImportTag.js';
 import requireAsteriskPrefix from './rules/requireAsteriskPrefix.js';
 import requireDescription from './rules/requireDescription.js';
 import requireDescriptionCompleteSentence from './rules/requireDescriptionCompleteSentence.js';
@@ -117,6 +118,7 @@ index.rules = {
   'no-restricted-syntax': noRestrictedSyntax,
   'no-types': noTypes,
   'no-undefined-types': noUndefinedTypes,
+  'prefer-import-tag': preferImportTag,
   'reject-any-type': buildRejectOrPreferRuleDefinition({
     description: 'Reports use of `any` or `*` type',
     overrideSettings: {
@@ -289,6 +291,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/no-restricted-syntax': 'off',
       'jsdoc/no-types': 'off',
       'jsdoc/no-undefined-types': warnOrError,
+      'jsdoc/prefer-import-tag': 'off',
       'jsdoc/reject-any-type': warnOrError,
       'jsdoc/reject-function-type': warnOrError,
       'jsdoc/require-asterisk-prefix': 'off',

package/src/iterateJsdoc.js

@@ -92,6 +92,10 @@ import esquery from 'esquery';
  *   parseClosureTemplateTag: ParseClosureTemplateTag,
  *   getPreferredTagNameObject: GetPreferredTagNameObject,
  *   pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith
+ *   isNamepathDefiningTag: IsNamepathX,
+ *   isNamepathReferencingTag: IsNamepathX,
+ *   isNamepathOrUrlReferencingTag: IsNamepathX,
+ *   tagMightHaveNamepath: IsNamepathX,
  * }} BasicUtils
  */
 
@@ -116,7 +120,7 @@ import esquery from 'esquery';
  * @callback ReportJSDoc
  * @param {string} msg
  * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]
- * @param {(() => void)|null} [handler]
+ * @param {((fixer: import('eslint').Rule.RuleFixer) => import('eslint').Rule.Fix|void)|null} [handler]
  * @param {boolean} [specRewire]
  * @param {undefined|{
  *   [key: string]: string
@@ -566,7 +570,8 @@ const {
  *   hasNonComment: number,
  *   hasNonCommentBeforeTag: {
  *     [key: string]: boolean|number
- *   }
+ *   },
+ *   foundTypedefValues: string[]
  * }} StateObject
  */
 
@@ -599,6 +604,24 @@ const getBasicUtils = (context, {
   /** @type {BasicUtils} */
   const utils = {};
 
+  for (const method of [
+    'isNamepathDefiningTag',
+    'isNamepathReferencingTag',
+    'isNamepathOrUrlReferencingTag',
+    'tagMightHaveNamepath',
+  ]) {
+    /** @type {IsNamepathX} */
+    utils[
+      /** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */ (
+        method
+      )] = (tagName) => {
+      return jsdocUtils[
+        /** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
+        (method)
+      ](tagName);
+    };
+  }
+
   /** @type {ReportSettings} */
   utils.reportSettings = (message) => {
     context.report({
@@ -771,7 +794,8 @@ const getUtils = (
     report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */ (
       fixer,
     ) => {
-      handler();
+      const extraFix = handler(fixer);
+
       const replacement = utils.stringify(jsdoc, specRewire);
 
       if (!replacement) {
@@ -780,21 +804,38 @@ const getUtils = (
           0, jsdocNode.range[0],
         ).search(/\n[ \t]*$/v);
         if (lastLineBreakPos > -1) {
-          return fixer.removeRange([
-            lastLineBreakPos, jsdocNode.range[1],
-          ]);
+          return [
+            fixer.removeRange([
+              lastLineBreakPos, jsdocNode.range[1],
+            ]),
+            /* c8 ignore next 2 -- Guard */
+            ...(extraFix ? [
+              extraFix,
+            ] : []),
+          ];
         }
 
-        return fixer.removeRange(
-          (/\s/v).test(text.charAt(jsdocNode.range[1])) ?
-            [
-              jsdocNode.range[0], jsdocNode.range[1] + 1,
-            ] :
-            jsdocNode.range,
-        );
+        return [
+          fixer.removeRange(
+            (/\s/v).test(text.charAt(jsdocNode.range[1])) ?
+              [
+                jsdocNode.range[0], jsdocNode.range[1] + 1,
+              ] :
+              jsdocNode.range,
+          ),
+          /* c8 ignore next 2 -- Guard */
+          ...(extraFix ? [
+            extraFix,
+          ] : []),
+        ];
       }
 
-      return fixer.replaceText(jsdocNode, replacement);
+      return [
+        fixer.replaceText(jsdocNode, replacement),
+        ...(extraFix ? [
+          extraFix,
+        ] : []),
+      ];
     } : null, tag, data);
   };
 
@@ -1525,24 +1566,6 @@ const getUtils = (
     };
   }
 
-  for (const method of [
-    'isNamepathDefiningTag',
-    'isNamepathReferencingTag',
-    'isNamepathOrUrlReferencingTag',
-    'tagMightHaveNamepath',
-  ]) {
-    /** @type {IsNamepathX} */
-    utils[
-      /** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */ (
-        method
-      )] = (tagName) => {
-      return jsdocUtils[
-        /** @type {"isNamepathDefiningTag"|"isNamepathReferencingTag"|"isNamepathOrUrlReferencingTag"|"tagMightHaveNamepath"} */
-        (method)
-      ](tagName);
-    };
-  }
-
   /** @type {GetTagStructureForMode} */
   utils.getTagStructureForMode = (mde) => {
     return jsdocUtils.getTagStructureForMode(mde, settings.structuredTags);

package/src/rules/noUndefinedTypes.js

@@ -59,8 +59,12 @@ export default iterateJsdoc(({
   report,
   settings,
   sourceCode,
+  state,
   utils,
 }) => {
+  /** @type {string[]} */
+  const foundTypedefValues = [];
+
   const {
     scopeManager,
   } = sourceCode;
@@ -73,11 +77,13 @@ export default iterateJsdoc(({
   const
     /**
      * @type {{
+     *   checkUsedTypedefs: boolean
      *   definedTypes: string[],
      *   disableReporting: boolean,
-     *   markVariablesAsUsed: boolean
+     *   markVariablesAsUsed: boolean,
      * }}
      */ {
+      checkUsedTypedefs = false,
       definedTypes = [],
       disableReporting = false,
       markVariablesAsUsed = true,
@@ -128,14 +134,16 @@ export default iterateJsdoc(({
       return commentNode.value.replace(/^\s*globals/v, '').trim().split(/,\s*/v);
     }).concat(Object.keys(context.languageOptions.globals ?? []));
 
-  const typedefDeclarations = comments
+  const typedefs = comments
     .flatMap((doc) => {
       return doc.tags.filter(({
         tag,
       }) => {
         return utils.isNamepathDefiningTag(tag);
       });
-    })
+    });
+
+  const typedefDeclarations = typedefs
     .map((tag) => {
       return tag.name;
     });
@@ -204,9 +212,9 @@ export default iterateJsdoc(({
       return [];
     }
 
-    const jsdoc = parseComment(commentNode, '');
+    const jsdc = parseComment(commentNode, '');
 
-    return jsdoc.tags.filter((tag) => {
+    return jsdc.tags.filter((tag) => {
       return tag.tag === 'template';
     });
   };
@@ -510,10 +518,74 @@ export default iterateJsdoc(({
             context.markVariableAsUsed(val);
           }
         }
+
+        if (checkUsedTypedefs && typedefDeclarations.includes(val)) {
+          foundTypedefValues.push(val);
+        }
       }
     });
   }
+
+  state.foundTypedefValues = foundTypedefValues;
 }, {
+  // We use this method rather than checking at end of handler above because
+  //   in that case, it is invoked too many times and would thus report errors
+  //   too many times.
+  exit ({
+    context,
+    state,
+    utils,
+  }) {
+    const {
+      checkUsedTypedefs = false,
+    } = context.options[0] || {};
+
+    if (!checkUsedTypedefs) {
+      return;
+    }
+
+    const allComments = context.sourceCode.getAllComments();
+    const comments = allComments
+      .filter((comment) => {
+        return (/^\*(?!\*)/v).test(comment.value);
+      })
+      .map((commentNode) => {
+        return {
+          doc: parseComment(commentNode, ''),
+          loc: commentNode.loc,
+        };
+      });
+    const typedefs = comments
+      .flatMap(({
+        doc,
+        loc,
+      }) => {
+        const tags = doc.tags.filter(({
+          tag,
+        }) => {
+          return utils.isNamepathDefiningTag(tag);
+        });
+        if (!tags.length) {
+          return [];
+        }
+
+        return {
+          loc,
+          tags,
+        };
+      });
+
+    for (const typedef of typedefs) {
+      if (
+        !state.foundTypedefValues.includes(typedef.tags[0].name)
+      ) {
+        context.report({
+          loc: /** @type {import('@eslint/core').SourceLocation} */ (typedef.loc),
+          message: 'This typedef was not used within the file',
+        });
+      }
+    }
+  },
   iterateAllJsdocs: true,
   meta: {
     docs: {
@@ -524,6 +596,10 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          checkUsedTypedefs: {
+            description: 'Whether to check typedefs for use within the file',
+            type: 'boolean',
+          },
           definedTypes: {
             description: `This array can be populated to indicate other types which
 are automatically considered as defined (in addition to globals, etc.).
@@ -536,7 +612,7 @@ Defaults to an empty array.`,
           disableReporting: {
             description: `Whether to disable reporting of errors. Defaults to
 \`false\`. This may be set to \`true\` in order to take advantage of only
-marking defined variables as used.`,
+marking defined variables as used or checking used typedefs.`,
             type: 'boolean',
           },
           markVariablesAsUsed: {