eslint-plugin-jsdoc 50.6.17 → 50.7.1

package/src/rules/convertToJsdocComments.js

@@ -1,17 +1,16 @@
-import iterateJsdoc from '../iterateJsdoc.js';
 import {
   getSettings,
 } from '../iterateJsdoc.js';
 import {
-  getIndent,
-  getContextObject,
   enforcedContexts,
+  getContextObject,
+  getIndent,
 } from '../jsdocUtils.js';
 import {
-  getNonJsdocComment,
   getDecorator,
-  getReducedASTNode,
   getFollowingComment,
+  getNonJsdocComment,
+  getReducedASTNode,
 } from '@es-joy/jsdoccomment';
 
 /** @type {import('eslint').Rule.RuleModule} */
@@ -44,15 +43,17 @@ export default {
     }
 
     const {
+      allowedPrefixes = [
+        '@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-',
+      ],
       contexts = settings.contexts || [],
       contextsAfter = /** @type {string[]} */ ([]),
       contextsBeforeAndAfter = [
-        'VariableDeclarator', 'TSPropertySignature', 'PropertyDefinition'
+        'VariableDeclarator', 'TSPropertySignature', 'PropertyDefinition',
       ],
       enableFixer = true,
       enforceJsdocLineStyle = 'multi',
       lineOrBlockStyle = 'both',
-      allowedPrefixes = ['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']
     } = context.options[0] ?? {};
 
     let reportingNonJsdoc = false;
@@ -75,7 +76,7 @@ export default {
           column: 0,
           /* c8 ignore next 2 -- Guard */
           // @ts-expect-error Ok
-          line: (comment.loc?.start?.line ?? 1)
+          line: (comment.loc?.start?.line ?? 1),
         },
       };
 
@@ -110,7 +111,7 @@ export default {
 
         const decorator = getDecorator(
           /** @type {import('eslint').Rule.Node} */
-          (baseNode)
+          (baseNode),
         );
         if (decorator) {
           baseNode = /** @type {import('@typescript-eslint/types').TSESTree.Decorator} */ (
@@ -169,6 +170,7 @@ export default {
         if (lineOrBlockStyle === 'line') {
           return;
         }
+
         report('blockCommentsJsdocStyle', comment, node, fixer);
         return;
       }
@@ -177,6 +179,7 @@ export default {
         if (lineOrBlockStyle === 'block') {
           return;
         }
+
         report('lineCommentsJsdocStyle', comment, node, fixer);
       }
     };
@@ -200,17 +203,18 @@ export default {
       reportingNonJsdoc = true;
 
       /** @type {AddComment} */
-      const addComment = (inlineCommentBlock, comment, indent, lines, fixer) => {
+      // eslint-disable-next-line unicorn/consistent-function-scoping -- Avoid conflicts
+      const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
         const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single'
-            ? `/** ${comment.value.trim()} `
-            : `/**\n${indent}*${comment.value.trimEnd()}\n${indent}`
+          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
+            `/** ${commentToAdd.value.trim()} ` :
+            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
         ) +
             `*/${'\n'.repeat((lines || 1) - 1)}`;
 
         return fixer.replaceText(
           /** @type {import('eslint').AST.Token} */
-          (comment),
+          (commentToAdd),
           insertion,
         );
       };
@@ -237,21 +241,23 @@ export default {
       }
 
       /** @type {AddComment} */
-      const addComment = (inlineCommentBlock, comment, indent, lines, fixer) => {
+      const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
         const insertion = (
-          inlineCommentBlock || enforceJsdocLineStyle === 'single'
-            ? `/** ${comment.value.trim()} `
-            : `/**\n${indent}*${comment.value.trimEnd()}\n${indent}`
+          inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
+            `/** ${commentToAdd.value.trim()} ` :
+            `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`
         ) +
             `*/${'\n'.repeat((lines || 1) - 1)}${lines ? `\n${indent.slice(1)}` : ' '}`;
 
-        return [fixer.remove(
+        return [
+          fixer.remove(
           /** @type {import('eslint').AST.Token} */
-          (comment)
-        ), fixer.insertTextBefore(
-          node.type === 'VariableDeclarator' ? node.parent : node,
-          insertion,
-        )];
+            (commentToAdd),
+          ), fixer.insertTextBefore(
+            node.type === 'VariableDeclarator' ? node.parent : node,
+            insertion,
+          ),
+        ];
       };
 
       reportings(comment, node, addComment, ctxts);
@@ -276,31 +282,31 @@ export default {
           if (!reportingNonJsdoc) {
             checkNonJsdocAfter(node, contextsBeforeAndAfter);
           }
-        }
-      )
+        },
+      ),
     };
   },
   meta: {
+    docs: {
+      description: 'Converts non-JSDoc comments preceding or following nodes into JSDoc ones',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header',
+    },
+
     fixable: 'code',
 
     messages: {
       blockCommentsJsdocStyle: 'Block comments should be JSDoc-style.',
       lineCommentsJsdocStyle: 'Line comments should be JSDoc-style.',
     },
-
-    docs: {
-      description: 'Converts non-JSDoc comments preceding or following nodes into JSDoc ones',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header',
-    },
     schema: [
       {
         additionalProperties: false,
         properties: {
           allowedPrefixes: {
-            type: 'array',
             items: {
-              type: 'string'
-            }
+              type: 'string',
+            },
+            type: 'array',
           },
           contexts: {
             items: {
@@ -369,15 +375,19 @@ export default {
             type: 'array',
           },
           enableFixer: {
-            type: 'boolean'
+            type: 'boolean',
           },
           enforceJsdocLineStyle: {
+            enum: [
+              'multi', 'single',
+            ],
             type: 'string',
-            enum: ['multi', 'single']
           },
           lineOrBlockStyle: {
+            enum: [
+              'block', 'line', 'both',
+            ],
             type: 'string',
-            enum: ['block', 'line', 'both']
           },
         },
         type: 'object',

package/src/rules/emptyTags.js

@@ -2,22 +2,26 @@ import iterateJsdoc from '../iterateJsdoc.js';
 
 const defaultEmptyTags = new Set([
   'abstract', 'async', 'generator', 'global', 'hideconstructor',
-  'ignore', 'inner', 'instance', 'override', 'readonly',
 
   // jsdoc doesn't use this form in its docs, but allow for compatibility with
   //  TypeScript which allows and Closure which requires
-  'inheritDoc',
+  'ignore',
 
   // jsdoc doesn't use but allow for TypeScript
+  'inheritDoc', 'inner', 'instance',
   'internal',
+
   'overload',
+
+  'override',
+  'readonly',
 ]);
 
 const emptyIfNotClosure = new Set([
-  'package', 'private', 'protected', 'public', 'static',
-
   // Closure doesn't allow with this casing
-  'inheritdoc',
+  'inheritdoc', 'package', 'private', 'protected', 'public',
+
+  'static',
 ]);
 
 const emptyIfClosure = new Set([
@@ -25,8 +29,8 @@ const emptyIfClosure = new Set([
 ]);
 
 export default iterateJsdoc(({
-  settings,
   jsdoc,
+  settings,
   utils,
 }) => {
   const emptyTags = utils.filterTags(({
@@ -42,7 +46,10 @@ export default iterateJsdoc(({
       settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
   });
 
-  for (const [key, tag] of emptyTags.entries()) {
+  for (const [
+    key,
+    tag,
+  ] of emptyTags.entries()) {
     const content = tag.name || tag.description || tag.type;
     if (content.trim() && (
       // Allow for JSDoc-block final asterisks

package/src/rules/importsAsDependencies.js

@@ -7,7 +7,9 @@ import {
 import {
   readFileSync,
 } from 'fs';
-import {isBuiltin as isBuiltinModule} from 'node:module';
+import {
+  isBuiltin as isBuiltinModule,
+} from 'node:module';
 import {
   join,
 } from 'path';

package/src/rules/informativeDocs.js

@@ -21,72 +21,72 @@ const defaultUselessWords = [
  */
 const getNamesFromNode = (node) => {
   switch (node?.type) {
-  case 'AccessorProperty':
-  case 'MethodDefinition':
-  case 'PropertyDefinition':
-  case 'TSAbstractAccessorProperty':
-  case 'TSAbstractMethodDefinition':
-  case 'TSAbstractPropertyDefinition':
-    return [
-      ...getNamesFromNode(
+    case 'AccessorProperty':
+    case 'MethodDefinition':
+    case 'PropertyDefinition':
+    case 'TSAbstractAccessorProperty':
+    case 'TSAbstractMethodDefinition':
+    case 'TSAbstractPropertyDefinition':
+      return [
+        ...getNamesFromNode(
         /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (
-          node.parent
-        ).parent,
-      ),
-      ...getNamesFromNode(
+            node.parent
+          ).parent,
+        ),
+        ...getNamesFromNode(
         /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-        (node.key),
-      ),
-    ];
+          (node.key),
+        ),
+      ];
 
-  case 'ExportDefaultDeclaration':
-  case 'ExportNamedDeclaration':
-    return getNamesFromNode(
-      /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */
-      (node).declaration
-    );
-  case 'ClassDeclaration':
-  case 'ClassExpression':
-  case 'FunctionDeclaration':
-  case 'FunctionExpression':
-  case 'TSModuleDeclaration':
-  case 'TSMethodSignature':
-  case 'TSDeclareFunction':
-  case 'TSEnumDeclaration':
-  case 'TSEnumMember':
-  case 'TSInterfaceDeclaration':
-  case 'TSTypeAliasDeclaration':
-    return getNamesFromNode(
+    case 'ClassDeclaration':
+    case 'ClassExpression':
+    case 'FunctionDeclaration':
+    case 'FunctionExpression':
+    case 'TSDeclareFunction':
+    case 'TSEnumDeclaration':
+    case 'TSEnumMember':
+    case 'TSInterfaceDeclaration':
+    case 'TSMethodSignature':
+    case 'TSModuleDeclaration':
+    case 'TSTypeAliasDeclaration':
+      return getNamesFromNode(
       /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */
-      (node).id,
-    );
-  case 'Identifier':
-    return [
-      node.name,
-    ];
-  case 'Property':
-    return getNamesFromNode(
+        (node).id,
+      );
+    case 'ExportDefaultDeclaration':
+    case 'ExportNamedDeclaration':
+      return getNamesFromNode(
+      /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */
+        (node).declaration,
+      );
+    case 'Identifier':
+      return [
+        node.name,
+      ];
+    case 'Property':
+      return getNamesFromNode(
       /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-      (node.key),
-    );
-  case 'VariableDeclaration':
-    return getNamesFromNode(
+        (node.key),
+      );
+    case 'VariableDeclaration':
+      return getNamesFromNode(
       /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-      (node.declarations[0]),
-    );
-  case 'VariableDeclarator':
-    return [
-      ...getNamesFromNode(
+        (node.declarations[0]),
+      );
+    case 'VariableDeclarator':
+      return [
+        ...getNamesFromNode(
         /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-        (node.id),
-      ),
-      ...getNamesFromNode(
+          (node.id),
+        ),
+        ...getNamesFromNode(
         /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-        (node.init),
-      ),
-    ].filter(Boolean);
-  default:
-    return [];
+          (node.init),
+        ),
+      ].filter(Boolean);
+    default:
+      return [];
   }
 };
 /* eslint-enable complexity -- Temporary */

package/src/rules/linesBeforeBlock.js

@@ -5,27 +5,33 @@ import iterateJsdoc from '../iterateJsdoc.js';
  * `[` starts an array, `{` starts an object or block, `(` starts a grouping, and `=` starts a
  * declaration (like a variable or a type alias).
  */
-const startPunctuators = new Set(['[', '{', '(', '=']);
+const startPunctuators = new Set([
+  '(', '=', '[', '{',
+]);
 
 export default iterateJsdoc(({
   context,
   jsdocNode,
-  sourceCode,
   report,
+  sourceCode,
   utils,
 }) => {
   const {
     checkBlockStarts,
-    lines = 1,
+    excludedTags = [
+      'type',
+    ],
     ignoreSameLine = true,
-    excludedTags = ['type']
+    lines = 1,
   } = context.options[0] || {};
 
   if (utils.hasATag(excludedTags)) {
     return;
   }
 
-  const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {includeComments: true});
+  const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {
+    includeComments: true,
+  });
   const tokenBefore = tokensBefore.at(-1);
   if (
     !tokenBefore || (
@@ -38,9 +44,9 @@ export default iterateJsdoc(({
   }
 
   if (tokenBefore.loc?.end?.line + lines >=
-    /** @type {number} */
+  /** @type {number} */
       (jsdocNode.loc?.start?.line)
-    ) {
+  ) {
     const startLine = jsdocNode.loc?.start?.line;
     const sameLine = tokenBefore.loc?.end?.line === startLine;
 
@@ -53,11 +59,11 @@ export default iterateJsdoc(({
       let indent = '';
       if (sameLine) {
         const spaceDiff = /** @type {number} */ (jsdocNode.loc?.start?.column) -
-          /** @type {number} */ (tokenBefore.loc?.end?.column);
+        /** @type {number} */ (tokenBefore.loc?.end?.column);
         // @ts-expect-error Should be a comment
         indent = /** @type {import('estree').Comment} */ (
           jsdocNode
-        ).value.match(/^\*\n([ \t]*) \*/)?.[1]?.slice(spaceDiff);
+        ).value.match(/^\*\n([\t ]*) \*/u)?.[1]?.slice(spaceDiff);
         if (!indent) {
           /** @type {import('eslint').AST.Token|import('estree').Comment|undefined} */
           let tokenPrior = tokenBefore;
@@ -66,9 +72,10 @@ export default iterateJsdoc(({
             startColumn = tokenPrior.loc?.start?.column;
             tokenPrior = tokensBefore.pop();
           }
+
           indent = ' '.repeat(
             /* c8 ignore next */
-            /** @type {number} */ (startColumn ? startColumn - 1 : 0)
+            /** @type {number} */ (startColumn ? startColumn - 1 : 0),
           );
         }
       }
@@ -77,19 +84,20 @@ export default iterateJsdoc(({
         /** @type {import('eslint').AST.Token} */
         (tokenBefore),
         '\n'.repeat(lines) +
-        (sameLine ? '\n' + indent : '')
+        (sameLine ? '\n' + indent : ''),
       );
     };
+
     report(`Required ${lines} line(s) before JSDoc block`, fix);
   }
 }, {
   iterateAllJsdocs: true,
   meta: {
-    fixable: 'code',
     docs: {
       description: 'Enforces minimum number of newlines before JSDoc comment blocks',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/lines-before-block.md#repos-sticky-header',
     },
+    fixable: 'code',
     schema: [
       {
         additionalProperties: false,
@@ -98,17 +106,17 @@ export default iterateJsdoc(({
             type: 'boolean',
           },
           excludedTags: {
-            type: 'array',
             items: {
-              type: 'string'
-            }
+              type: 'string',
+            },
+            type: 'array',
           },
           ignoreSameLine: {
             type: 'boolean',
           },
           lines: {
-            type: 'integer'
-          }
+            type: 'integer',
+          },
         },
         type: 'object',
       },

package/src/rules/matchDescription.js

@@ -16,9 +16,9 @@ const stringOrDefault = (value, userDefault) => {
 };
 
 export default iterateJsdoc(({
+  context,
   jsdoc,
   report,
-  context,
   utils,
 }) => {
   const {

package/src/rules/matchName.js

@@ -3,11 +3,11 @@ import iterateJsdoc from '../iterateJsdoc.js';
 // eslint-disable-next-line complexity
 export default iterateJsdoc(({
   context,
-  jsdoc,
-  report,
   info: {
     lastIndex,
   },
+  jsdoc,
+  report,
   utils,
 }) => {
   const {

package/src/rules/multilineBlocks.js

@@ -7,17 +7,17 @@ export default iterateJsdoc(({
 }) => {
   const {
     allowMultipleTags = true,
+    minimumLengthForMultiline = Number.POSITIVE_INFINITY,
+    multilineTags = [
+      '*',
+    ],
     noFinalLineText = true,
-    noZeroLineText = true,
+    noMultilineBlocks = false,
     noSingleLineBlocks = false,
+    noZeroLineText = true,
     singleLineTags = [
       'lends', 'type',
     ],
-    noMultilineBlocks = false,
-    minimumLengthForMultiline = Number.POSITIVE_INFINITY,
-    multilineTags = [
-      '*',
-    ],
   } = context.options[0] || {};
 
   const {
@@ -209,13 +209,13 @@ export default iterateJsdoc(({
             tokens: jsdoc.source.reduce((obj, {
               tokens: {
                 description: desc,
-                tag: tg,
-                type: typ,
-                name: nme,
                 lineEnd,
-                postType,
+                name: nme,
                 postName,
                 postTag,
+                postType,
+                tag: tg,
+                type: typ,
               },
             }) => {
               if (typ) {

package/src/rules/noBadBlocks.js

@@ -9,10 +9,10 @@ const commentRegexp = /^\/\*(?!\*)/u;
 const extraAsteriskCommentRegexp = /^\/\*{3,}/u;
 
 export default iterateJsdoc(({
-  context,
-  sourceCode,
   allComments,
+  context,
   makeReport,
+  sourceCode,
 }) => {
   const [
     {
@@ -34,7 +34,7 @@ export default iterateJsdoc(({
 
     const initialText = commentText.replace(commentRegexp, '').trimStart();
     if ([
-      'eslint'
+      'eslint',
     ].some((directive) => {
       return initialText.startsWith(directive);
     })) {

package/src/rules/noMultiAsterisks.js

@@ -24,17 +24,17 @@ export default iterateJsdoc(({
 
   // eslint-disable-next-line complexity -- Todo
   jsdoc.source.some(({
-    tokens,
     number,
+    tokens,
   }) => {
     const {
       delimiter,
-      tag,
-      name,
-      type,
       description,
       end,
+      name,
       postDelimiter,
+      tag,
+      type,
     } = tokens;
 
     if (

package/src/rules/noRestrictedSyntax.js

@@ -19,8 +19,8 @@ export default iterateJsdoc(({
   } = context.options[0];
 
   const {
-    foundContext,
     contextStr,
+    foundContext,
   } = utils.findContext(contexts, comment);
 
   // We are not on the *particular* matching context/comment, so don't assume

package/src/rules/noTypes.js

@@ -34,7 +34,7 @@ export default iterateJsdoc(({
   contextDefaults: [
     'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
     // Add this to above defaults
-    'TSMethodSignature'
+    'TSMethodSignature',
   ],
   meta: {
     docs: {