eslint-plugin-jsdoc 44.2.2 → 44.2.3

package/dist/jsdocUtils.js

@@ -10,22 +10,53 @@ var _getDefaultTagStructureForMode = _interopRequireDefault(require("./getDefaul
 var _tagNames = require("./tagNames");
 var _hasReturnValue = require("./utils/hasReturnValue");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
-/* eslint-disable jsdoc/no-undefined-types */
-
 /**
- * @typedef {"jsdoc"|"typescript"|"closure"} ParserMode
+ * @typedef {number} Integer
+ */
+/**
+ * @typedef {import('./utils/hasReturnValue.js').ESTreeOrTypeScriptNode} ESTreeOrTypeScriptNode
  */
 
+/**
+ * @typedef {"jsdoc"|"typescript"|"closure"|"permissive"} ParserMode
+ */
+/**
+ * @type {import('./getDefaultTagStructureForMode.js').TagStructure}
+ */
 let tagStructure;
+
+/**
+ * @param {ParserMode} mode
+ * @returns {void}
+ */
 const setTagStructure = mode => {
   tagStructure = (0, _getDefaultTagStructureForMode.default)(mode);
 };
 
-// Given a nested array of property names, reduce them to a single array,
-// appending the name of the root element along the way if present.
+/**
+ * @typedef {{
+ *   hasPropertyRest: boolean,
+ *   hasRestElement: boolean,
+ *   names: string[],
+ *   rests: boolean[],
+ * }} FlattendRootInfo
+ */
+
+/**
+ * Given a nested array of property names, reduce them to a single array,
+ *   appending the name of the root element along the way if present.
+ *
+ * @param {} params
+ * @param {string} root
+ * @returns {FlattendRootInfo}
+ */
 const flattenRoots = (params, root = '') => {
   let hasRestElement = false;
   let hasPropertyRest = false;
+
+  /**
+   * @type {boolean[]}
+   */
   const rests = [];
   const names = params.reduce((acc, cur) => {
     if (Array.isArray(cur)) {
@@ -78,7 +109,7 @@ const flattenRoots = (params, root = '') => {
 };
 
 /**
- * @param {object} propSignature
+ * @param {ESTreeOrTypeScriptNode} propSignature
  * @returns {undefined|Array|string}
  */
 const getPropertiesFromPropertySignature = propSignature => {
@@ -94,15 +125,28 @@ const getPropertiesFromPropertySignature = propSignature => {
 };
 
 /**
- * @param {object} functionNode
- * @param {boolean} checkDefaultObjects
+ * @param {ESTreeOrTypeScriptNode} functionNode
+ * @param {boolean} [checkDefaultObjects]
  * @returns {Array}
  */
 const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
   var _functionNode$value;
-  // eslint-disable-next-line complexity
+  /* eslint-disable complexity -- Temporary */
+  /**
+   * @param {} param
+   * @param {boolean} [isProperty]
+   * @returns {undefined|{
+   *   isRestProperty: boolean|undefined,
+   *   name: string,
+   *   restElement: true
+   * }|[undefined|string, FlattendRootInfo|{
+   *   name: Integer,
+   *   restElement: boolean
+   * }[]]}
+   */
   const getParamName = (param, isProperty) => {
     var _param$left, _param$left3;
+    /* eslint-enable complexity -- Temporary */
     const hasLeftTypeAnnotation = 'left' in param && 'typeAnnotation' in param.left;
     if ('typeAnnotation' in param || hasLeftTypeAnnotation) {
       var _typeAnnotation$typeA;
@@ -140,14 +184,14 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
       // eslint-disable-next-line default-case
       switch (param.value.type) {
         case 'ArrayPattern':
-          return [param.key.name, param.value.elements.map((prop, idx) => {
+          return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
             return {
               name: idx,
-              restElement: prop.type === 'RestElement'
+              restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
             };
           })];
         case 'ObjectPattern':
-          return [param.key.name, param.value.properties.map(prop => {
+          return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
             return getParamName(prop, isProperty);
           })];
         case 'AssignmentPattern':
@@ -157,20 +201,20 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
               case 'Identifier':
                 // Default parameter
                 if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-                  return [param.key.name, param.value.right.properties.map(prop => {
+                  return [param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
                     return getParamName(prop, isProperty);
                   })];
                 }
                 break;
               case 'ObjectPattern':
-                return [param.key.name, param.value.left.properties.map(prop => {
+                return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
                   return getParamName(prop, isProperty);
                 })];
               case 'ArrayPattern':
-                return [param.key.name, param.value.left.elements.map((prop, idx) => {
+                return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
                   return {
                     name: idx,
-                    restElement: prop.type === 'RestElement'
+                    restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
                   };
                 })];
             }
@@ -197,7 +241,7 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
     }
     if (param.type === 'ArrayPattern' || ((_param$left3 = param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.type) === 'ArrayPattern') {
       var _param$left4;
-      const elements = param.elements || ((_param$left4 = param.left) === null || _param$left4 === void 0 ? void 0 : _param$left4.elements);
+      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left4 = param.left) === null || _param$left4 === void 0 ? void 0 : _param$left4.elements);
       const roots = elements.map((prop, idx) => {
         return {
           name: `"${idx}"`,
@@ -227,7 +271,7 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
 };
 
 /**
- * @param {Node} functionNode
+ * @param {ESTreeOrTypeScriptNode} functionNode
  * @returns {Integer}
  */
 const hasParams = functionNode => {
@@ -239,9 +283,13 @@ const hasParams = functionNode => {
  * Gets all names of the target type, including those that refer to a path, e.g.
  * "@param foo; @param foo.bar".
  *
- * @param {object} jsdoc
+ * @param {import('comment-parser').Block} jsdoc
  * @param {string} targetTagName
- * @returns {Array<object>}
+ * @returns {{
+ *   idx: Integer,
+ *   name: string,
+ *   type: string
+ * }[]}
  */
 const getJsdocTagsDeep = (jsdoc, targetTagName) => {
   const ret = [];
@@ -264,8 +312,9 @@ const getJsdocTagsDeep = (jsdoc, targetTagName) => {
 const modeWarnSettings = (0, _WarnSettings.default)();
 
 /**
- * @param {string} mode
- * @param context
+ * @param {ParserMode} mode
+ * @param {import('eslint').Rule.RuleContext} context
+ * @returns {import('./tagNames.js').AliasedTags}
  */
 const getTagNamesForMode = (mode, context) => {
   switch (mode) {
@@ -296,11 +345,14 @@ const getTagNamesForMode = (mode, context) => {
 };
 
 /**
- * @param context
+ * @param {import('eslint').Rule.RuleContext} context
  * @param {ParserMode} mode
  * @param {string} name
- * @param {object} tagPreference
- * @returns {string|object}
+ * @param {TagNamePreference} tagPreference
+ * @returns {string|boolean|{
+ *   message: string;
+ *   replacement?: string|undefined;
+ * }}
  */
 const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
   var _Object$entries$find;
@@ -319,7 +371,7 @@ const getPreferredTagName = (context, mode, name, tagPreference = {}) => {
   const tagPreferenceFixed = Object.fromEntries(Object.entries(tagPreference).map(([key, value]) => {
     return [key.replace(/^tag /u, ''), value];
   }));
-  if (Object.prototype.hasOwnProperty.call(tagPreferenceFixed, name)) {
+  if (Object.hasOwn(tagPreferenceFixed, name)) {
     return tagPreferenceFixed[name];
   }
   const tagNames = getTagNamesForMode(mode, context);
@@ -362,18 +414,70 @@ const hasTag = (jsdoc, targetTagName) => {
 /**
  * Get all tags, inline tags and inline tags in tags
  *
- * @param {object} jsdoc
- * @returns {Array}
+ * @param {import('comment-parser').Block & {
+ *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
+ * }} jsdoc
+ * @param {boolean} includeInlineTags
+ * @returns {(import('comment-parser').Spec|
+ *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
 const getAllTags = (jsdoc, includeInlineTags) => {
-  return includeInlineTags ? [...jsdoc.tags, ...jsdoc.inlineTags, ...jsdoc.tags.flatMap(tag => {
-    return tag.inlineTags;
+  return includeInlineTags ? [...jsdoc.tags, ...jsdoc.inlineTags.map(inlineTag => {
+    // Tags don't have source or line numbers, so add before returning
+    let line = -1;
+    for (const {
+      tokens: {
+        description
+      }
+    } of jsdoc.source) {
+      line++;
+      if (description && description.includes(`{@${inlineTag.tag}`)) {
+        break;
+      }
+    }
+    inlineTag.line = line;
+    return inlineTag;
+  }), ...jsdoc.tags.flatMap(tag => {
+    let tagBegins = -1;
+    for (const {
+      tokens: {
+        tag: tg
+      }
+    } of jsdoc.source) {
+      tagBegins++;
+      if (tg) {
+        break;
+      }
+    }
+    for (const inlineTag of tag.inlineTags) {
+      let line;
+      for (const {
+        number,
+        tokens: {
+          description
+        }
+      } of tag.source) {
+        if (description && description.includes(`{@${inlineTag.tag}`)) {
+          line = number;
+          break;
+        }
+      }
+      inlineTag.line = tagBegins + line - 1;
+    }
+    return (
+      /**
+       * @type {import('comment-parser').Spec & {
+       *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
+       * }}
+       */
+      tag.inlineTags
+    );
   })] : jsdoc.tags;
 };
 
 /**
  * @param {object} jsdoc
- * @param {Array} targetTagNames
+ * @param {string[]} targetTagNames
  * @returns {boolean}
  */
 const hasATag = (jsdoc, targetTagNames) => {
@@ -385,9 +489,9 @@ const hasATag = (jsdoc, targetTagNames) => {
 /**
  * Checks if the JSDoc comment has an undefined type.
  *
- * @param {JsDocTag} tag
+ * @param {import('comment-parser').Spec} tag
  *   the tag which should be checked.
- * @param {"jsdoc"|"closure"|"typescript"} mode
+ * @param {ParserMode} mode
  * @returns {boolean}
  *   true in case a defined type is undeclared; otherwise false.
  */
@@ -423,20 +527,34 @@ const mayBeUndefinedTypeTag = (tag, mode) => {
 };
 
 /**
- * @param map
- * @param tag
- * @returns {Map}
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} map
+ * @param {string} tag
+ * @returns {Map<string, string | boolean>}
  */
 const ensureMap = (map, tag) => {
   if (!map.has(tag)) {
     map.set(tag, new Map());
   }
-  return map.get(tag);
+  return (/** @type {Map<string, string | boolean>} */map.get(tag)
+  );
 };
 
+/* eslint-disable jsdoc/valid-types -- Older non-TS version */
+/**
+ * @typedef {{
+ *   [tag: string]: {
+ *     name: string|boolean,
+ *     type: string[]|boolean,
+ *     required: string[]
+ *   }
+ * }} StructuredTags
+ */
+/* eslint-enable jsdoc/valid-types -- Older non-TS version */
+
 /**
- * @param structuredTags
- * @param tagMap
+ * @param {StructuredTags} structuredTags
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {void}
  */
 const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
   for (const [tag, {
@@ -469,9 +587,9 @@ const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
 };
 
 /**
- * @param mode
- * @param structuredTags
- * @returns {Map}
+ * @param {ParserMode} mode
+ * @param {StructuredTags} structuredTags
+ * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
  */
 const getTagStructureForMode = (mode, structuredTags) => {
   const tagStruct = (0, _getDefaultTagStructureForMode.default)(mode);
@@ -484,8 +602,8 @@ const getTagStructureForMode = (mode, structuredTags) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathDefiningTag = (tag, tagMap = tagStructure) => {
@@ -494,8 +612,8 @@ const isNamepathDefiningTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
@@ -504,8 +622,8 @@ const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
@@ -514,8 +632,8 @@ const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
@@ -524,9 +642,9 @@ const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
- * @returns {boolean}
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
+ * @returns {boolean|string}
  */
 const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
   if (tagMustHaveTypePosition(tag, tagMap)) {
@@ -539,8 +657,8 @@ const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
 const namepathTypes = new Set(['namepath-defining', 'namepath-referencing']);
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
@@ -550,8 +668,8 @@ const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
@@ -560,8 +678,8 @@ const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
@@ -571,7 +689,7 @@ const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
 
 /**
  * @param tag
- * @param {Map} tagMap
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
@@ -579,8 +697,8 @@ const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
 };
 
 /**
- * @param tag
- * @param {Map} tagMap
+ * @param {string} tag
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
@@ -590,7 +708,7 @@ const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
 
 /**
  * @param tag
- * @param {Map} tagMap
+ * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
  * @returns {boolean}
  */
 const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
@@ -603,8 +721,14 @@ const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
   return mustHaveEither && !hasEither && !mustHaveTypePosition;
 };
 
-// eslint-disable-next-line complexity
+/* eslint-disable complexity -- Temporary */
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} [checkYieldReturnValue]
+ * @returns {boolean}
+ */
 const hasNonFunctionYield = (node, checkYieldReturnValue) => {
+  /* eslint-enable complexity -- Temporary */
   if (!node) {
     return false;
   }
@@ -754,7 +878,8 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
 /**
  * Checks if a node has a return statement. Void return does not count.
  *
- * @param {object} node
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
 const hasYieldValue = (node, checkYieldReturnValue) => {
@@ -764,8 +889,8 @@ const hasYieldValue = (node, checkYieldReturnValue) => {
 /**
  * Checks if a node has a throws statement.
  *
- * @param {object} node
- * @param {boolean} innerFunction
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {boolean} [innerFunction]
  * @returns {boolean}
  */
 // eslint-disable-next-line complexity
@@ -843,8 +968,8 @@ const isInlineTag = (tag) => {
  *
  * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
  * @see {https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
- * @param {JsDocTag} tag
- * @returns {Array<string>}
+ * @param {import('comment-parser').Spec} tag
+ * @returns {string[]}
  */
 const parseClosureTemplateTag = tag => {
   return tag.name.split(',').map(type => {
@@ -861,7 +986,7 @@ const parseClosureTemplateTag = tag => {
  *   contexts designated by the rule. Returns an array of
  *   ESTree AST types, indicating allowable contexts.
  *
- * @param {*} context
+ * @param {import('eslint').Rule.RuleContext} context
  * @param {DefaultContexts} defaultContexts
  * @param settings
  * @returns {string[]}
@@ -921,8 +1046,31 @@ const filterTags = (tags, filter) => {
 const tagsWithNamesAndDescriptions = new Set(['param', 'arg', 'argument', 'property', 'prop', 'template',
 // These two are parsed by our custom parser as though having a `name`
 'returns', 'return']);
+
+/* eslint-disable jsdoc/valid-types -- Old version */
+/**
+ * @typedef {{
+ *   [key: string]: false|
+ *     {message: string, replacement?: string}
+ * }} TagNamePreference
+ */
+/* eslint-enable jsdoc/valid-types -- Old version */
+
+/**
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {ParserMode} mode
+ * @param {import('comment-parser').Spec[]} tags
+ * @param {TagNamePreference} tagPreference
+ * @returns {{
+ *   tagsWithNames: import('comment-parser').Spec[],
+ *   tagsWithoutNames: import('comment-parser').Spec[]
+ * }}
+ */
 const getTagsByType = (context, mode, tags, tagPreference) => {
   const descName = getPreferredTagName(context, mode, 'description', tagPreference);
+  /**
+   * @type {import('comment-parser').Spec[]}
+   */
   const tagsWithoutNames = [];
   const tagsWithNames = filterTags(tags, tag => {
     const {
@@ -939,22 +1087,47 @@ const getTagsByType = (context, mode, tags, tagPreference) => {
     tagsWithoutNames
   };
 };
+
+/**
+ * @param {import('eslint').SourceCode} sourceCode
+ * @returns {string}
+ */
 const getIndent = sourceCode => {
   var _sourceCode$text$matc;
   return (((_sourceCode$text$matc = sourceCode.text.match(/^\n*([ \t]+)/u)) === null || _sourceCode$text$matc === void 0 ? void 0 : _sourceCode$text$matc[1]) ?? '') + ' ';
 };
+
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @returns {boolean}
+ */
 const isConstructor = node => {
   var _node$parent;
   return (node === null || node === void 0 ? void 0 : node.type) === 'MethodDefinition' && node.kind === 'constructor' || (node === null || node === void 0 ? void 0 : (_node$parent = node.parent) === null || _node$parent === void 0 ? void 0 : _node$parent.kind) === 'constructor';
 };
+
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @returns {boolean}
+ */
 const isGetter = node => {
   var _node$parent2;
   return node && ((_node$parent2 = node.parent) === null || _node$parent2 === void 0 ? void 0 : _node$parent2.kind) === 'get';
 };
+
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @returns {boolean}
+ */
 const isSetter = node => {
   var _node$parent3;
   return node && ((_node$parent3 = node.parent) === null || _node$parent3 === void 0 ? void 0 : _node$parent3.kind) === 'set';
 };
+
+/**
+ * @param {ESTreeOrTypeScriptNode} node
+ * @returns {boolean}
+ */
 const hasAccessorPair = node => {
   const {
     type,
@@ -974,6 +1147,14 @@ const hasAccessorPair = node => {
     return kind === oppositeKind && name === sourceName;
   });
 };
+
+/**
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {ESTreeOrTypeScriptNode} node
+ * @param {import('eslint').Rule.RuleContext} context
+ * @param {} schema
+ * @returns {boolean}
+ */
 const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
   const hasSchemaOption = prop => {
     var _context$options$2;