eslint-plugin-jsdoc 48.8.3 → 48.9.0

package/src/iterateJsdoc.js

@@ -1,4 +1,4 @@
-import jsdocUtils from './jsdocUtils.js';
+import * as jsdocUtils from './jsdocUtils.js';
 import {
   commentHandler,
   getJSDocComment,
@@ -628,11 +628,11 @@ const getBasicUtils = (context, {
   utils.getPreferredTagNameObject = ({
     tagName,
   }) => {
-    const ret = jsdocUtils.getPreferredTagName(
-      context,
-      /** @type {import('./jsdocUtils.js').ParserMode} */ (mode),
+    const ret = jsdocUtils.getPreferredTagNameSimple(
       tagName,
+      /** @type {import('./jsdocUtils.js').ParserMode} */ (mode),
       tagNamePreference,
+      context,
     );
     const isObject = ret && typeof ret === 'object';
     if (ret === false || (isObject && !ret.replacement)) {
@@ -783,44 +783,7 @@ const getUtils = (
 
   /** @type {GetTagDescription} */
   utils.getTagDescription = (tg, returnArray) => {
-    /**
-     * @type {string[]}
-     */
-    const descriptions = [];
-    tg.source.some(({
-      tokens: {
-        end,
-        lineEnd,
-        postDelimiter,
-        tag,
-        postTag,
-        name,
-        type,
-        description,
-      },
-    }) => {
-      const desc = (
-        tag && postTag ||
-        !tag && !name && !type && postDelimiter || ''
-
-      // Remove space
-      ).slice(1) +
-        (description || '') + (lineEnd || '');
-
-      if (end) {
-        if (desc) {
-          descriptions.push(desc);
-        }
-
-        return true;
-      }
-
-      descriptions.push(desc);
-
-      return false;
-    });
-
-    return returnArray ? descriptions : descriptions.join('\n');
+    return jsdocUtils.getTagDescription(tg, returnArray);
   };
 
   /** @type {SetTagDescription} */
@@ -1375,29 +1338,13 @@ const getUtils = (
   };
 
   /** @type {GetPreferredTagName} */
-  utils.getPreferredTagName = ({
-    tagName,
-    skipReportingBlockedTag = false,
-    allowObjectReturn = false,
-    defaultMessage = `Unexpected tag \`@${tagName}\``,
-  }) => {
-    const ret = jsdocUtils.getPreferredTagName(context, mode, tagName, tagNamePreference);
-    const isObject = ret && typeof ret === 'object';
-    if (utils.hasTag(tagName) && (ret === false || isObject && !ret.replacement)) {
-      if (skipReportingBlockedTag) {
-        return {
-          blocked: true,
-          tagName,
-        };
+  utils.getPreferredTagName = (args) => {
+    return jsdocUtils.getPreferredTagName(
+      jsdoc, {
+        ...args,
+        context, mode, report, tagNamePreference,
       }
-
-      const message = isObject && ret.message || defaultMessage;
-      report(message, null, utils.getTags(tagName)[0]);
-
-      return false;
-    }
-
-    return isObject && !allowObjectReturn ? ret.replacement : ret;
+    );
   };
 
   /** @type {IsValidTag} */
@@ -1619,21 +1566,19 @@ const getUtils = (
 
   /** @type {GetTags} */
   utils.getTags = (tagName) => {
-    return utils.filterTags((item) => {
-      return item.tag === tagName;
-    });
+    return jsdocUtils.getTags(jsdoc, tagName);
   };
 
   /** @type {GetPresentTags} */
   utils.getPresentTags = (tagList) => {
-    return utils.filterTags((tag) => {
+    return jsdocUtils.filterTags(jsdoc, (tag) => {
       return tagList.includes(tag.tag);
     });
   };
 
   /** @type {FilterTags} */
   utils.filterTags = (filter) => {
-    return jsdoc.tags.filter((tag) => {
+    return jsdocUtils.filterTags(jsdoc, (tag) => {
       return filter(tag);
     });
   };
@@ -1699,34 +1644,13 @@ const getUtils = (
   };
 
   /** @type {ForEachPreferredTag} */
-  utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag = false) => {
-    const targetTagName = /** @type {string|false} */ (
-      utils.getPreferredTagName({
+  utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {
+    return jsdocUtils.forEachPreferredTag(
+      jsdoc, tagName, arrayHandler, {
         skipReportingBlockedTag,
-        tagName,
-      })
+        context, mode, report, tagNamePreference
+      }
     );
-    if (!targetTagName ||
-      skipReportingBlockedTag && targetTagName && typeof targetTagName === 'object'
-    ) {
-      return;
-    }
-
-    const matchingJsdocTags = jsdoc.tags.filter(({
-      tag,
-    }) => {
-      return tag === targetTagName;
-    });
-
-    for (const matchingJsdocTag of matchingJsdocTags) {
-      arrayHandler(
-        /**
-         * @type {import('@es-joy/jsdoccomment').JsdocTagWithInline}
-         */ (
-          matchingJsdocTag
-        ), targetTagName,
-      );
-    }
   };
 
   /** @type {FindContext} */
@@ -2030,8 +1954,8 @@ const iterate = (
     !ruleConfig.checkPrivate && settings.ignorePrivate &&
     (
       utils.hasTag('private') ||
-      jsdoc.tags
-        .filter(({
+      jsdocUtils
+        .filterTags(jsdoc, ({
           tag,
         }) => {
           return tag === 'access';

package/src/jsdocUtils.js

@@ -521,7 +521,7 @@ const modeWarnSettings = WarnSettings();
 
 /**
  * @param {ParserMode|undefined} mode
- * @param {import('eslint').Rule.RuleContext} context
+ * @param {Reporter} context
  * @returns {import('./tagNames.js').AliasedTags}
  */
 const getTagNamesForMode = (mode, context) => {
@@ -556,20 +556,76 @@ const getTagNamesForMode = (mode, context) => {
 };
 
 /**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode|undefined} mode
+ * @param {import('comment-parser').Spec} tg
+ * @param {boolean} [returnArray]
+ * @returns {string[]|string}
+ */
+const getTagDescription = (tg, returnArray) => {
+    /**
+     * @type {string[]}
+     */
+    const descriptions = [];
+    tg.source.some(({
+      tokens: {
+        end,
+        lineEnd,
+        postDelimiter,
+        tag,
+        postTag,
+        name,
+        type,
+        description,
+      },
+    }) => {
+      const desc = (
+        tag && postTag ||
+        !tag && !name && !type && postDelimiter || ''
+
+      // Remove space
+      ).slice(1) +
+        (description || '') + (lineEnd || '');
+
+      if (end) {
+        if (desc) {
+          descriptions.push(desc);
+        }
+
+        return true;
+      }
+
+      descriptions.push(desc);
+
+      return false;
+    });
+
+    return returnArray ? descriptions : descriptions.join('\n');
+};
+
+/**
+ * @typedef {{
+ *   report: (descriptor: import('eslint').Rule.ReportDescriptor) => void
+ * }} Reporter
+ */
+
+/**
  * @param {string} name
+ * @param {ParserMode|undefined} mode
  * @param {TagNamePreference} tagPreference
+ * @param {Reporter} context
  * @returns {string|false|{
  *   message: string;
  *   replacement?: string|undefined;
  * }}
  */
-const getPreferredTagName = (
-  context,
-  mode,
+const getPreferredTagNameSimple = (
   name,
+  mode,
   tagPreference = {},
+  context = {
+    report () {
+      // No-op
+    }
+  },
 ) => {
   const prefValues = Object.values(tagPreference);
   if (prefValues.includes(name) || prefValues.some((prefVal) => {
@@ -649,6 +705,129 @@ const hasTag = (jsdoc, targetTagName) => {
   });
 };
 
+/**
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
+ * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
+ */
+const filterTags = (jsdoc, filter) => {
+  return jsdoc.tags.filter((tag) => {
+    return filter(tag);
+  });
+};
+
+/**
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @param {string} tagName
+ * @returns {import('comment-parser').Spec[]}
+ */
+const getTags = (jsdoc, tagName) => {
+  return filterTags(jsdoc, (item) => {
+    return item.tag === tagName;
+  });
+};
+
+/**
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @param {{
+ *   tagName: string,
+ *   context?: import('eslint').Rule.RuleContext,
+ *   mode?: ParserMode,
+ *   report?: import('./iterateJsdoc.js').Report
+ *   tagNamePreference?: TagNamePreference
+ *   skipReportingBlockedTag?: boolean,
+ *   allowObjectReturn?: boolean,
+ *   defaultMessage?: string,
+ * }} cfg
+ * @returns {string|undefined|false|{
+ *   message: string;
+ *   replacement?: string|undefined;
+ * }|{
+ *   blocked: true,
+ *   tagName: string
+ * }}
+ */
+const getPreferredTagName = (jsdoc, {
+  tagName,
+  context, mode,
+  tagNamePreference,
+  report = () => {},
+  skipReportingBlockedTag = false,
+  allowObjectReturn = false,
+  defaultMessage = `Unexpected tag \`@${tagName}\``,
+}) => {
+  const ret = getPreferredTagNameSimple(tagName, mode, tagNamePreference, context);
+  const isObject = ret && typeof ret === 'object';
+  if (hasTag(jsdoc, tagName) && (ret === false || isObject && !ret.replacement)) {
+    if (skipReportingBlockedTag) {
+      return {
+        blocked: true,
+        tagName,
+      };
+    }
+
+    const message = isObject && ret.message || defaultMessage;
+    report(message, null, getTags(jsdoc, tagName)[0]);
+
+    return false;
+  }
+
+  return isObject && !allowObjectReturn ? ret.replacement : ret;
+};
+
+/**
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
+ * @param {string} tagName
+ * @param {(
+ *   matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,
+ *   targetTagName: string
+ * ) => void} arrayHandler
+ * @param {object} cfg
+ * @param {import('eslint').Rule.RuleContext} [cfg.context]
+ * @param {ParserMode} [cfg.mode]
+ * @param {import('./iterateJsdoc.js').Report} [cfg.report]
+ * @param {TagNamePreference} [cfg.tagNamePreference]
+ * @param {boolean} [cfg.skipReportingBlockedTag]
+ * @returns {void}
+ */
+const forEachPreferredTag = (
+  jsdoc, tagName, arrayHandler,
+  {
+    context, mode, report,
+    tagNamePreference,
+    skipReportingBlockedTag = false,
+  } = {}
+) => {
+  const targetTagName = /** @type {string|false} */ (
+    getPreferredTagName(jsdoc, {
+      skipReportingBlockedTag,
+      tagName,
+      context, mode, report, tagNamePreference
+    })
+  );
+  if (!targetTagName ||
+    skipReportingBlockedTag && targetTagName && typeof targetTagName === 'object'
+  ) {
+    return;
+  }
+
+  const matchingJsdocTags = jsdoc.tags.filter(({
+    tag,
+  }) => {
+    return tag === targetTagName;
+  });
+
+  for (const matchingJsdocTag of matchingJsdocTags) {
+    arrayHandler(
+      /**
+       * @type {import('@es-joy/jsdoccomment').JsdocTagWithInline}
+       */ (
+        matchingJsdocTag
+      ), targetTagName,
+    );
+  }
+};
+
 /**
  * Get all tags, inline tags and inline tags in tags
  * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
@@ -1652,19 +1831,24 @@ const getRegexFromString = (regexString, requiredFlags) => {
   return new RegExp(regex, flags);
 };
 
-export default {
+export {
   comparePaths,
   dropPathSegmentQuotes,
   enforcedContexts,
   exemptSpeciaMethods,
+  filterTags,
   flattenRoots,
+  forEachPreferredTag,
   getAllTags,
   getContextObject,
   getFunctionParameterNames,
   getIndent,
   getJsdocTagsDeep,
   getPreferredTagName,
+  getPreferredTagNameSimple,
   getRegexFromString,
+  getTagDescription,
+  getTags,
   getTagsByType,
   getTagStructureForMode,
   hasATag,

package/src/rules/convertToJsdocComments.js

@@ -2,7 +2,11 @@ import iterateJsdoc from '../iterateJsdoc.js';
 import {
   getSettings,
 } from '../iterateJsdoc.js';
-import jsdocUtils from '../jsdocUtils.js';
+import {
+  getIndent,
+  getContextObject,
+  enforcedContexts,
+} from '../jsdocUtils.js';
 import {
   getNonJsdocComment,
   getDecorator,
@@ -114,7 +118,7 @@ export default {
           );
         }
 
-        const indent = jsdocUtils.getIndent({
+        const indent = getIndent({
           text: sourceCode.getText(
             /** @type {import('eslint').Rule.Node} */ (baseNode),
             /** @type {import('eslint').AST.SourceLocation} */
@@ -255,17 +259,17 @@ export default {
 
     // Todo: add contexts to check after (and handle if want both before and after)
     return {
-      ...jsdocUtils.getContextObject(
-        jsdocUtils.enforcedContexts(context, true, settings),
+      ...getContextObject(
+        enforcedContexts(context, true, settings),
         checkNonJsdoc,
       ),
-      ...jsdocUtils.getContextObject(
+      ...getContextObject(
         contextsAfter,
         (_info, _handler, node) => {
           checkNonJsdocAfter(node, contextsAfter);
         },
       ),
-      ...jsdocUtils.getContextObject(
+      ...getContextObject(
         contextsBeforeAndAfter,
         (_info, _handler, node) => {
           checkNonJsdoc({}, null, node);

package/src/rules/requireJsdoc.js

@@ -2,7 +2,15 @@ import exportParser from '../exportParser.js';
 import {
   getSettings,
 } from '../iterateJsdoc.js';
-import jsdocUtils from '../jsdocUtils.js';
+import {
+  exemptSpeciaMethods,
+  isConstructor,
+  getFunctionParameterNames,
+  hasReturnValue,
+  getIndent,
+  getContextObject,
+  enforcedContexts,
+} from '../jsdocUtils.js';
 import {
   getDecorator,
   getJSDocComment,
@@ -381,7 +389,7 @@ export default {
 
       // For those who have options configured against ANY constructors (or
       //  setters or getters) being reported
-      if (jsdocUtils.exemptSpeciaMethods(
+      if (exemptSpeciaMethods(
         {
           description: '',
           inlineTags: [],
@@ -405,10 +413,10 @@ export default {
 
         // Avoid reporting  param-less, return-less constructor methods (when
         //  `exemptEmptyConstructors` option is set)
-        exemptEmptyConstructors && jsdocUtils.isConstructor(node)
+        exemptEmptyConstructors && isConstructor(node)
       ) {
-        const functionParameterNames = jsdocUtils.getFunctionParameterNames(node);
-        if (!functionParameterNames.length && !jsdocUtils.hasReturnValue(node)) {
+        const functionParameterNames = getFunctionParameterNames(node);
+        if (!functionParameterNames.length && !hasReturnValue(node)) {
           return;
         }
       }
@@ -427,7 +435,7 @@ export default {
           baseNode = decorator;
         }
 
-        const indent = jsdocUtils.getIndent({
+        const indent = getIndent({
           text: sourceCode.getText(
             /** @type {import('eslint').Rule.Node} */ (baseNode),
             /** @type {import('eslint').AST.SourceLocation} */
@@ -516,8 +524,8 @@ export default {
     };
 
     return {
-      ...jsdocUtils.getContextObject(
-        jsdocUtils.enforcedContexts(context, [], settings),
+      ...getContextObject(
+        enforcedContexts(context, [], settings),
         checkJsDoc,
       ),
       ArrowFunctionExpression (node) {