eslint-plugin-jsdoc 50.6.17 → 50.7.1

package/src/rules/noUndefinedTypes.js

@@ -1,18 +1,15 @@
-import { dirname, join } from 'path';
-import { fileURLToPath } from 'url';
-
-import {parseImportsExports} from 'parse-imports-exports';
+import iterateJsdoc, {
+  parseComment,
+} from '../iterateJsdoc.js';
 import {
   getJSDocComment,
   parse as parseType,
   traverse,
   tryParse as tryParseType,
 } from '@es-joy/jsdoccomment';
-import iterateJsdoc, {
-  parseComment,
-} from '../iterateJsdoc.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
+import {
+  parseImportsExports,
+} from 'parse-imports-exports';
 
 const extraTypes = [
   'null', 'undefined', 'void', 'string', 'boolean', 'object',
@@ -89,9 +86,9 @@ export default iterateJsdoc(({
   /** @type {(string|undefined)[]} */
   let definedPreferredTypes = [];
   const {
+    mode,
     preferredTypes,
     structuredTags,
-    mode,
   } = settings;
   if (Object.keys(preferredTypes).length) {
     definedPreferredTypes = /** @type {string[]} */ (Object.values(preferredTypes).map((preferredType) => {
@@ -135,7 +132,6 @@ export default iterateJsdoc(({
       return tag.name;
     });
 
-
   const importTags = settings.mode === 'typescript' ? /** @type {string[]} */ (comments.flatMap((doc) => {
     return doc.tags.filter(({
       tag,
@@ -144,12 +140,14 @@ export default iterateJsdoc(({
     });
   }).flatMap((tag) => {
     const {
-      type, name, description
+      description,
+      name,
+      type,
     } = tag;
-    const typePart = type ? `{${type}} `: '';
-    const imprt = 'import ' + (description
-      ? `${typePart}${name} ${description}`
-      : `${typePart}${name}`);
+    const typePart = type ? `{${type}} ` : '';
+    const imprt = 'import ' + (description ?
+      `${typePart}${name} ${description}` :
+      `${typePart}${name}`);
 
     const importsExports = parseImportsExports(imprt.trim());
 
@@ -159,6 +157,7 @@ export default iterateJsdoc(({
       if (namedImports.default) {
         types.push(namedImports.default);
       }
+
       if (namedImports.names) {
         types.push(...Object.keys(namedImports.names));
       }
@@ -169,6 +168,7 @@ export default iterateJsdoc(({
       if (namespaceImports.namespace) {
         types.push(namespaceImports.namespace);
       }
+
       if (namespaceImports.default) {
         types.push(namespaceImports.default);
       }
@@ -226,14 +226,20 @@ export default iterateJsdoc(({
    * @returns {Set<string>}
    */
   const getValidRuntimeIdentifiers = (scope) => {
-    const result = new Set()
-    while (scope) {
-      for (const {name} of scope.variables) {
-        result.add(name)
+    const result = new Set();
+
+    let scp = scope;
+    while (scp) {
+      for (const {
+        name,
+      } of scp.variables) {
+        result.add(name);
       }
-      scope = scope.upper
+
+      scp = scp.upper;
     }
-    return result
+
+    return result;
   };
 
   const allDefinedTypes = new Set(globalScope.variables.map(({
@@ -340,8 +346,8 @@ export default iterateJsdoc(({
   ].filter(Boolean));
 
   for (const {
-    tag,
     parsedType,
+    tag,
   } of tagsWithTypes) {
     traverse(parsedType, (nde) => {
       const {

package/src/rules/requireAsteriskPrefix.js

@@ -2,9 +2,9 @@ import iterateJsdoc from '../iterateJsdoc.js';
 
 export default iterateJsdoc(({
   context,
+  indent,
   jsdoc,
   utils,
-  indent,
 }) => {
   const [
     defaultRequireValue = 'always',
@@ -28,9 +28,9 @@ export default iterateJsdoc(({
   }) => {
     const {
       delimiter,
-      tag,
-      end,
       description,
+      end,
+      tag,
     } = tokens;
 
     /**

package/src/rules/requireDescription.js

@@ -13,10 +13,10 @@ const checkDescription = (description) => {
 };
 
 export default iterateJsdoc(({
+  context,
   jsdoc,
   report,
   utils,
-  context,
 }) => {
   if (utils.avoidDocs()) {
     return;

package/src/rules/requireDescriptionCompleteSentence.js

@@ -2,11 +2,11 @@ import iterateJsdoc from '../iterateJsdoc.js';
 import escapeStringRegexp from 'escape-string-regexp';
 
 const otherDescriptiveTags = new Set([
+  'classdesc', 'deprecated', 'exception', 'file', 'fileoverview', 'overview',
   // 'copyright' and 'see' might be good addition, but as the former may be
   //   sensitive text, and the latter may have just a link, they are not
   //   included by default
-  'summary', 'file', 'fileoverview', 'overview', 'classdesc', 'todo',
-  'deprecated', 'throws', 'exception', 'yields', 'yield',
+  'summary', 'throws', 'todo', 'yield', 'yields',
 ]);
 
 /**
@@ -112,7 +112,7 @@ const validateDescription = (
     return false;
   }
 
-  const descriptionNoHeadings = description.replaceAll(/^\s*#[^\n]*(\n|$)/gm, '');
+  const descriptionNoHeadings = description.replaceAll(/^\s*#[^\n]*(\n|$)/gmu, '');
 
   const paragraphs = extractParagraphs(descriptionNoHeadings).filter(Boolean);
 
@@ -123,7 +123,7 @@ const validateDescription = (
       let text = sourceCode.getText(jsdocNode);
 
       if (!/[.:?!]$/u.test(paragraph)) {
-        const line = paragraph.split('\n').filter(Boolean).pop();
+        const line = paragraph.split('\n').findLast(Boolean);
         text = text.replace(new RegExp(`${escapeStringRegexp(
           /** @type {string} */
           (line),
@@ -210,11 +210,11 @@ const validateDescription = (
 };
 
 export default iterateJsdoc(({
-  sourceCode,
   context,
   jsdoc,
-  report,
   jsdocNode,
+  report,
+  sourceCode,
   utils,
 }) => {
   const /** @type {{abbreviations: string[], newlineBeforeCapsAssumesBadSentenceEnd: boolean}} */ {

package/src/rules/requireFileOverview.js

@@ -23,10 +23,10 @@ const setDefaults = (state) => {
 };
 
 export default iterateJsdoc(({
+  context,
   jsdocNode,
   state,
   utils,
-  context,
 }) => {
   const {
     tags = defaultTags,
@@ -70,9 +70,9 @@ export default iterateJsdoc(({
     for (const [
       tagName,
       {
+        initialCommentsOnly = false,
         mustExist = false,
         preventDuplicates = false,
-        initialCommentsOnly = false,
       },
     ] of Object.entries(tags)) {
       const obj = utils.getPreferredTagNameObject({
@@ -144,8 +144,8 @@ export default iterateJsdoc(({
     type: 'suggestion',
   },
   nonComment ({
-    state,
     node,
+    state,
   }) {
     if (!state.hasNonComment) {
       state.hasNonComment = node.range[0];

package/src/rules/requireHyphenBeforeParamDescription.js

@@ -1,12 +1,9 @@
 import iterateJsdoc from '../iterateJsdoc.js';
 
 export default iterateJsdoc(({
-  sourceCode,
-  utils,
-  report,
   context,
   jsdoc,
-  jsdocNode,
+  utils,
 }) => {
   const [
     mainCircumstance,
@@ -62,7 +59,7 @@ export default iterateJsdoc(({
                 break;
               }
             }
-          }
+          },
         );
       }
     } else if (startsWithHyphen) {

package/src/rules/requireJsdoc.js

@@ -3,13 +3,13 @@ import {
   getSettings,
 } from '../iterateJsdoc.js';
 import {
+  enforcedContexts,
   exemptSpeciaMethods,
-  isConstructor,
+  getContextObject,
   getFunctionParameterNames,
-  hasReturnValue,
   getIndent,
-  getContextObject,
-  enforcedContexts,
+  hasReturnValue,
+  isConstructor,
 } from '../jsdocUtils.js';
 import {
   getDecorator,
@@ -215,13 +215,13 @@ const getOption = (context, baseObject, option, key) => {
  */
 const getOptions = (context, settings) => {
   const {
-    publicOnly,
     contexts = settings.contexts || [],
+    enableFixer = true,
     exemptEmptyConstructors = true,
     exemptEmptyFunctions = false,
-    enableFixer = true,
     fixerMessage = '',
     minLineCount = undefined,
+    publicOnly,
   } = context.options[0] || {};
 
   return {
@@ -309,13 +309,13 @@ export default {
     const opts = getOptions(context, settings);
 
     const {
-      require: requireOption,
       contexts,
-      exemptEmptyFunctions,
-      exemptEmptyConstructors,
       enableFixer,
+      exemptEmptyConstructors,
+      exemptEmptyFunctions,
       fixerMessage,
       minLineCount,
+      require: requireOption,
     } = opts;
 
     const publicOnly =
@@ -429,7 +429,7 @@ export default {
 
         const decorator = getDecorator(
           /** @type {import('eslint').Rule.Node} */
-          (baseNode)
+          (baseNode),
         );
         if (decorator) {
           baseNode = decorator;
@@ -535,10 +535,10 @@ export default {
 
         if (
           [
-            'VariableDeclarator', 'AssignmentExpression', 'ExportDefaultDeclaration',
+            'AssignmentExpression', 'ExportDefaultDeclaration', 'VariableDeclarator',
           ].includes(node.parent.type) ||
           [
-            'Property', 'ObjectProperty', 'ClassProperty', 'PropertyDefinition',
+            'ClassProperty', 'ObjectProperty', 'Property', 'PropertyDefinition',
           ].includes(node.parent.type) &&
             node ===
               /**
@@ -591,10 +591,10 @@ export default {
 
         if (
           [
-            'VariableDeclarator', 'AssignmentExpression', 'ExportDefaultDeclaration',
+            'AssignmentExpression', 'ExportDefaultDeclaration', 'VariableDeclarator',
           ].includes(node.parent.type) ||
           [
-            'Property', 'ObjectProperty', 'ClassProperty', 'PropertyDefinition',
+            'ClassProperty', 'ObjectProperty', 'Property', 'PropertyDefinition',
           ].includes(node.parent.type) &&
             node ===
               /**

package/src/rules/requireParam.js

@@ -33,9 +33,9 @@ const rootNamer = (desiredRoots, currentIndex) => {
 
 /* eslint-disable complexity -- Temporary */
 export default iterateJsdoc(({
+  context,
   jsdoc,
   utils,
-  context,
 }) => {
   /* eslint-enable complexity -- Temporary */
   if (utils.avoidDocs()) {
@@ -49,18 +49,18 @@ export default iterateJsdoc(({
 
   const {
     autoIncrementBase = 0,
-    checkRestProperty = false,
     checkDestructured = true,
     checkDestructuredRoots = true,
+    checkRestProperty = false,
     checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
     enableFixer = true,
-    enableRootFixer = true,
     enableRestElementFixer = true,
+    enableRootFixer = true,
+    ignoreWhenAllParamsMissing = false,
     unnamedRootBase = [
       'root',
     ],
     useDefaultObjectProperties = false,
-    ignoreWhenAllParamsMissing = false,
   } = context.options[0] || {};
 
   const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
@@ -225,7 +225,6 @@ export default iterateJsdoc(({
     functionParameterIdx,
     functionParameterName,
   ] of functionParameterNames.entries()) {
-
     let inc;
     if (Array.isArray(functionParameterName)) {
       const matchedJsdoc = shallowJsdocParameterNames[functionParameterIdx - thisOffset];
@@ -243,6 +242,7 @@ export default iterateJsdoc(({
         rootName = nextRootName;
         inc = incremented;
       }
+
       [
         nextRootName,
         incremented,
@@ -250,10 +250,10 @@ export default iterateJsdoc(({
       ] = namer();
 
       const {
-        hasRestElement,
         hasPropertyRest,
-        rests,
+        hasRestElement,
         names,
+        rests,
       } = /**
            * @type {import('../jsdocUtils.js').FlattendRootInfo & {
            *   annotationParamName?: string | undefined;
@@ -394,8 +394,8 @@ export default iterateJsdoc(({
   const fix = ({
     functionParameterIdx,
     functionParameterName,
-    remove,
     inc,
+    remove,
     type,
   }) => {
     if (inc && !enableRootFixer) {
@@ -460,8 +460,8 @@ export default iterateJsdoc(({
 
     const offset = jsdoc.source.findIndex(({
       tokens: {
-        tag,
         end,
+        tag,
       },
     }) => {
       return tag || end;

package/src/rules/requireProperty.js

@@ -7,7 +7,7 @@ export default iterateJsdoc(({
     tag,
   }) => {
     return [
-      'typedef', 'namespace',
+      'namespace', 'typedef',
     ].includes(tag);
   });
   if (!propertyAssociatedTags.length) {

package/src/rules/requireReturns.js

@@ -36,6 +36,7 @@ const canSkip = (utils) => {
 };
 
 export default iterateJsdoc(({
+  context,
   info: {
     comment,
   },
@@ -43,7 +44,6 @@ export default iterateJsdoc(({
   report,
   settings,
   utils,
-  context,
 }) => {
   const {
     contexts,

package/src/rules/requireReturnsCheck.js

@@ -110,7 +110,7 @@ export default iterateJsdoc(({
     Boolean(
       !exemptGenerators || !node ||
       !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||
-      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator
+      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,
     )
   ) {
     report(`JSDoc @${tagName} declaration present but return expression not available in function.`);

package/src/rules/requireReturnsDescription.js

@@ -8,7 +8,7 @@ export default iterateJsdoc(({
     const type = jsdocTag.type && jsdocTag.type.trim();
 
     if ([
-      'void', 'undefined', 'Promise<void>', 'Promise<undefined>',
+      'Promise<undefined>', 'Promise<void>', 'undefined', 'void',
     ].includes(type)) {
       return;
     }

package/src/rules/requireTemplate.js

@@ -1,34 +1,38 @@
+import iterateJsdoc from '../iterateJsdoc.js';
 import {
   parse as parseType,
   traverse,
   tryParse as tryParseType,
 } from '@es-joy/jsdoccomment';
-import iterateJsdoc from '../iterateJsdoc.js';
 
 export default iterateJsdoc(({
   context,
-  utils,
   node,
-  settings,
   report,
+  settings,
+  utils,
 }) => {
   const {
     requireSeparateTemplates = false,
   } = context.options[0] || {};
 
   const {
-    mode
+    mode,
   } = settings;
 
   const usedNames = new Set();
   const templateTags = utils.getTags('template');
-  const templateNames = templateTags.flatMap(({name}) => {
-    return name.split(/,\s*/);
+  const templateNames = templateTags.flatMap(({
+    name,
+  }) => {
+    return name.split(/,\s*/u);
   });
 
   for (const tag of templateTags) {
-    const {name} = tag;
-    const names = name.split(/,\s*/);
+    const {
+      name,
+    } = tag;
+    const names = name.split(/,\s*/u);
     if (requireSeparateTemplates && names.length > 1) {
       report(`Missing separate @template for ${names[1]}`, null, tag);
     }
@@ -41,11 +45,21 @@ export default iterateJsdoc(({
    *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
    */
   const checkTypeParams = (aliasDeclaration) => {
-    /* c8 ignore next -- Guard */
-    const {params} = aliasDeclaration.typeParameters ?? {params: []};
-    for (const {name: {name}} of params) {
+    const {
+      params,
+      /* c8 ignore next -- Guard */
+    } = aliasDeclaration.typeParameters ?? {
+      /* c8 ignore next -- Guard */
+      params: [],
+    };
+    for (const {
+      name: {
+        name,
+      },
+    } of params) {
       usedNames.add(name);
     }
+
     for (const usedName of usedNames) {
       if (!templateNames.includes(usedName)) {
         report(`Missing @template ${usedName}`);
@@ -60,32 +74,35 @@ export default iterateJsdoc(({
     if (!nde) {
       return;
     }
+
     switch (nde.type) {
-    case 'ExportDefaultDeclaration':
-      switch (nde.declaration?.type) {
-        case 'ClassDeclaration':
-        case 'FunctionDeclaration':
-        case 'TSInterfaceDeclaration':
-          checkTypeParams(nde.declaration);
-          break;
-      }
-      break;
-    case 'ExportNamedDeclaration':
-      switch (nde.declaration?.type) {
       case 'ClassDeclaration':
       case 'FunctionDeclaration':
-      case 'TSTypeAliasDeclaration':
       case 'TSInterfaceDeclaration':
-        checkTypeParams(nde.declaration);
+      case 'TSTypeAliasDeclaration':
+        checkTypeParams(nde);
+        break;
+      case 'ExportDefaultDeclaration':
+        switch (nde.declaration?.type) {
+          case 'ClassDeclaration':
+          case 'FunctionDeclaration':
+          case 'TSInterfaceDeclaration':
+            checkTypeParams(nde.declaration);
+            break;
+        }
+
+        break;
+      case 'ExportNamedDeclaration':
+        switch (nde.declaration?.type) {
+          case 'ClassDeclaration':
+          case 'FunctionDeclaration':
+          case 'TSInterfaceDeclaration':
+          case 'TSTypeAliasDeclaration':
+            checkTypeParams(nde.declaration);
+            break;
+        }
+
         break;
-      }
-      break;
-    case 'ClassDeclaration':
-    case 'FunctionDeclaration':
-    case 'TSTypeAliasDeclaration':
-    case 'TSInterfaceDeclaration':
-      checkTypeParams(nde);
-      break;
     }
   };
 
@@ -99,7 +116,7 @@ export default iterateJsdoc(({
     try {
       parsedType = mode === 'permissive' ?
         tryParseType(/** @type {string} */ (potentialTag.type)) :
-        parseType(/** @type {string} */ (potentialTag.type), mode)
+        parseType(/** @type {string} */ (potentialTag.type), mode);
     } catch {
       return;
     }
@@ -109,7 +126,7 @@ export default iterateJsdoc(({
         type,
         value,
       } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
-      if (type === 'JsdocTypeName' && (/^[A-Z]$/).test(value)) {
+      if (type === 'JsdocTypeName' && (/^[A-Z]$/u).test(value)) {
         usedNames.add(value);
         if (!usedNameToTag.has(value)) {
           usedNameToTag.set(value, potentialTag);
@@ -143,7 +160,9 @@ export default iterateJsdoc(({
   const callbackTags = utils.getTags('callback');
   const functionTags = utils.getTags('function');
   if (callbackTags.length || functionTags.length) {
-    checkTagsAndTemplates(['param', 'returns']);
+    checkTagsAndTemplates([
+      'param', 'returns',
+    ]);
     return;
   }
 
@@ -156,7 +175,9 @@ export default iterateJsdoc(({
   const potentialTypedef = typedefTags[0];
   checkForUsedTypes(potentialTypedef);
 
-  checkTagsAndTemplates(['property']);
+  checkTagsAndTemplates([
+    'property',
+  ]);
 }, {
   iterateAllJsdocs: true,
   meta: {
@@ -169,8 +190,8 @@ export default iterateJsdoc(({
         additionalProperties: false,
         properties: {
           requireSeparateTemplates: {
-            type: 'boolean'
-          }
+            type: 'boolean',
+          },
         },
         type: 'object',
       },

package/src/rules/requireYields.js

@@ -65,15 +65,15 @@ const checkTagName = (utils, report, tagName) => {
 };
 
 export default iterateJsdoc(({
+  context,
   report,
   utils,
-  context,
 }) => {
   const {
-    next = false,
-    nextWithGeneratorTag = false,
     forceRequireNext = false,
     forceRequireYields = false,
+    next = false,
+    nextWithGeneratorTag = false,
     withGeneratorTag = true,
   } = context.options[0] || {};
 

package/src/rules/requireYieldsCheck.js

@@ -77,8 +77,8 @@ export default iterateJsdoc(({
   }
 
   const {
-    next = false,
     checkGeneratorsOnly = false,
+    next = false,
   } = context.options[0] || {};
 
   const [