eslint-plugin-jsdoc 44.2.4 → 44.2.5

package/dist/jsdocUtils.js

@@ -4,11 +4,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _jsdoccomment = require("@es-joy/jsdoccomment");
-var _WarnSettings = _interopRequireDefault(require("./WarnSettings"));
 var _getDefaultTagStructureForMode = _interopRequireDefault(require("./getDefaultTagStructureForMode"));
 var _tagNames = require("./tagNames");
 var _hasReturnValue = require("./utils/hasReturnValue");
+var _WarnSettings = _interopRequireDefault(require("./WarnSettings"));
+var _jsdoccomment = require("@es-joy/jsdoccomment");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /**
  * @typedef {number} Integer
@@ -33,45 +33,47 @@ const setTagStructure = mode => {
   tagStructure = (0, _getDefaultTagStructureForMode.default)(mode);
 };
 
-/**
- * @typedef {{
- *   hasPropertyRest: boolean,
- *   hasRestElement: boolean,
- *   names: string[],
- *   rests: boolean[],
- * }} FlattendRootInfo
- */
-
 /**
  * @typedef {undefined|string|{
+ *   name: Integer,
+ *   restElement: boolean
+ * }|{
  *   isRestProperty: boolean|undefined,
  *   name: string,
- *   restElement: true
- * }|[undefined|string, FlattendRootInfo & {
- *   annotationParamName?: string
+ *   restElement: boolean
  * }|{
- *   name: Integer,
+ *   name: string,
  *   restElement: boolean
- * }[]]} ParamNameInfo
+ * }} ParamCommon
+ */
+/**
+ * @typedef {ParamCommon|[string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string,
+ * })]|NestedParamInfo} ParamNameInfo
  */
 
 /**
- * @typedef {undefined|string|{
- *   isRestProperty: boolean,
- *   restElement: boolean,
- *   name: string
- * }|[string, {
+ * @typedef {{
  *   hasPropertyRest: boolean,
  *   hasRestElement: boolean,
  *   names: string[],
  *   rests: boolean[],
- * }]|[string, string[]]} ParamInfo
+ * }} FlattendRootInfo
+ */
+/**
+ * @typedef {[string, (string[]|ParamInfo[])]} NestedParamInfo
+ */
+/**
+ * @typedef {ParamCommon|
+ * [string|undefined, (FlattendRootInfo & {
+ *   annotationParamName?: string
+ * })]|
+ * NestedParamInfo} ParamInfo
  */
 
 /**
  * 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.
- *
+ * appending the name of the root element along the way if present.
  * @callback FlattenRoots
  * @param {ParamInfo[]} params
  * @param {string} [root]
@@ -114,21 +116,21 @@ const flattenRoots = (params, root = '') => {
       if (flattened.hasPropertyRest) {
         hasPropertyRest = true;
       }
-      const inner = [root ? `${root}.${cur[0]}` : cur[0], ...flattened.names].filter(Boolean);
+      const inner = /** @type {string[]} */[root ? `${root}.${cur[0]}` : cur[0], ...flattened.names].filter(Boolean);
       rests.push(false, ...flattened.rests);
       return acc.concat(inner);
     }
     if (typeof cur === 'object') {
-      if (cur.isRestProperty) {
+      if ('isRestProperty' in cur && cur.isRestProperty) {
         hasPropertyRest = true;
         rests.push(true);
       } else {
         rests.push(false);
       }
-      if (cur.restElement) {
+      if ('restElement' in cur && cur.restElement) {
         hasRestElement = true;
       }
-      acc.push(root ? `${root}.${cur.name}` : cur.name);
+      acc.push(root ? `${root}.${String(cur.name)}` : String(cur.name));
     } else if (typeof cur !== 'undefined') {
       rests.push(false);
       acc.push(root ? `${root}.${cur}` : cur);
@@ -181,10 +183,14 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
    *   import('estree').RestElement|import('estree').ArrayPattern|
    *   import('@typescript-eslint/types').TSESTree.TSParameterProperty|
    *   import('@typescript-eslint/types').TSESTree.Property|
-   *   import('@typescript-eslint/types').TSESTree.RestElement
+   *   import('@typescript-eslint/types').TSESTree.RestElement|
+   *   import('@typescript-eslint/types').TSESTree.Identifier|
+   *   import('@typescript-eslint/types').TSESTree.ObjectPattern|
+   *   import('@typescript-eslint/types').TSESTree.BindingName|
+   *   import('@typescript-eslint/types').TSESTree.Parameter
    * } param
    * @param {boolean} [isProperty]
-   * @returns {ParamNameInfo}
+   * @returns {ParamNameInfo|[string, ParamNameInfo[]]}
    */
   const getParamName = (param, isProperty) => {
     var _param$left2;
@@ -228,16 +234,22 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
       // eslint-disable-next-line default-case
       switch (param.value.type) {
         case 'ArrayPattern':
-          return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
-            return {
-              name: idx,
-              restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
-            };
-          })];
+          {
+            return [/** @type {import('estree').Identifier} */
+            param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
+              return {
+                name: idx,
+                restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
+              };
+            })];
+          }
         case 'ObjectPattern':
-          return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
-            return getParamName(prop, isProperty);
-          })];
+          {
+            return [/** @type {import('estree').Identifier} */param.key.name, /** @type {import('estree').ObjectPattern} */param.value.properties.map(prop => {
+              return (/** @type {string|[string, string[]]} */getParamName(prop, isProperty)
+              );
+            })];
+          }
         case 'AssignmentPattern':
           {
             // eslint-disable-next-line default-case
@@ -245,17 +257,21 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
               case 'Identifier':
                 // Default parameter
                 if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-                  return [param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
-                    return getParamName(prop, isProperty);
+                  return [/** @type {import('estree').Identifier} */param.key.name, /** @type {import('estree').AssignmentPattern} */param.value.right.properties.map(prop => {
+                    return (/** @type {string} */getParamName( /** @type {import('estree').Property} */
+                      prop, isProperty)
+                    );
                   })];
                 }
                 break;
               case 'ObjectPattern':
-                return [param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
+                return [/** @type {import('estree').Identifier} */
+                param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
                   return getParamName(prop, isProperty);
                 })];
               case 'ArrayPattern':
-                return [param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
+                return [/** @type {import('estree').Identifier} */
+                param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
                   return {
                     name: idx,
                     restElement: (prop === null || prop === void 0 ? void 0 : prop.type) === 'RestElement'
@@ -270,9 +286,10 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
 
         // The key of an object could also be a string or number
         case 'Literal':
-          return param.key.raw ||
-          // istanbul ignore next -- `raw` may not be present in all parsers
-          param.key.value;
+          return (/** @type {string} */param.key.raw ||
+            // istanbul ignore next -- `raw` may not be present in all parsers
+            param.key.value
+          );
 
         // case 'MemberExpression':
         default:
@@ -283,9 +300,9 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
           return undefined;
       }
     }
-    if (param.type === 'ArrayPattern' || ((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.type) === 'ArrayPattern') {
+    if (param.type === 'ArrayPattern' || /** @type {import('estree').AssignmentPattern} */((_param$left2 = param.left) === null || _param$left2 === void 0 ? void 0 : _param$left2.type) === 'ArrayPattern') {
       var _param$left3;
-      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left3 = param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.elements);
+      const elements = /** @type {import('estree').ArrayPattern} */param.elements || ( /** @type {import('estree').ArrayPattern} */(_param$left3 = /** @type {import('estree').AssignmentPattern} */param.left) === null || _param$left3 === void 0 ? void 0 : _param$left3.elements);
       const roots = elements.map((prop, idx) => {
         return {
           name: `"${idx}"`,
@@ -297,19 +314,20 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
     if (['RestElement', 'ExperimentalRestProperty'].includes(param.type)) {
       return {
         isRestProperty: isProperty,
-        name: param.argument.name,
+        name: /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ /** @type {import('@typescript-eslint/types').TSESTree.RestElement} */param.argument.name,
         restElement: true
       };
     }
     if (param.type === 'TSParameterProperty') {
-      return getParamName(param.parameter, true);
+      return getParamName( /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */
+      /** @type {import('@typescript-eslint/types').TSESTree.TSParameterProperty} */param.parameter, true);
     }
     throw new Error(`Unsupported function signature format: \`${param.type}\`.`);
   };
   if (!functionNode) {
     return [];
   }
-  return (functionNode.params || ((_functionNode$value = functionNode.value) === null || _functionNode$value === void 0 ? void 0 : _functionNode$value.params) || []).map(param => {
+  return ( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */functionNode.params || ( /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */(_functionNode$value = functionNode.value) === null || _functionNode$value === void 0 ? void 0 : _functionNode$value.params) || []).map(param => {
     return getParamName(param);
   });
 };
@@ -320,13 +338,13 @@ const getFunctionParameterNames = (functionNode, checkDefaultObjects) => {
  */
 const hasParams = functionNode => {
   // Should also check `functionNode.value.params` if supporting `MethodDefinition`
-  return functionNode.params.length;
+  return (/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */functionNode.params.length
+  );
 };
 
 /**
  * Gets all names of the target type, including those that refer to a path, e.g.
  * "@param foo; @param foo.bar".
- *
  * @param {import('comment-parser').Block} jsdoc
  * @param {string} targetTagName
  * @returns {{
@@ -373,6 +391,10 @@ const getTagNamesForMode = (mode, context) => {
       if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
         context.report({
           loc: {
+            end: {
+              column: 1,
+              line: 1
+            },
             start: {
               column: 1,
               line: 1
@@ -444,9 +466,7 @@ const isValidTag = (context, mode, name, definedTags) => {
 };
 
 /**
- * @param {import('comment-parser').Block & {
- *   inlineTags: import('@es-joy/jsdoccomment').InlineTag[]
- * }} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string} targetTagName
  * @returns {boolean}
  */
@@ -459,10 +479,7 @@ const hasTag = (jsdoc, targetTagName) => {
 
 /**
  * Get all tags, inline tags and inline tags in tags
- *
- * @param {import('comment-parser').Block & {
- *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
- * }} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @returns {(import('comment-parser').Spec|
  *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}
  */
@@ -495,7 +512,8 @@ const getAllTags = jsdoc => {
       }
     }
     for (const inlineTag of tag.inlineTags) {
-      let line;
+      /** @type {import('./iterateJsdoc.js').Integer} */
+      let line = 0;
       for (const {
         number,
         tokens: {
@@ -521,7 +539,7 @@ const getAllTags = jsdoc => {
 };
 
 /**
- * @param {import('comment-parser').Block} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {string[]} targetTagNames
  * @returns {boolean}
  */
@@ -533,7 +551,6 @@ const hasATag = (jsdoc, targetTagNames) => {
 
 /**
  * Checks if the JSDoc comment has an undefined type.
- *
  * @param {import('comment-parser').Spec|null|undefined} tag
  *   the tag which should be checked.
  * @param {ParserMode} mode
@@ -685,7 +702,7 @@ const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
     return true;
   }
   const tagStruct = ensureMap(tagMap, tag);
-  const ret = tagStruct.get('typeAllowed');
+  const ret = /** @type {boolean|undefined} */tagStruct.get('typeAllowed');
   return ret === undefined ? true : ret;
 };
 const namepathTypes = new Set(['namepath-defining', 'namepath-referencing']);
@@ -708,7 +725,8 @@ const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
  */
 const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
   const tagStruct = ensureMap(tagMap, tag);
-  return namepathTypes.has(tagStruct.get('namepathRole'));
+  const nampathRole = tagStruct.get('namepathRole');
+  return nampathRole !== false && namepathTypes.has( /** @type {string} */nampathRole);
 };
 
 /**
@@ -759,7 +777,7 @@ const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
 
 /* eslint-disable complexity -- Temporary */
 /**
- * @param {ESTreeOrTypeScriptNode} node
+ * @param {ESTreeOrTypeScriptNode|null|undefined} node
  * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
@@ -805,7 +823,8 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
       }
     case 'TryStatement':
       {
-        return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield(node.finalizer, checkYieldReturnValue);
+        return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield( /** @type {import('@typescript-eslint/types').TSESTree.BlockStatement} */
+        node.finalizer, checkYieldReturnValue);
       }
     case 'SwitchStatement':
       {
@@ -866,8 +885,11 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     // @ts-expect-error In Babel?
     // istanbul ignore next -- In Babel?
     case 'ObjectMethod':
+      // @ts-expect-error In Babel?
       // istanbul ignore next -- In Babel?
-      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || node.arguments.some(nde => {
+      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
+      // @ts-expect-error In Babel?
+      node.arguments.some(nde => {
         return hasNonFunctionYield(nde, checkYieldReturnValue);
       });
     case 'SpreadElement':
@@ -898,7 +920,7 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
     case 'YieldExpression':
       {
         if (checkYieldReturnValue) {
-          if (node.parent.type === 'VariableDeclarator') {
+          if ( /** @type {import('eslint').Rule.Node} */node.parent.type === 'VariableDeclarator') {
             return true;
           }
           return false;
@@ -919,18 +941,18 @@ const hasNonFunctionYield = (node, checkYieldReturnValue) => {
 
 /**
  * Checks if a node has a return statement. Void return does not count.
- *
  * @param {ESTreeOrTypeScriptNode} node
  * @param {boolean} [checkYieldReturnValue]
  * @returns {boolean}
  */
 const hasYieldValue = (node, checkYieldReturnValue) => {
-  return node.generator && (node.expression || hasNonFunctionYield(node.body, checkYieldReturnValue));
+  return (/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */node.generator && ( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */node.expression || hasNonFunctionYield( /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */
+    node.body, checkYieldReturnValue))
+  );
 };
 
 /**
  * Checks if a node has a throws statement.
- *
  * @param {ESTreeOrTypeScriptNode|null|undefined} node
  * @param {boolean} [innerFunction]
  * @returns {boolean}
@@ -1007,9 +1029,8 @@ const isInlineTag = (tag) => {
 
 /**
  * Parses GCC Generic/Template types
- *
- * @see {https://github.com/google/closure-compiler/wiki/Generic-Types}
- * @see {https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
+ * @see {@link https://github.com/google/closure-compiler/wiki/Generic-Types}
+ * @see {@link https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template}
  * @param {import('comment-parser').Spec} tag
  * @returns {string[]}
  */
@@ -1025,9 +1046,8 @@ const parseClosureTemplateTag = tag => {
 
 /**
  * Checks user option for `contexts` array, defaulting to
- *   contexts designated by the rule. Returns an array of
- *   ESTree AST types, indicating allowable contexts.
- *
+ * contexts designated by the rule. Returns an array of
+ * ESTree AST types, indicating allowable contexts.
  * @param {import('eslint').Rule.RuleContext} context
  * @param {DefaultContexts|undefined} defaultContexts
  * @param {{
@@ -1044,14 +1064,17 @@ const enforcedContexts = (context, defaultContexts, settings) => {
 /**
  * @param {import('./iterateJsdoc.js').Context[]} contexts
  * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
- * @param {Function} [handler]
+ * @param {import('@es-joy/jsdoccomment').CommentHandler} [handler]
  * @returns {import('eslint').Rule.RuleListener}
  */
 const getContextObject = (contexts, checkJsdoc, handler) => {
   /** @type {import('eslint').Rule.RuleListener} */
   const properties = {};
   for (const [idx, prop] of contexts.entries()) {
+    /** @type {string} */
     let property;
+
+    /** @type {(node: import('eslint').Rule.Node) => void} */
     let value;
     if (typeof prop === 'object') {
       const selInfo = {
@@ -1059,13 +1082,18 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
         selector: prop.context
       };
       if (prop.comment) {
-        property = prop.context;
+        property = /** @type {string} */prop.context;
         value = checkJsdoc.bind(null, {
           ...selInfo,
           comment: prop.comment
-        }, handler.bind(null, prop.comment));
+        },
+        /**
+         * @type {(jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean}
+         */
+        /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
+        handler.bind(null, prop.comment));
       } else {
-        property = prop.context;
+        property = /** @type {string} */prop.context;
         value = checkJsdoc.bind(null, selInfo, null);
       }
     } else {
@@ -1076,10 +1104,18 @@ const getContextObject = (contexts, checkJsdoc, handler) => {
       property = prop;
       value = checkJsdoc.bind(null, selInfo, null);
     }
-    const old = properties[property];
-    properties[property] = old ? function (...args) {
-      old(...args);
-      value(...args);
+    const old =
+    /**
+     * @type {((node: import('eslint').Rule.Node) => void)}
+     */
+    properties[property];
+    properties[property] = old ?
+    /**
+     * @type {((node: import('eslint').Rule.Node) => void)}
+     */
+    function (node) {
+      old(node);
+      value(node);
     } : value;
   }
   return properties;
@@ -1088,10 +1124,9 @@ const tagsWithNamesAndDescriptions = new Set(['param', 'arg', 'argument', 'prope
 // 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|
+ *   [key: string]: false|string|
  *     {message: string, replacement?: string}
  * }} TagNamePreference
  */
@@ -1211,7 +1246,7 @@ const hasAccessorPair = node => {
 };
 
 /**
- * @param {import('comment-parser').Block} jsdoc
+ * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
  * @param {import('eslint').Rule.Node|null} node
  * @param {import('eslint').Rule.RuleContext} context
  * @param {import('json-schema').JSONSchema4} schema
@@ -1237,17 +1272,16 @@ const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
  * identifier or numeric literal) or single or double quoted, in either
  * the `@param` or in source, we need to strip the quotes to give a fair
  * comparison.
- *
  * @param {string} str
  * @returns {string}
  */
 const dropPathSegmentQuotes = str => {
-  return str.replace(/\.(['"])(.*)\1/gu, '.$2');
+  return str.replaceAll(/\.(['"])(.*)\1/gu, '.$2');
 };
 
 /**
  * @param {string} name
- * @returns {(otherPathName: string) => void}
+ * @returns {(otherPathName: string) => boolean}
  */
 const comparePaths = name => {
   return otherPathName => {