eslint-plugin-jsdoc 50.6.16 → 50.7.0

package/src/index.js

@@ -1,3 +1,6 @@
+import {
+  getJsdocProcessorPlugin,
+} from './getJsdocProcessorPlugin.js';
 import checkAccess from './rules/checkAccess.js';
 import checkAlignment from './rules/checkAlignment.js';
 import checkExamples from './rules/checkExamples.js';
@@ -56,17 +59,18 @@ import tagLines from './rules/tagLines.js';
 import textEscaping from './rules/textEscaping.js';
 import validTypes from './rules/validTypes.js';
 
-import { getJsdocProcessorPlugin } from './getJsdocProcessorPlugin.js';
-
+/* eslint-disable jsdoc/valid-types -- Bug */
 /**
  * @typedef {"recommended" | "stylistic" | "contents" | "logical" | "requirements"} ConfigGroups
  * @typedef {"" | "-typescript" | "-typescript-flavor"} ConfigVariants
  * @typedef {"" | "-error"} ErrorLevelVariants
  * @type {import('eslint').ESLint.Plugin & {
-*   configs: Record<`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`, import('eslint').Linter.Config>
-* }}
-*/
+ *   configs: Record<`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
+ *   import('eslint').Linter.Config>
+ * }}
+ */
 const index = {
+  /* eslint-enable jsdoc/valid-types -- Bug */
   // @ts-expect-error Ok
   configs: {},
   rules: {
@@ -137,7 +141,9 @@ const index = {
  */
 const createRecommendedRuleset = (warnOrError, flatName) => {
   return {
-    ...(flatName ? {name: 'jsdoc/' + flatName} : {}),
+    ...(flatName ? {
+      name: 'jsdoc/' + flatName,
+    } : {}),
     // @ts-expect-error Ok
     plugins:
       flatName ? {
@@ -219,7 +225,7 @@ const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
     ...ruleset,
     rules: {
       ...ruleset.rules,
-      /* eslint-disable indent -- Extra indent to avoid use by auto-rule-editing */
+      /* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
         'jsdoc/check-tag-names': [
           warnOrError, {
             typed: true,
@@ -230,7 +236,7 @@ const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
         'jsdoc/require-param-type': 'off',
         'jsdoc/require-property-type': 'off',
         'jsdoc/require-returns-type': 'off',
-      /* eslint-enable indent */
+      /* eslint-enable @stylistic/indent */
     },
   };
 };
@@ -247,9 +253,9 @@ const createRecommendedTypeScriptFlavorRuleset = (warnOrError, flatName) => {
     ...ruleset,
     rules: {
       ...ruleset.rules,
-      /* eslint-disable indent -- Extra indent to avoid use by auto-rule-editing */
+      /* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
         'jsdoc/no-undefined-types': 'off',
-      /* eslint-enable indent */
+      /* eslint-enable @stylistic/indent */
     },
   };
 };
@@ -266,26 +272,39 @@ const createStandaloneRulesetFactory = (ruleNames) => {
   return (warnOrError, flatName) => {
     return {
       name: 'jsdoc/' + flatName,
-      plugins: { jsdoc: index },
+      plugins: {
+        jsdoc: index,
+      },
       rules: Object.fromEntries(
         ruleNames.map(
-          ruleName =>
-            typeof ruleName === "string"
-              ? [ruleName, warnOrError]
-              : [ruleName[0], [warnOrError, ...ruleName.slice(1)]]
-        )
+          (ruleName) => {
+            return (typeof ruleName === 'string' ?
+              [
+                ruleName, warnOrError,
+              ] :
+              [
+                ruleName[0], [
+                  warnOrError, ...ruleName.slice(1),
+                ],
+              ]);
+          },
+        ),
       ),
     };
   };
-}
+};
 
 const contentsRules = [
   'jsdoc/informative-docs',
   'jsdoc/match-description',
   'jsdoc/no-blank-block-descriptions',
   'jsdoc/no-blank-blocks',
-  ['jsdoc/text-escaping', { escapeHTML: true }]
-]
+  [
+    'jsdoc/text-escaping', {
+      escapeHTML: true,
+    },
+  ],
+];
 
 const createContentsTypescriptRuleset = createStandaloneRulesetFactory(contentsRules);
 
@@ -346,7 +365,9 @@ const stylisticRules = [
   'jsdoc/multiline-blocks',
   'jsdoc/no-multi-asterisks',
   'jsdoc/require-asterisk-prefix',
-  ['jsdoc/require-hyphen-before-param-description', 'never'],
+  [
+    'jsdoc/require-hyphen-before-param-description', 'never',
+  ],
   'jsdoc/tag-lines',
 ];
 
@@ -392,16 +413,20 @@ index.configs['flat/stylistic-typescript-flavor-error'] = createStylisticTypeScr
 
 index.configs.examples = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
   {
+    files: [
+      '**/*.js',
+    ],
     name: 'jsdoc/examples/processor',
-    files: ['**/*.js'],
     plugins: {
-      examples: getJsdocProcessorPlugin()
+      examples: getJsdocProcessorPlugin(),
     },
     processor: 'examples/examples',
   },
   {
+    files: [
+      '**/*.md/*.js',
+    ],
     name: 'jsdoc/examples/rules',
-    files: ['**/*.md/*.js'],
     rules: {
       // "always" newline rule at end unlikely in sample code
       'eol-last': 0,
@@ -436,26 +461,30 @@ index.configs.examples = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
 
       // Can generally look nicer to pad a little even if code imposes more stringency
       'padded-blocks': 0,
-    }
-  }
+    },
+  },
 ]);
 
 index.configs['default-expressions'] = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
   {
-    files: ['**/*.js'],
+    files: [
+      '**/*.js',
+    ],
     name: 'jsdoc/default-expressions/processor',
     plugins: {
       examples: getJsdocProcessorPlugin({
         checkDefaults: true,
         checkParams: true,
-        checkProperties: true
-      })
+        checkProperties: true,
+      }),
     },
-    processor: 'examples/examples'
+    processor: 'examples/examples',
   },
   {
+    files: [
+      '**/*.jsdoc-defaults', '**/*.jsdoc-params', '**/*.jsdoc-properties',
+    ],
     name: 'jsdoc/default-expressions/rules',
-    files: ['**/*.jsdoc-defaults', '**/*.jsdoc-params', '**/*.jsdoc-properties'],
     rules: {
       ...index.configs.examples[1].rules,
       'chai-friendly/no-unused-expressions': 0,
@@ -468,9 +497,9 @@ index.configs['default-expressions'] = /** @type {import('eslint').Linter.FlatCo
       semi: [
         'error', 'never',
       ],
-      strict: 0
+      strict: 0,
     },
-  }
+  },
 ]);
 
 index.configs['examples-and-default-expressions'] = /** @type {import('eslint').Linter.FlatConfig[]} */ ([
@@ -480,22 +509,22 @@ index.configs['examples-and-default-expressions'] = /** @type {import('eslint').
       examples: getJsdocProcessorPlugin({
         checkDefaults: true,
         checkParams: true,
-        checkProperties: true
-      })
+        checkProperties: true,
+      }),
     },
   },
   ...index.configs.examples.map((config) => {
     return {
       ...config,
-      plugins: {}
+      plugins: {},
     };
   }),
   ...index.configs['default-expressions'].map((config) => {
     return {
       ...config,
-      plugins: {}
+      plugins: {},
     };
-  })
+  }),
 ]);
 
 export default index;

package/src/iterateJsdoc.js

@@ -594,8 +594,8 @@ const globalState = new Map();
  * @returns {BasicUtils}
  */
 const getBasicUtils = (context, {
-  tagNamePreference,
   mode,
+  tagNamePreference,
 }) => {
   /** @type {BasicUtils} */
   const utils = {};
@@ -706,23 +706,23 @@ const getUtils = (
   const utils = /** @type {Utils} */ (getBasicUtils(context, settings));
 
   const {
-    tagNamePreference,
-    overrideReplacesDocs,
+    augmentsExtendsReplacesDocs,
     ignoreReplacesDocs,
     implementsReplacesDocs,
-    augmentsExtendsReplacesDocs,
     maxLines,
     minLines,
     mode,
+    overrideReplacesDocs,
+    tagNamePreference,
   } = settings;
 
   /** @type {IsIteratingFunction} */
   utils.isIteratingFunction = () => {
     return !iteratingAll || [
-      'MethodDefinition',
       'ArrowFunctionExpression',
       'FunctionDeclaration',
       'FunctionExpression',
+      'MethodDefinition',
     ].includes(String(node && node.type));
   };
 
@@ -815,8 +815,8 @@ const getUtils = (
     jsdoc.source.some(({
       tokens: {
         description,
-        tag,
         end,
+        tag,
       },
     }, idx) => {
       if (tag) {
@@ -870,12 +870,12 @@ const getUtils = (
 
     jsdoc.source.some(({
       tokens: {
-        description,
-        start,
         delimiter,
+        description,
+        end,
         postDelimiter,
+        start,
         tag,
-        end,
       },
     }, idx) => {
       if (delimiter === '/**') {
@@ -927,8 +927,8 @@ const getUtils = (
     jsdoc.source.some(({
       tokens: {
         description,
-        tag,
         end,
+        tag,
       },
     }, idx) => {
       /* c8 ignore next 3 -- Already checked */
@@ -1003,8 +1003,8 @@ const getUtils = (
         let spliceCount = 1;
         tagSource.slice(tagIdx + 1).some(({
           tokens: {
-            tag,
             end: ending,
+            tag,
           },
         }) => {
           if (!tag && !ending) {
@@ -1058,7 +1058,8 @@ const getUtils = (
 
         return true;
       }
-      /* c8 ignore next */
+      /* c8 ignore next 2 */
+      // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
       return false;
     });
     for (const [
@@ -1211,7 +1212,8 @@ const getUtils = (
 
         return true;
       }
-      /* c8 ignore next */
+      /* c8 ignore next 2 */
+      // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8
       return false;
     });
 
@@ -1233,11 +1235,11 @@ const getUtils = (
       ],
     } = jsdoc;
     const {
-      postDelimiter,
       description,
       lineEnd,
-      tag,
       name,
+      postDelimiter,
+      tag,
       type,
     } = tokens;
 
@@ -1308,7 +1310,7 @@ const getUtils = (
        */ (node).generator ||
       node.type === 'MethodDefinition' && node.value.generator ||
       [
-        'ExportNamedDeclaration', 'ExportDefaultDeclaration',
+        'ExportDefaultDeclaration', 'ExportNamedDeclaration',
       ].includes(node.type) &&
       /** @type {import('estree').FunctionDeclaration} */
       (
@@ -1342,8 +1344,11 @@ const getUtils = (
     return jsdocUtils.getPreferredTagName(
       jsdoc, {
         ...args,
-        context, mode, report, tagNamePreference,
-      }
+        context,
+        mode,
+        report,
+        tagNamePreference,
+      },
     );
   };
 
@@ -1536,7 +1541,7 @@ const getUtils = (
   /** @type {HasYieldValue} */
   utils.hasYieldValue = () => {
     if ([
-      'ExportNamedDeclaration', 'ExportDefaultDeclaration',
+      'ExportDefaultDeclaration', 'ExportNamedDeclaration',
     ].includes(/** @type {Node} */ (node).type)) {
       return jsdocUtils.hasYieldValue(
         /** @type {import('estree').Declaration|import('estree').Expression} */ (
@@ -1647,9 +1652,12 @@ const getUtils = (
   utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
     return jsdocUtils.forEachPreferredTag(
       jsdoc, tagName, arrayHandler, {
+        context,
+        mode,
+        report,
         skipReportingBlockedTag,
-        context, mode, report, tagNamePreference
-      }
+        tagNamePreference,
+      },
     );
   };
 
@@ -1722,11 +1730,34 @@ const getUtils = (
  */
 
 /**
- * @param {import('eslint').Rule.RuleContext} context
+ * @typedef {{
+ *   settings?: {
+ *     jsdoc?: {
+ *       ignorePrivate: boolean,
+ *       ignoreInternal: boolean,
+ *       maxLines: Integer,
+ *       minLines: Integer,
+ *       tagNamePreference: import('./jsdocUtils.js').TagNamePreference,
+ *       preferredTypes: PreferredTypes,
+ *       structuredTags: StructuredTags,
+ *       overrideReplacesDocs: boolean,
+ *       ignoreReplacesDocs: boolean,
+ *       implementsReplacesDocs: boolean,
+ *       augmentsExtendsReplacesDocs: boolean,
+ *       exemptDestructuredRootsFromChecks: boolean,
+ *       mode: import('./jsdocUtils.js').ParserMode,
+ *       contexts: Context[],
+ *     }
+ *   }
+ * }} JSDocSettings
+ */
+
+/**
+ * @param {import('eslint').Rule.RuleContext & JSDocSettings} context
  * @returns {Settings|false}
  */
 const getSettings = (context) => {
-  /* dslint-disable canonical/sort-keys */
+  /* eslint-disable perfectionist/sort-objects */
   const settings = {
     // All rules
     ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),
@@ -1759,7 +1790,7 @@ const getSettings = (context) => {
     // Many rules
     contexts: context.settings.jsdoc?.contexts,
   };
-  /* dslint-enable canonical/sort-keys */
+  /* eslint-enable perfectionist/sort-objects */
 
   jsdocUtils.setTagStructure(settings.mode);
   try {
@@ -1822,7 +1853,6 @@ const makeReport = (context, commentNode) => {
         },
       };
 
-      // Todo: Remove ignore once `check-examples` can be restored for ESLint 8+
       if ('column' in jsdocLoc && typeof jsdocLoc.column === 'number') {
         const colNumber = /** @type {import('eslint').AST.SourceLocation} */ (
           commentNode.loc
@@ -2189,7 +2219,6 @@ const iterateAllJsdocs = (iterator, ruleConfig, contexts, additiveCommentContext
   };
 
   return {
-    // @ts-expect-error ESLint accepts
     create (context) {
       /* c8 ignore next -- Fallback to deprecated method */
       const {
@@ -2302,7 +2331,7 @@ const checkFile = (iterator, ruleConfig) => {
 export {
   getSettings,
   // dslint-disable-next-line unicorn/prefer-export-from -- Avoid experimental parser
-  parseComment,
+
 };
 
 /**
@@ -2313,7 +2342,7 @@ export {
 export default function iterateJsdoc (iterator, ruleConfig) {
   const metaType = ruleConfig?.meta?.type;
   if (!metaType || ![
-    'problem', 'suggestion', 'layout',
+    'layout', 'problem', 'suggestion',
   ].includes(metaType)) {
     throw new TypeError('Rule must include `meta.type` option (with value "problem", "suggestion", or "layout")');
   }
@@ -2483,3 +2512,7 @@ export default function iterateJsdoc (iterator, ruleConfig) {
     meta: ruleConfig.meta,
   };
 }
+
+export {
+  parseComment,
+} from '@es-joy/jsdoccomment';