eslint-plugin-jsdoc 50.6.17 → 50.7.0

package/src/rules/checkAlignment.js

@@ -9,10 +9,10 @@ const trimStart = (string) => {
 };
 
 export default iterateJsdoc(({
-  sourceCode,
+  indent,
   jsdocNode,
   report,
-  indent,
+  sourceCode,
 }) => {
   // `indent` is whitespace from line 1 (`/**`), so slice and account for "/".
   const indentLevel = indent.length + 1;

package/src/rules/checkExamples.js

@@ -1,5 +1,3 @@
-// Todo: When replace `CLIEngine` with `ESLint` when feature set complete per https://github.com/eslint/eslint/issues/14745
-// https://github.com/eslint/eslint/blob/master/docs/user-guide/migrating-to-7.0.0.md#-the-cliengine-class-has-been-deprecated
 import iterateJsdoc from '../iterateJsdoc.js';
 import eslint, {
   ESLint,
@@ -110,10 +108,10 @@ const getLinesCols = (text) => {
 };
 
 export default iterateJsdoc(({
-  report,
-  utils,
   context,
   globalState,
+  report,
+  utils,
 }) => {
   if (semver.gte(ESLint.version, '8.0.0')) {
     report(
@@ -143,21 +141,21 @@ export default iterateJsdoc(({
     rejectExampleCodeRegex = null,
   } = options;
   const {
+    allowInlineConfig = true,
+    baseConfig = {},
+    captionRequired = false,
     checkDefaults = false,
+    checkEslintrc = true,
     checkParams = false,
     checkProperties = false,
-    noDefaultExampleRules = false,
-    checkEslintrc = true,
+    configFile,
     matchingFileName = null,
     matchingFileNameDefaults = null,
     matchingFileNameParams = null,
     matchingFileNameProperties = null,
+    noDefaultExampleRules = false,
     paddedIndent = 0,
-    baseConfig = {},
-    configFile,
-    allowInlineConfig = true,
     reportUnusedDisableDirectives = true,
-    captionRequired = false,
   } = options;
 
   // Make this configurable?
@@ -201,18 +199,18 @@ export default iterateJsdoc(({
    * }} cfg
    */
   const checkSource = ({
-    filename,
+    cols = 0,
     defaultFileName,
-    rules = expressionRules,
+    filename,
     lines = 0,
-    cols = 0,
+    rules = expressionRules,
     skipInit,
     source,
-    targetTagName,
     sources = [],
     tag = {
       line: 0,
     },
+    targetTagName,
   }) => {
     if (!skipInit) {
       sources.push({
@@ -222,8 +220,6 @@ export default iterateJsdoc(({
       });
     }
 
-    // Todo: Make fixable
-
     /**
      * @param {{
      *   nonJSPrefacingCols: import('../iterateJsdoc.js').Integer,
@@ -305,11 +301,11 @@ export default iterateJsdoc(({
       const codeStartCol = likelyNestedJSDocIndentSpace;
 
       for (const {
-        message,
-        line,
         column,
-        severity,
+        line,
+        message,
         ruleId,
+        severity,
       } of messages) {
         const startLine = codeStartLine + line + zeroBasedLineIndexAdjust;
         const startCol = codeStartCol + (
@@ -450,9 +446,9 @@ export default iterateJsdoc(({
       exampleCodeRegex.lastIndex = 0;
       while ((exampleCode = exampleCodeRegex.exec(source)) !== null) {
         const {
-          index,
           '0': n0,
           '1': n1,
+          index,
         } = exampleCode;
 
         // Count anything preceding user regex match (can affect line numbering)

package/src/rules/checkIndentation.js

@@ -26,10 +26,10 @@ const maskCodeBlocks = (str) => {
 };
 
 export default iterateJsdoc(({
-  sourceCode,
+  context,
   jsdocNode,
   report,
-  context,
+  sourceCode,
 }) => {
   const options = context.options[0] || {};
   const /** @type {{excludeTags: string[]}} */ {

package/src/rules/checkLineAlignment.js

@@ -174,6 +174,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
  */
 const checkAlignment = ({
   customSpacings,
+  disableWrapIndent,
   indent,
   jsdoc,
   jsdocNode,
@@ -182,16 +183,15 @@ const checkAlignment = ({
   tags,
   utils,
   wrapIndent,
-  disableWrapIndent,
 }) => {
   const transform = commentFlow(
     alignTransform({
       customSpacings,
+      disableWrapIndent,
       indent,
       preserveMainDescriptionPostDelimiter,
       tags,
       wrapIndent,
-      disableWrapIndent,
     }),
   );
   const transformedJsdoc = transform(jsdoc);
@@ -217,21 +217,21 @@ const checkAlignment = ({
 };
 
 export default iterateJsdoc(({
+  context,
   indent,
   jsdoc,
   jsdocNode,
   report,
-  context,
   utils,
 }) => {
   const {
+    customSpacings,
+    disableWrapIndent = false,
+    preserveMainDescriptionPostDelimiter,
     tags: applicableTags = [
       'param', 'arg', 'argument', 'property', 'prop', 'returns', 'return',
     ],
-    preserveMainDescriptionPostDelimiter,
-    customSpacings,
     wrapIndent = '',
-    disableWrapIndent = false,
   } = context.options[1] || {};
 
   if (context.options[0] === 'always') {
@@ -249,6 +249,7 @@ export default iterateJsdoc(({
 
     checkAlignment({
       customSpacings,
+      disableWrapIndent,
       indent,
       jsdoc,
       jsdocNode,
@@ -257,7 +258,6 @@ export default iterateJsdoc(({
       tags: applicableTags,
       utils,
       wrapIndent,
-      disableWrapIndent,
     });
 
     return;
@@ -347,6 +347,9 @@ export default iterateJsdoc(({
               },
             },
           },
+          disableWrapIndent: {
+            type: 'boolean',
+          },
           preserveMainDescriptionPostDelimiter: {
             default: false,
             type: 'boolean',
@@ -360,9 +363,6 @@ export default iterateJsdoc(({
           wrapIndent: {
             type: 'string',
           },
-          disableWrapIndent: {
-            type: 'boolean',
-          },
         },
         type: 'object',
       },

package/src/rules/checkParamNames.js

@@ -87,6 +87,7 @@ const validateParameterNames = (
 
       return true;
     }
+
     if (
       typeof functionParameterName === 'object' &&
         'name' in functionParameterName &&
@@ -98,6 +99,7 @@ const validateParameterNames = (
         thisOffset--;
         return false;
       }
+
       report(
         `Expected @${targetTagName} name to be "${expectedName}". Got "${actualName}".`,
         null,
@@ -118,10 +120,10 @@ const validateParameterNames = (
       const [
         parameterName,
         {
-          names: properties,
+          annotationParamName,
           hasPropertyRest,
+          names: properties,
           rests,
-          annotationParamName,
         },
       ] =
         /**
@@ -191,8 +193,8 @@ const validateParameterNames = (
       const hasMissing = missingProperties.length;
       if (hasMissing) {
         for (const {
-          tagPlacement,
           name: missingProperty,
+          tagPlacement,
         } of missingProperties) {
           report(`Missing @${targetTagName} "${missingProperty}"`, null, tagPlacement);
         }
@@ -271,8 +273,14 @@ const validateParameterNames = (
       // When disableMissingParamChecks is true tag names can be omitted.
       // Report when the tag names do not match the expected names or they are used out of order.
       if (disableMissingParamChecks) {
-        const usedExpectedNames = expectedNames.map(a => a?.toString()).filter(expectedName => expectedName && actualNames.includes(expectedName));
-        const usedInOrder = actualNames.every((actualName, idx) => actualName === usedExpectedNames[idx]);
+        const usedExpectedNames = expectedNames.map((a) => {
+          return a?.toString();
+        }).filter((expectedName) => {
+          return expectedName && actualNames.includes(expectedName);
+        });
+        const usedInOrder = actualNames.every((actualName, idx) => {
+          return actualName === usedExpectedNames[idx];
+        });
         if (usedInOrder) {
           return false;
         }
@@ -283,9 +291,9 @@ const validateParameterNames = (
           expectedNames.map((expectedName) => {
             return typeof expectedName === 'object' &&
               'name' in expectedName &&
-              expectedName.restElement
-              ? '...' + expectedName.name
-              : expectedName;
+              expectedName.restElement ?
+              '...' + expectedName.name :
+              expectedName;
           }).join(', ')
         }". Got "${actualNames.join(', ')}".`,
         null,
@@ -318,8 +326,8 @@ const validateParameterNamesDeep = (
   let lastRealParameter;
 
   return jsdocParameterNames.some(({
-    name: jsdocParameterName,
     idx,
+    name: jsdocParameterName,
   }) => {
     const isPropertyPath = jsdocParameterName.includes('.');
 
@@ -356,26 +364,26 @@ const validateParameterNamesDeep = (
 
 const allowedNodes = [
   'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
-    // Add this to above defaults
-    'TSMethodSignature'
+  // Add this to above defaults
+  'TSMethodSignature',
 ];
 
 export default iterateJsdoc(({
   context,
   jsdoc,
+  node,
   report,
   utils,
-  node,
 }) => {
   const {
     allowExtraTrailingParamDocs,
     checkDestructured = true,
     checkRestProperty = false,
     checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/',
-    enableFixer = false,
-    useDefaultObjectProperties = false,
     disableExtraPropertyReporting = false,
     disableMissingParamChecks = false,
+    enableFixer = false,
+    useDefaultObjectProperties = false,
   } = context.options[0] || {};
 
   // Although we might just remove global settings contexts from applying to

package/src/rules/checkPropertyNames.js

@@ -61,8 +61,8 @@ const validatePropertyNamesDeep = (
   let lastRealProperty;
 
   return jsdocPropertyNames.some(({
-    name: jsdocPropertyName,
     idx,
+    name: jsdocPropertyName,
   }) => {
     const isPropertyPath = jsdocPropertyName.includes('.');
 

package/src/rules/checkTagNames.js

@@ -61,14 +61,14 @@ const typedTagsUnnecessaryOutsideDeclare = new Set([
 ]);
 
 export default iterateJsdoc(({
-  sourceCode,
-  jsdoc,
-  report,
-  utils,
   context,
+  jsdoc,
+  jsdocNode,
   node,
+  report,
   settings,
-  jsdocNode,
+  sourceCode,
+  utils,
 }) => {
   const
     /**
@@ -87,8 +87,8 @@ export default iterateJsdoc(({
   /** @type {(string|undefined)[]} */
   let definedPreferredTags = [];
   const {
-    tagNamePreference,
     structuredTags,
+    tagNamePreference,
   } = settings;
   const definedStructuredTags = Object.keys(structuredTags);
   const definedNonPreferredTags = Object.keys(tagNamePreference);
@@ -146,7 +146,7 @@ export default iterateJsdoc(({
     }
 
     if (context.getFilename().endsWith('.d.ts') && [
-      'Program', null, undefined,
+      null, 'Program', undefined,
     ].includes(node?.parent?.type)) {
       return false;
     }

package/src/rules/checkTemplateNames.js

@@ -1,19 +1,18 @@
+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 {
-    mode
+    mode,
   } = settings;
 
   const templateTags = utils.getTags('template');
@@ -63,11 +62,13 @@ export default iterateJsdoc(({
 
   const checkTemplateTags = () => {
     for (const tag of templateTags) {
-      const {name} = tag;
-      const names = name.split(/,\s*/);
-      for (const name of names) {
-        if (!usedNames.has(name)) {
-          report(`@template ${name} not in use`, null, tag);
+      const {
+        name,
+      } = tag;
+      const names = name.split(/,\s*/u);
+      for (const nme of names) {
+        if (!usedNames.has(nme)) {
+          report(`@template ${nme} not in use`, null, tag);
         }
       }
     }
@@ -82,10 +83,19 @@ export default iterateJsdoc(({
    */
   const checkParameters = (aliasDeclaration, checkParamsAndReturns) => {
     /* c8 ignore next -- Guard */
-    const {params} = aliasDeclaration.typeParameters ?? {params: []};
-    for (const {name: {name}} of params) {
+    const {
+      params,
+    } = aliasDeclaration.typeParameters ?? {
+      params: [],
+    };
+    for (const {
+      name: {
+        name,
+      },
+    } of params) {
       usedNames.add(name);
     }
+
     if (checkParamsAndReturns) {
       checkParamsAndReturnsTags();
     }
@@ -100,28 +110,30 @@ export default iterateJsdoc(({
     if (!nde) {
       return;
     }
+
     switch (nde.type) {
-    case 'ExportDefaultDeclaration':
-    case 'ExportNamedDeclaration':
-      switch (nde.declaration?.type) {
-        case 'FunctionDeclaration':
-          checkParameters(nde.declaration, true);
-          break;
-        case 'ClassDeclaration':
-        case 'TSTypeAliasDeclaration':
-        case 'TSInterfaceDeclaration':
-          checkParameters(nde.declaration);
-          break;
-      }
-      break;
-    case 'FunctionDeclaration':
-      checkParameters(nde, true);
-      break;
-    case 'ClassDeclaration':
-    case 'TSTypeAliasDeclaration':
-    case 'TSInterfaceDeclaration':
-      checkParameters(nde);
-      break;
+      case 'ClassDeclaration':
+      case 'TSInterfaceDeclaration':
+      case 'TSTypeAliasDeclaration':
+        checkParameters(nde);
+        break;
+      case 'ExportDefaultDeclaration':
+      case 'ExportNamedDeclaration':
+        switch (nde.declaration?.type) {
+          case 'ClassDeclaration':
+          case 'TSInterfaceDeclaration':
+          case 'TSTypeAliasDeclaration':
+            checkParameters(nde.declaration);
+            break;
+          case 'FunctionDeclaration':
+            checkParameters(nde.declaration, true);
+            break;
+        }
+
+        break;
+      case 'FunctionDeclaration':
+        checkParameters(nde, true);
+        break;
     }
   };
 
@@ -151,11 +163,13 @@ export default iterateJsdoc(({
   }
 
   for (const tag of templateTags) {
-    const {name} = tag;
-    const names = name.split(/,\s*/);
-    for (const name of names) {
-      if (!usedNames.has(name)) {
-        report(`@template ${name} not in use`, null, tag);
+    const {
+      name,
+    } = tag;
+    const names = name.split(/,\s*/u);
+    for (const nme of names) {
+      if (!usedNames.has(nme)) {
+        report(`@template ${nme} not in use`, null, tag);
       }
     }
   }

package/src/rules/checkTypes.js

@@ -89,12 +89,12 @@ const getMessage = (upperCase) => {
 };
 
 export default iterateJsdoc(({
+  context,
   jsdocNode,
-  sourceCode,
   report,
-  utils,
   settings,
-  context,
+  sourceCode,
+  utils,
 }) => {
   const jsdocTagsWithPossibleType = utils.filterTags((tag) => {
     return Boolean(utils.tagMightHaveTypePosition(tag.tag));
@@ -109,9 +109,9 @@ export default iterateJsdoc(({
      * }}
      */
     {
+      mode,
       preferredTypes: preferredTypesOriginal,
       structuredTags,
-      mode,
     } = settings;
 
   const injectObjectPreferredTypes = !('Object' in preferredTypesOriginal ||
@@ -177,9 +177,9 @@ export default iterateJsdoc(({
      *   })[]
      * }}
      */ {
+      exemptTagContexts = [],
       noDefaults,
       unifyParentAndChildTypeChecks,
-      exemptTagContexts = [],
     } = context.options[0] || {};
 
   /**
@@ -415,8 +415,8 @@ export default iterateJsdoc(({
     }
 
     const {
-      tag: tagName,
       name: nameInTag,
+      tag: tagName,
     } = jsdocTag;
 
     traverse(typeAst, (node, parentNode, property) => {
@@ -428,7 +428,7 @@ export default iterateJsdoc(({
          * @type {import('jsdoc-type-pratt-parser').NameResult}
          */ (node);
       if (![
-        'JsdocTypeName', 'JsdocTypeAny',
+        'JsdocTypeAny', 'JsdocTypeName',
       ].includes(type)) {
         return;
       }

package/src/rules/checkValues.js

@@ -1,12 +1,9 @@
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
+import iterateJsdoc from '../iterateJsdoc.js';
+import {
+  parseImportsExports,
+} from 'parse-imports-exports';
 import semver from 'semver';
 import spdxExpressionParse from 'spdx-expression-parse';
-import {parseImportsExports} from 'parse-imports-exports';
-import iterateJsdoc from '../iterateJsdoc.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const allowedKinds = new Set([
   'class',
@@ -23,17 +20,17 @@ const allowedKinds = new Set([
 ]);
 
 export default iterateJsdoc(({
-  utils,
-  report,
   context,
+  report,
   settings,
+  utils,
 }) => {
   const options = context.options[0] || {};
   const {
-    allowedLicenses = null,
     allowedAuthors = null,
-    numericOnlyVariation = false,
+    allowedLicenses = null,
     licensePattern = '/([^\n\r]*)/gu',
+    numericOnlyVariation = false,
   } = options;
 
   utils.forEachPreferredTag('version', (jsdocParameter, targetTagName) => {
@@ -167,18 +164,20 @@ export default iterateJsdoc(({
   if (settings.mode === 'typescript') {
     utils.forEachPreferredTag('import', (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());
 
       if (importsExports.errors) {
         report(
-          `Bad @import tag`,
+          'Bad @import tag',
           null,
           tag,
         );