eslint-plugin-jsdoc 63.3.3 → 64.0.0

package/dist/jsdocUtils.cjs

@@ -1,1786 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.hasParams = exports.hasATag = exports.getTagsByType = exports.getTags = exports.getTagStructureForMode = exports.getTagDescription = exports.getRegexFromString = exports.getPreferredTagNameSimple = exports.getPreferredTagName = exports.getJsdocTagsDeep = exports.getJSDocCommentBlocks = exports.getInlineTags = exports.getIndent = exports.getFunctionParameterNames = exports.getDocumentNamepathDefiningTags = exports.getContextObject = exports.getAllTags = exports.forEachPreferredTag = exports.flattenRoots = exports.filterTags = exports.exemptSpeciaMethods = exports.enforcedContexts = exports.dropPathSegmentQuotes = exports.comparePaths = void 0;
-Object.defineProperty(exports, "hasReturnValue", {
-  enumerable: true,
-  get: function () {
-    return _hasReturnValue.hasReturnValue;
-  }
-});
-exports.hasThrowValue = exports.hasTag = void 0;
-Object.defineProperty(exports, "hasValueOrExecutorHasNonEmptyResolveValue", {
-  enumerable: true,
-  get: function () {
-    return _hasReturnValue.hasValueOrExecutorHasNonEmptyResolveValue;
-  }
-});
-exports.tagMustHaveTypePosition = exports.tagMustHaveNamePosition = exports.tagMissingRequiredTypeOrNamepath = exports.tagMightHaveTypePosition = exports.tagMightHaveNamepath = exports.tagMightHaveNamePosition = exports.tagMightHaveNameOrNamepath = exports.tagMightHaveName = exports.tagMightHaveEitherTypeOrNamePosition = exports.strictNativeTypes = exports.setTagStructure = exports.rewireByParsedType = exports.pathDoesNotBeginWith = exports.parseClosureTemplateTag = exports.overrideTagStructure = exports.mayBeUndefinedTypeTag = exports.isValidTag = exports.isSetter = exports.isNamepathReferencingTag = exports.isNamepathOrUrlReferencingTag = exports.isNameOrNamepathDefiningTag = exports.isGetter = exports.isConstructor = exports.hasYieldValue = void 0;
-var _getDefaultTagStructureForMode = _interopRequireDefault(require("./getDefaultTagStructureForMode.cjs"));
-var _tagNames = require("./tagNames.cjs");
-var _WarnSettings = _interopRequireDefault(require("./WarnSettings.cjs"));
-var _jsdoccomment = require("@es-joy/jsdoccomment");
-var _hasReturnValue = require("./utils/hasReturnValue.cjs");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * @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);
-};
-
-/**
- * @typedef {undefined|string|{
- *   name: Integer,
- *   restElement: boolean
- * }|{
- *   isRestProperty: boolean|undefined,
- *   name: string,
- *   restElement: boolean
- * }|{
- *   name: string,
- *   restElement: boolean
- * }} ParamCommon
- */
-/**
- * @typedef {ParamCommon|[string|undefined, (FlattendRootInfo & {
- *   annotationParamName?: string,
- * })]|NestedParamInfo} ParamNameInfo
- */
-
-/**
- * @typedef {{
- *   hasPropertyRest: boolean,
- *   hasRestElement: boolean,
- *   names: string[],
- *   rests: boolean[],
- * }} 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.
- * @callback FlattenRoots
- * @param {ParamInfo[]} params
- * @param {string} [root]
- * @returns {FlattendRootInfo}
- */
-
-/** @type {FlattenRoots} */
-exports.setTagStructure = setTagStructure;
-const flattenRoots = (params, root = '') => {
-  let hasRestElement = false;
-  let hasPropertyRest = false;
-
-  /**
-   * @type {boolean[]}
-   */
-  const rests = [];
-  const names = params.reduce(
-  /**
-   * @param {string[]} acc
-   * @param {ParamInfo} cur
-   * @returns {string[]}
-   */
-  (acc, cur) => {
-    if (Array.isArray(cur)) {
-      let nms;
-      if (Array.isArray(cur[1])) {
-        nms = cur[1];
-      } else {
-        if (cur[1].hasRestElement) {
-          hasRestElement = true;
-        }
-        if (cur[1].hasPropertyRest) {
-          hasPropertyRest = true;
-        }
-        nms = cur[1].names;
-      }
-      const flattened = flattenRoots(nms, root ? `${root}.${cur[0]}` : cur[0]);
-      if (flattened.hasRestElement) {
-        hasRestElement = true;
-      }
-      if (flattened.hasPropertyRest) {
-        hasPropertyRest = true;
-      }
-      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 ('isRestProperty' in cur && cur.isRestProperty) {
-        hasPropertyRest = true;
-        rests.push(true);
-      } else {
-        rests.push(false);
-      }
-      if ('restElement' in cur && cur.restElement) {
-        hasRestElement = true;
-      }
-      acc.push(root ? `${root}.${String(cur.name)}` : String(cur.name));
-    } else if (typeof cur !== 'undefined') {
-      rests.push(false);
-      acc.push(root ? `${root}.${cur}` : cur);
-    }
-    return acc;
-  }, []);
-  return {
-    hasPropertyRest,
-    hasRestElement,
-    names,
-    rests
-  };
-};
-
-/**
- * @param {import('@typescript-eslint/types').TSESTree.TSIndexSignature|
- *  import('@typescript-eslint/types').TSESTree.TSConstructSignatureDeclaration|
- *  import('@typescript-eslint/types').TSESTree.TSCallSignatureDeclaration|
- *  import('@typescript-eslint/types').TSESTree.TSPropertySignature} propSignature
- * @returns {undefined|string|[string, string[]]}
- */
-exports.flattenRoots = flattenRoots;
-const getPropertiesFromPropertySignature = propSignature => {
-  if (propSignature.type === 'TSIndexSignature' || propSignature.type === 'TSConstructSignatureDeclaration' || propSignature.type === 'TSCallSignatureDeclaration') {
-    return undefined;
-  }
-  if (propSignature.typeAnnotation && propSignature.typeAnnotation.typeAnnotation.type === 'TSTypeLiteral') {
-    return [/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name, propSignature.typeAnnotation.typeAnnotation.members.map(member => {
-      return /** @type {string} */getPropertiesFromPropertySignature(/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
-      member);
-    })];
-  }
-  return /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */propSignature.key.name;
-};
-
-/**
- * @param {ESTreeOrTypeScriptNode|null} functionNode
- * @param {boolean} [checkDefaultObjects]
- * @param {boolean} [ignoreInterfacedParameters]
- * @throws {Error}
- * @returns {ParamNameInfo[]}
- */
-const getFunctionParameterNames = (functionNode, checkDefaultObjects, ignoreInterfacedParameters) => {
-  /* eslint-disable complexity -- Temporary */
-  /**
-   * @param {import('estree').Identifier|import('estree').AssignmentPattern|
-   *   import('estree').ObjectPattern|import('estree').Property|
-   *   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.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|[string, ParamNameInfo[]]}
-   */
-  const getParamName = (param, isProperty) => {
-    /* eslint-enable complexity -- Temporary */
-    const hasLeftTypeAnnotation = 'left' in param && 'typeAnnotation' in param.left;
-    if ('typeAnnotation' in param || hasLeftTypeAnnotation) {
-      if (ignoreInterfacedParameters && 'typeAnnotation' in param && param.typeAnnotation) {
-        // No-op
-        return [undefined, {
-          hasPropertyRest: false,
-          hasRestElement: false,
-          names: [],
-          rests: []
-        }];
-      }
-      const typeAnnotation = hasLeftTypeAnnotation ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.typeAnnotation : /** @type {import('@typescript-eslint/types').TSESTree.Identifier|import('@typescript-eslint/types').TSESTree.ObjectPattern} */
-      param.typeAnnotation;
-      if (typeAnnotation?.typeAnnotation?.type === 'TSTypeLiteral') {
-        const propertyNames = typeAnnotation.typeAnnotation.members.map(member => {
-          return getPropertiesFromPropertySignature(/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */
-          member);
-        });
-        const flattened = {
-          ...flattenRoots(propertyNames),
-          annotationParamName: 'name' in param ? param.name : undefined
-        };
-        const hasLeftName = 'left' in param && 'name' in param.left;
-        if ('name' in param || hasLeftName) {
-          return [hasLeftName ? /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.left.name : /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */param.name, flattened];
-        }
-        return [undefined, flattened];
-      }
-    }
-    if ('name' in param) {
-      return param.name;
-    }
-    if ('left' in param && 'name' in param.left) {
-      return param.left.name;
-    }
-    if (param.type === 'ObjectPattern' || 'left' in param && param.left.type === 'ObjectPattern') {
-      const properties = /** @type {import('@typescript-eslint/types').TSESTree.ObjectPattern} */param.properties || /** @type {import('estree').ObjectPattern} */
-      (/** @type {import('@typescript-eslint/types').TSESTree.AssignmentPattern} */param.left)?.properties;
-      const roots = properties.map(prop => {
-        return getParamName(prop, true);
-      });
-      return [undefined, flattenRoots(roots)];
-    }
-    if (param.type === 'Property') {
-      switch (param.value.type) {
-        case 'ArrayPattern':
-          {
-            return [/** @type {import('estree').Identifier} */
-            param.key.name, /** @type {import('estree').ArrayPattern} */param.value.elements.map((prop, idx) => {
-              return {
-                name: idx,
-                restElement: prop?.type === 'RestElement'
-              };
-            })];
-          }
-        case 'ObjectPattern':
-          {
-            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':
-          {
-            switch (param.value.left.type) {
-              case 'ArrayPattern':
-                return [/** @type {import('estree').Identifier} */
-                param.key.name, /** @type {import('estree').ArrayPattern} */param.value.left.elements.map((prop, idx) => {
-                  return {
-                    name: idx,
-                    restElement: prop?.type === 'RestElement'
-                  };
-                })];
-              case 'Identifier':
-                // Default parameter
-                if (checkDefaultObjects && param.value.right.type === 'ObjectExpression') {
-                  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 [/** @type {import('estree').Identifier} */
-                param.key.name, /** @type {import('estree').ObjectPattern} */param.value.left.properties.map(prop => {
-                  return getParamName(prop, isProperty);
-                })];
-            }
-          }
-      }
-      switch (param.key.type) {
-        case 'Identifier':
-          return param.key.name;
-
-        // The key of an object could also be a string or number
-        case 'Literal':
-          /* c8 ignore next 2 -- `raw` may not be present in all parsers */
-          return /** @type {string} */param.key.raw || param.key.value;
-
-        // case 'MemberExpression':
-        default:
-          // Todo: We should really create a structure (and a corresponding
-          //   option analogous to `checkRestProperty`) which allows for
-          //   (and optionally requires) dynamic properties to have a single
-          //   line of documentation
-          return undefined;
-      }
-    }
-    if (param.type === 'ArrayPattern' || /** @type {import('estree').AssignmentPattern} */param.left?.type === 'ArrayPattern') {
-      const elements = /** @type {import('estree').ArrayPattern} */param.elements || /** @type {import('estree').ArrayPattern} */(/** @type {import('estree').AssignmentPattern} */param.left)?.elements;
-      const roots = elements.map((prop, idx) => {
-        return {
-          name: `"${idx}"`,
-          restElement: prop?.type === 'RestElement'
-        };
-      });
-      return [undefined, flattenRoots(roots)];
-    }
-    if (['ExperimentalRestProperty', 'RestElement'].includes(param.type)) {
-      return {
-        isRestProperty: isProperty,
-        name: /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */(/** @type {import('@typescript-eslint/types').TSESTree.RestElement} */param
-        // @ts-expect-error Ok
-        .argument).name ?? param?.argument?.elements?.map(({
-          // @ts-expect-error Ok
-          name
-        }) => {
-          return name;
-        }),
-        restElement: true
-      };
-    }
-    if (param.type === 'TSParameterProperty') {
-      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 (/** @type {import('@typescript-eslint/types').TSESTree.TSFunctionType} */
-  (/** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */functionNode?.typeAnnotation?.typeAnnotation)?.params || /** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */functionNode.params || /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */functionNode.value?.params || []).map(param => {
-    return getParamName(param);
-  });
-};
-
-/**
- * @param {ESTreeOrTypeScriptNode} functionNode
- * @returns {Integer}
- */
-exports.getFunctionParameterNames = getFunctionParameterNames;
-const hasParams = functionNode => {
-  // Should also check `functionNode.value.params` if supporting `MethodDefinition`
-  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.
- * `foo` or `foo.bar`.
- * @param {import('comment-parser').Block} jsdoc
- * @param {string} targetTagName
- * @returns {{
- *   idx: Integer,
- *   name: string,
- *   type: string
- * }[]}
- */
-exports.hasParams = hasParams;
-const getJsdocTagsDeep = (jsdoc, targetTagName) => {
-  const ret = [];
-  for (const [idx, {
-    name,
-    tag,
-    type
-  }] of jsdoc.tags.entries()) {
-    if (tag !== targetTagName) {
-      continue;
-    }
-    ret.push({
-      idx,
-      name,
-      type
-    });
-  }
-  return ret;
-};
-exports.getJsdocTagsDeep = getJsdocTagsDeep;
-const modeWarnSettings = (0, _WarnSettings.default)();
-
-/**
- * @param {ParserMode|undefined} mode
- * @param {import('eslint').Rule.RuleContext} context
- * @returns {import('./tagNames.js').AliasedTags}
- */
-const getTagNamesForMode = (mode, context) => {
-  switch (mode) {
-    case 'closure':
-    case 'permissive':
-      return _tagNames.closureTags;
-    case 'jsdoc':
-      return _tagNames.jsdocTags;
-    case 'typescript':
-      return _tagNames.typeScriptTags;
-    default:
-      if (!modeWarnSettings.hasBeenWarned(context, 'mode')) {
-        context.report({
-          loc: {
-            end: {
-              column: 1,
-              line: 1
-            },
-            start: {
-              column: 1,
-              line: 1
-            }
-          },
-          message: `Unrecognized value \`${mode}\` for \`settings.jsdoc.mode\`.`
-        });
-        modeWarnSettings.markSettingAsWarned(context, 'mode');
-      }
-
-      // We'll avoid breaking too many other rules
-      return _tagNames.jsdocTags;
-  }
-};
-
-/**
- * @param {import('comment-parser').Spec} tg
- * @param {boolean} [returnArray]
- * @returns {string[]|string}
- */
-const getTagDescription = (tg, returnArray) => {
-  /**
-   * @type {string[]}
-   */
-  const descriptions = [];
-  tg.source.some(({
-    tokens: {
-      description,
-      end,
-      lineEnd,
-      name,
-      postDelimiter,
-      postTag,
-      tag,
-      type
-    }
-  }) => {
-    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 {import('eslint').Rule.RuleContext} context
- * @returns {string|false|{
- *   message: string;
- *   replacement?: string|undefined;
- * }}
- */
-exports.getTagDescription = getTagDescription;
-const getPreferredTagNameSimple = (name, mode, tagPreference = {},
-// @ts-expect-error Just a no-op
-// eslint-disable-next-line unicorn/no-object-as-default-parameter -- Ok
-context = {
-  report() {
-    // No-op
-  }
-}) => {
-  const prefValues = Object.values(tagPreference);
-  if (prefValues.includes(name) || prefValues.some(prefVal => {
-    return prefVal && typeof prefVal === 'object' && prefVal.replacement === name;
-  })) {
-    return name;
-  }
-
-  // Allow keys to have a 'tag ' prefix to avoid upstream bug in ESLint
-  // that disallows keys that conflict with Object.prototype,
-  // e.g. 'tag constructor' for 'constructor':
-  // https://github.com/eslint/eslint/issues/13289
-  // https://github.com/gajus/eslint-plugin-jsdoc/issues/537
-  const tagPreferenceFixed = Object.fromEntries(Object.entries(tagPreference).map(([key, value]) => {
-    return [key.replace(/^tag /v, ''), value];
-  }));
-  if (Object.hasOwn(tagPreferenceFixed, name)) {
-    return tagPreferenceFixed[name];
-  }
-  const tagNames = getTagNamesForMode(mode, context);
-  const preferredTagName = Object.entries(tagNames).find(([, aliases]) => {
-    return aliases.includes(name);
-  })?.[0];
-  if (preferredTagName) {
-    return preferredTagName;
-  }
-  return name;
-};
-
-/**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode|undefined} mode
- * @param {string} name
- * @param {string[]} definedTags
- * @returns {boolean}
- */
-exports.getPreferredTagNameSimple = getPreferredTagNameSimple;
-const isValidTag = (context, mode, name, definedTags) => {
-  const tagNames = getTagNamesForMode(mode, context);
-  const validTagNames = Object.keys(tagNames).concat(Object.values(tagNames).flat());
-  const additionalTags = definedTags;
-  const allTags = validTagNames.concat(additionalTags);
-  return allTags.includes(name);
-};
-
-/**
- * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
- * @param {string} targetTagName
- * @returns {boolean}
- */
-exports.isValidTag = isValidTag;
-const hasTag = (jsdoc, targetTagName) => {
-  const targetTagLower = targetTagName.toLowerCase();
-  return jsdoc.tags.some(doc => {
-    return doc.tag.toLowerCase() === targetTagLower;
-  });
-};
-
-/**
- * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
- * @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter
- * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}
- */
-exports.hasTag = hasTag;
-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[]}
- */
-exports.filterTags = filterTags;
-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
- * }}
- */
-exports.getTags = getTags;
-const getPreferredTagName = (jsdoc, {
-  allowObjectReturn = false,
-  context,
-  tagName,
-  defaultMessage = `Unexpected tag \`@${tagName}\``,
-  mode,
-  report = () => {},
-  skipReportingBlockedTag = false,
-  tagNamePreference
-}) => {
-  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}
- */
-exports.getPreferredTagName = getPreferredTagName;
-const forEachPreferredTag = (jsdoc, tagName, arrayHandler, {
-  context,
-  mode,
-  report,
-  skipReportingBlockedTag = false,
-  tagNamePreference
-} = {}) => {
-  const targetTagName = /** @type {string|false} */
-  getPreferredTagName(jsdoc, {
-    context,
-    mode,
-    report,
-    skipReportingBlockedTag,
-    tagName,
-    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 inline tags and inline tags in tags
- * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
- * @returns {(import('comment-parser').Spec|
- *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
- *     line?: number | undefined; column?: number | undefined;
- *   })[]}
- */
-exports.forEachPreferredTag = forEachPreferredTag;
-const getInlineTags = jsdoc => {
-  return [...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 => {
-    for (const inlineTag of tag.inlineTags) {
-      /** @type {import('./iterateJsdoc.js').Integer} */
-      let line = 0;
-      for (const {
-        number,
-        tokens: {
-          description
-        }
-      } of tag.source) {
-        if (description && description.includes(`{@${inlineTag.tag}`)) {
-          line = number;
-          break;
-        }
-      }
-      inlineTag.line = line;
-    }
-    return (
-      /**
-       * @type {import('comment-parser').Spec & {
-       *   inlineTags: import('@es-joy/jsdoccomment').JsdocInlineTagNoType[]
-       * }}
-       */
-      tag.inlineTags
-    );
-  })];
-};
-
-/**
- * Get all tags, inline tags and inline tags in tags
- * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
- * @returns {(import('comment-parser').Spec|
- *   import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
- *     line?: number | undefined; column?: number | undefined;
- *   })[]}
- */
-exports.getInlineTags = getInlineTags;
-const getAllTags = jsdoc => {
-  return [...jsdoc.tags, ...getInlineTags(jsdoc)];
-};
-
-/**
- * @param {import('./iterateJsdoc.js').JsdocBlockWithInline} jsdoc
- * @param {string[]} targetTagNames
- * @returns {boolean}
- */
-exports.getAllTags = getAllTags;
-const hasATag = (jsdoc, targetTagNames) => {
-  return targetTagNames.some(targetTagName => {
-    return hasTag(jsdoc, targetTagName);
-  });
-};
-
-/**
- * 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
- * @returns {boolean}
- *   true in case a defined type is undeclared; otherwise false.
- */
-exports.hasATag = hasATag;
-const mayBeUndefinedTypeTag = (tag, mode) => {
-  // The function should not continue in the event the type is not defined...
-  if (typeof tag === 'undefined' || tag === null) {
-    return true;
-  }
-
-  // .. same applies if it declares an `{undefined}` or `{void}` type
-  const tagType = tag.type.trim();
-
-  // Exit early if matching
-  if (tagType === 'undefined' || tagType === 'void' || tagType === '*' || tagType === 'any') {
-    return true;
-  }
-  let parsedTypes;
-  try {
-    parsedTypes = (0, _jsdoccomment.tryParse)(tagType, mode === 'permissive' ? undefined : [mode]);
-  } catch {
-    // Ignore
-  }
-  if (
-  // We do not traverse deeply as it could be, e.g., `Promise<void>`
-  parsedTypes && parsedTypes.type === 'JsdocTypeUnion' && parsedTypes.elements.some(elem => {
-    return elem.type === 'JsdocTypeUndefined' || elem.type === 'JsdocTypeName' && elem.value === 'void';
-  })) {
-    return true;
-  }
-
-  // In any other case, a type is present
-  return false;
-};
-
-/**
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} map
- * @param {string} tag
- * @returns {Map<string, string|string[]|boolean|undefined>}
- */
-exports.mayBeUndefinedTypeTag = mayBeUndefinedTypeTag;
-const ensureMap = (map, tag) => {
-  if (!map.has(tag)) {
-    map.set(tag, new Map());
-  }
-  return /** @type {Map<string, string | boolean>} */map.get(tag);
-};
-
-/**
- * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {void}
- */
-const overrideTagStructure = (structuredTags, tagMap = tagStructure) => {
-  for (const [tag, {
-    name,
-    required = [],
-    type
-  }] of Object.entries(structuredTags)) {
-    const tagStruct = ensureMap(tagMap, tag);
-    tagStruct.set('namepathRole', name);
-    tagStruct.set('typeAllowed', type);
-    const requiredName = required.includes('name');
-    if (requiredName && name === false) {
-      throw new Error('Cannot add "name" to `require` with the tag\'s `name` set to `false`');
-    }
-    tagStruct.set('nameRequired', requiredName);
-    const requiredType = required.includes('type');
-    if (requiredType && type === false) {
-      throw new Error('Cannot add "type" to `require` with the tag\'s `type` set to `false`');
-    }
-    tagStruct.set('typeRequired', requiredType);
-    const typeOrNameRequired = required.includes('typeOrNameRequired');
-    if (typeOrNameRequired && name === false) {
-      throw new Error('Cannot add "typeOrNameRequired" to `require` with the tag\'s `name` set to `false`');
-    }
-    if (typeOrNameRequired && type === false) {
-      throw new Error('Cannot add "typeOrNameRequired" to `require` with the tag\'s `type` set to `false`');
-    }
-    tagStruct.set('typeOrNameRequired', typeOrNameRequired);
-  }
-};
-
-/**
- * @param {ParserMode} mode
- * @param {import('./iterateJsdoc.js').StructuredTags} structuredTags
- * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}
- */
-exports.overrideTagStructure = overrideTagStructure;
-const getTagStructureForMode = (mode, structuredTags) => {
-  const tagStruct = (0, _getDefaultTagStructureForMode.default)(mode);
-  try {
-    overrideTagStructure(structuredTags, tagStruct);
-    /* c8 ignore next 3 */
-  } catch {
-    //
-  }
-  return tagStruct;
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.getTagStructureForMode = getTagStructureForMode;
-const isNameOrNamepathDefiningTag = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return /** @type {(string|boolean|undefined)[]} */['name-defining', 'namepath-defining'].includes(/** @type {string|boolean|undefined} */
-  tagStruct.get('namepathRole'));
-};
-
-/**
- * @param {import('eslint').SourceCode} sourceCode
- * @returns {import('@es-joy/jsdoccomment').JsdocBlockWithInline[]}
- */
-exports.isNameOrNamepathDefiningTag = isNameOrNamepathDefiningTag;
-const getJSDocCommentBlocks = sourceCode => {
-  return sourceCode.getAllComments().filter(comment => {
-    return /^\*(?!\*)/v.test(comment.value);
-  }).map(commentNode => {
-    return (0, _jsdoccomment.parseComment)(commentNode, '');
-  });
-};
-
-/**
- * @param {import('eslint').SourceCode} sourceCode
- * @returns {import('comment-parser').Spec[]}
- */
-exports.getJSDocCommentBlocks = getJSDocCommentBlocks;
-const getDocumentNamepathDefiningTags = sourceCode => {
-  return getJSDocCommentBlocks(sourceCode).flatMap(doc => {
-    return doc.tags.filter(({
-      tag
-    }) => {
-      return isNameOrNamepathDefiningTag(tag) && !['arg', 'argument', 'param', 'prop', 'property'].includes(tag);
-    });
-  });
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.getDocumentNamepathDefiningTags = getDocumentNamepathDefiningTags;
-const isNamepathReferencingTag = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('namepathRole') === 'namepath-referencing';
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.isNamepathReferencingTag = isNamepathReferencingTag;
-const isNamepathOrUrlReferencingTag = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return tagStruct.get('namepathRole') === 'namepath-or-url-referencing';
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean|undefined}
- */
-exports.isNamepathOrUrlReferencingTag = isNamepathOrUrlReferencingTag;
-const tagMustHaveTypePosition = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return /** @type {boolean|undefined} */tagStruct.get('typeRequired');
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean|string}
- */
-exports.tagMustHaveTypePosition = tagMustHaveTypePosition;
-const tagMightHaveTypePosition = (tag, tagMap = tagStructure) => {
-  if (tagMustHaveTypePosition(tag, tagMap)) {
-    return true;
-  }
-  const tagStruct = ensureMap(tagMap, tag);
-  const ret = /** @type {boolean|undefined} */tagStruct.get('typeAllowed');
-  return ret === undefined ? true : ret;
-};
-exports.tagMightHaveTypePosition = tagMightHaveTypePosition;
-const namepathTypes = new Set(['name-defining', 'namepath-defining', 'namepath-referencing']);
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-const tagMightHaveNamePosition = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  const ret = tagStruct.get('namepathRole');
-  return ret === undefined ? true : Boolean(ret);
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.tagMightHaveNamePosition = tagMightHaveNamePosition;
-const tagMightHaveNameOrNamepath = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  const nampathRole = tagStruct.get('namepathRole');
-  return nampathRole !== false && namepathTypes.has(/** @type {string} */nampathRole);
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.tagMightHaveNameOrNamepath = tagMightHaveNameOrNamepath;
-const tagMightHaveNamepath = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  const nampathRole = tagStruct.get('namepathRole');
-  return nampathRole !== false && ['namepath-defining', 'namepath-referencing'].includes(/** @type {string} */nampathRole);
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.tagMightHaveNamepath = tagMightHaveNamepath;
-const tagMightHaveName = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  const nampathRole = tagStruct.get('namepathRole');
-  return nampathRole !== false && nampathRole === 'name-defining';
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean|undefined}
- */
-exports.tagMightHaveName = tagMightHaveName;
-const tagMustHaveNamePosition = (tag, tagMap = tagStructure) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return /** @type {boolean|undefined} */tagStruct.get('nameRequired');
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean}
- */
-exports.tagMustHaveNamePosition = tagMustHaveNamePosition;
-const tagMightHaveEitherTypeOrNamePosition = (tag, tagMap) => {
-  return Boolean(tagMightHaveTypePosition(tag, tagMap)) || tagMightHaveNameOrNamepath(tag, tagMap);
-};
-
-/**
- * @param {string} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean|undefined}
- */
-exports.tagMightHaveEitherTypeOrNamePosition = tagMightHaveEitherTypeOrNamePosition;
-const tagMustHaveEitherTypeOrNamePosition = (tag, tagMap) => {
-  const tagStruct = ensureMap(tagMap, tag);
-  return /** @type {boolean} */tagStruct.get('typeOrNameRequired');
-};
-
-/**
- * @param {import('comment-parser').Spec} tag
- * @param {import('./getDefaultTagStructureForMode.js').TagStructure} tagMap
- * @returns {boolean|undefined}
- */
-const tagMissingRequiredTypeOrNamepath = (tag, tagMap = tagStructure) => {
-  const mustHaveTypePosition = tagMustHaveTypePosition(tag.tag, tagMap);
-  const mightHaveTypePosition = tagMightHaveTypePosition(tag.tag, tagMap);
-  const hasTypePosition = mightHaveTypePosition && Boolean(tag.type);
-  const hasNameOrNamepathPosition = (tagMustHaveNamePosition(tag.tag, tagMap) || tagMightHaveNameOrNamepath(tag.tag, tagMap)) && Boolean(tag.name);
-  const mustHaveEither = tagMustHaveEitherTypeOrNamePosition(tag.tag, tagMap);
-  const hasEither = tagMightHaveEitherTypeOrNamePosition(tag.tag, tagMap) && (hasTypePosition || hasNameOrNamepathPosition);
-  return mustHaveEither && !hasEither && !mustHaveTypePosition;
-};
-
-/* eslint-disable complexity -- Temporary */
-/**
- * @param {ESTreeOrTypeScriptNode|null|undefined} node
- * @param {boolean} [checkYieldReturnValue]
- * @returns {boolean}
- */
-exports.tagMissingRequiredTypeOrNamepath = tagMissingRequiredTypeOrNamepath;
-const hasNonFunctionYield = (node, checkYieldReturnValue) => {
-  /* eslint-enable complexity -- Temporary */
-  if (!node) {
-    return false;
-  }
-  switch (node.type) {
-    case 'ArrayExpression':
-    case 'ArrayPattern':
-      return node.elements.some(element => {
-        return hasNonFunctionYield(element, checkYieldReturnValue);
-      });
-    case 'AssignmentExpression':
-    case 'BinaryExpression':
-    case 'LogicalExpression':
-      {
-        return hasNonFunctionYield(node.left, checkYieldReturnValue) || hasNonFunctionYield(node.right, checkYieldReturnValue);
-      }
-    case 'AssignmentPattern':
-      return hasNonFunctionYield(node.right, checkYieldReturnValue);
-    case 'BlockStatement':
-      {
-        return node.body.some(bodyNode => {
-          return !['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression'].includes(bodyNode.type) && hasNonFunctionYield(bodyNode, checkYieldReturnValue);
-        });
-      }
-
-    /* c8 ignore next 2 -- In Babel? */
-    case 'CallExpression':
-    // @ts-expect-error In Babel?
-    case 'OptionalCallExpression':
-      return node.arguments.some(element => {
-        return hasNonFunctionYield(element, checkYieldReturnValue);
-      });
-    case 'ChainExpression':
-    case 'ExpressionStatement':
-      {
-        return hasNonFunctionYield(node.expression, checkYieldReturnValue);
-      }
-
-    /* c8 ignore next 2 -- In Babel? */
-    // @ts-expect-error In Babel?
-    case 'ClassProperty':
-
-    /* c8 ignore next 2 -- In Babel? */
-    // @ts-expect-error In Babel?
-    case 'ObjectProperty':
-    /* c8 ignore next 2 -- In Babel? */
-    case 'Property':
-    case 'PropertyDefinition':
-      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) || hasNonFunctionYield(node.value, checkYieldReturnValue);
-    case 'ConditionalExpression':
-    case 'IfStatement':
-      {
-        return hasNonFunctionYield(node.test, checkYieldReturnValue) || hasNonFunctionYield(node.consequent, checkYieldReturnValue) || hasNonFunctionYield(node.alternate, checkYieldReturnValue);
-      }
-    case 'DoWhileStatement':
-    case 'ForInStatement':
-    case 'ForOfStatement':
-    case 'ForStatement':
-    case 'LabeledStatement':
-    case 'WhileStatement':
-    case 'WithStatement':
-      {
-        return hasNonFunctionYield(node.body, checkYieldReturnValue);
-      }
-
-    /* c8 ignore next 2 -- In Babel? */
-    // @ts-expect-error In Babel?
-    case 'Import':
-    case 'ImportExpression':
-      return hasNonFunctionYield(node.source, checkYieldReturnValue);
-
-    // ?.
-    /* c8 ignore next 2 -- In Babel? */
-    case 'MemberExpression':
-    // @ts-expect-error In Babel?
-    case 'OptionalMemberExpression':
-      return hasNonFunctionYield(node.object, checkYieldReturnValue) || hasNonFunctionYield(node.property, checkYieldReturnValue);
-    case 'ObjectExpression':
-    case 'ObjectPattern':
-      return node.properties.some(property => {
-        return hasNonFunctionYield(property, checkYieldReturnValue);
-      });
-    /* c8 ignore next 2 -- In Babel? */
-    // @ts-expect-error In Babel?
-    case 'ObjectMethod':
-      /* c8 ignore next 6 -- In Babel? */
-      // @ts-expect-error In Babel?
-      return node.computed && hasNonFunctionYield(node.key, checkYieldReturnValue) ||
-      // @ts-expect-error In Babel?
-      node.arguments.some(nde => {
-        return hasNonFunctionYield(nde, checkYieldReturnValue);
-      });
-    case 'ReturnStatement':
-      {
-        if (node.argument === null) {
-          return false;
-        }
-        return hasNonFunctionYield(node.argument, checkYieldReturnValue);
-      }
-
-    // Comma
-    case 'SequenceExpression':
-    case 'TemplateLiteral':
-      return node.expressions.some(subExpression => {
-        return hasNonFunctionYield(subExpression, checkYieldReturnValue);
-      });
-    case 'SpreadElement':
-    case 'UnaryExpression':
-      return hasNonFunctionYield(node.argument, checkYieldReturnValue);
-    case 'SwitchStatement':
-      {
-        return node.cases.some(someCase => {
-          return someCase.consequent.some(nde => {
-            return hasNonFunctionYield(nde, checkYieldReturnValue);
-          });
-        });
-      }
-    case 'TaggedTemplateExpression':
-      return hasNonFunctionYield(node.quasi, checkYieldReturnValue);
-    case 'TryStatement':
-      {
-        return hasNonFunctionYield(node.block, checkYieldReturnValue) || hasNonFunctionYield(node.handler && node.handler.body, checkYieldReturnValue) || hasNonFunctionYield(/** @type {import('@typescript-eslint/types').TSESTree.BlockStatement} */
-        node.finalizer, checkYieldReturnValue);
-      }
-    case 'VariableDeclaration':
-      {
-        return node.declarations.some(nde => {
-          return hasNonFunctionYield(nde, checkYieldReturnValue);
-        });
-      }
-    case 'VariableDeclarator':
-      {
-        return hasNonFunctionYield(node.id, checkYieldReturnValue) || hasNonFunctionYield(node.init, checkYieldReturnValue);
-      }
-    case 'YieldExpression':
-      {
-        if (checkYieldReturnValue) {
-          if (/** @type {import('eslint').Rule.Node} */node.parent?.type === 'VariableDeclarator') {
-            return true;
-          }
-          return false;
-        }
-
-        // void return does not count.
-        if (node.argument === null) {
-          return false;
-        }
-        return true;
-      }
-    default:
-      {
-        return false;
-      }
-  }
-};
-
-/**
- * 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 /** @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}
- */
-exports.hasYieldValue = hasYieldValue;
-const hasThrowValue = (node, innerFunction) => {
-  if (!node) {
-    return false;
-  }
-
-  // There are cases where a function may execute its inner function which
-  //   throws, but we're treating functions atomically rather than trying to
-  //   follow them
-  switch (node.type) {
-    case 'ArrowFunctionExpression':
-    case 'FunctionDeclaration':
-    case 'FunctionExpression':
-      {
-        return !innerFunction && !node.async && hasThrowValue(node.body, true);
-      }
-    case 'BlockStatement':
-      {
-        return node.body.some(bodyNode => {
-          return bodyNode.type !== 'FunctionDeclaration' && hasThrowValue(bodyNode);
-        });
-      }
-    case 'DoWhileStatement':
-    case 'ForInStatement':
-    case 'ForOfStatement':
-    case 'ForStatement':
-    case 'LabeledStatement':
-    case 'WhileStatement':
-    case 'WithStatement':
-      {
-        return hasThrowValue(node.body);
-      }
-    case 'IfStatement':
-      {
-        return hasThrowValue(node.consequent) || hasThrowValue(node.alternate);
-      }
-    case 'SwitchStatement':
-      {
-        return node.cases.some(someCase => {
-          return someCase.consequent.some(nde => {
-            return hasThrowValue(nde);
-          });
-        });
-      }
-    case 'ThrowStatement':
-      {
-        return true;
-      }
-
-    // We only consider it to throw an error if the catch or finally blocks throw an error.
-    case 'TryStatement':
-      {
-        return hasThrowValue(node.handler && node.handler.body) || hasThrowValue(node.finalizer);
-      }
-    default:
-      {
-        return false;
-      }
-  }
-};
-
-/**
- * @param {string} tag
- */
-/*
-const isInlineTag = (tag) => {
-  return /^(@link|@linkcode|@linkplain|@tutorial) /v.test(tag);
-};
-*/
-
-/**
- * Splits a `@template` tag's names on commas that separate template entries,
- * ignoring commas nested within a type expression so that default values such
- * as `[T=Record<string, unknown>]` are not split apart.
- *
- * Only `<`, `(` and `{` are treated as nesting: a comma within them is part of
- * a type (generic arguments, function params, object type). Square brackets are
- * deliberately not counted, since `[...]` is the optional/default wrapper in
- * which commas do separate entries, e.g. `[T=string, U=number]`.
- * @param {string} str
- * @returns {string[]}
- */
-exports.hasThrowValue = hasThrowValue;
-const splitTopLevelCommas = str => {
-  const parts = [];
-  let depth = 0;
-  let current = '';
-  for (const char of str) {
-    if (char === '<' || char === '{' || char === '(') {
-      depth++;
-    } else if (char === '>' || char === '}' || char === ')') {
-      depth = Math.max(0, depth - 1);
-    }
-    if (char === ',' && depth === 0) {
-      parts.push(current);
-      current = '';
-    } else {
-      current += char;
-    }
-  }
-  parts.push(current);
-  return parts;
-};
-
-/**
- * Parses GCC Generic/Template types
- * @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[]}
- */
-const parseClosureTemplateTag = tag => {
-  return splitTopLevelCommas(tag.name).map(type => {
-    return type.trim().replace(/^\[?(?<name>.*?)=.*$/v, '$<name>');
-  });
-};
-
-/**
- * @typedef {true|string[]} DefaultContexts
- */
-
-/**
- * Checks user option for `contexts` array, defaulting to
- * 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 {{
- *   contexts?: import('./iterateJsdoc.js').Context[]
- * }} settings
- * @returns {(string|import('./iterateJsdoc.js').ContextObject)[]}
- */
-exports.parseClosureTemplateTag = parseClosureTemplateTag;
-const enforcedContexts = (context, defaultContexts, settings) => {
-  const contexts = context.options[0]?.contexts || settings.contexts || (defaultContexts === true ? ['ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction'] : defaultContexts);
-  return contexts;
-};
-
-/**
- * @param {import('./iterateJsdoc.js').Context[]} contexts
- * @param {import('./iterateJsdoc.js').CheckJsdoc} checkJsdoc
- * @param {import('@es-joy/jsdoccomment').CommentHandler} [handler]
- * @returns {import('eslint').Rule.RuleListener}
- */
-exports.enforcedContexts = enforcedContexts;
-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 = {
-        lastIndex: idx,
-        selector: prop.context
-      };
-      if (prop.comment) {
-        property = /** @type {string} */prop.context;
-        value = checkJsdoc.bind(null, {
-          ...selInfo,
-          comment: prop.comment
-        },
-        /**
-         * @type {(jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean}
-         */
-        /** @type {import('@es-joy/jsdoccomment').CommentHandler} */
-        handler.bind(null, prop.comment));
-      } else {
-        property = /** @type {string} */prop.context;
-        value = checkJsdoc.bind(null, selInfo, null);
-      }
-    } else {
-      const selInfo = {
-        lastIndex: idx,
-        selector: prop
-      };
-      property = prop;
-      value = checkJsdoc.bind(null, selInfo, null);
-    }
-    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;
-};
-exports.getContextObject = getContextObject;
-const tagsWithNamesAndDescriptions = new Set(['arg', 'argument', 'param', 'prop', 'property', 'return',
-// These two are parsed by our custom parser as though having a `name`
-'returns', 'template']);
-
-/**
- * @typedef {{
- *   [key: string]: false|string|
- *     {message: string, replacement?: string}
- * }} TagNamePreference
- */
-
-/**
- * @param {import('eslint').Rule.RuleContext} context
- * @param {ParserMode|undefined} mode
- * @param {import('comment-parser').Spec[]} tags
- * @returns {{
- *   tagsWithNames: import('comment-parser').Spec[],
- *   tagsWithoutNames: import('comment-parser').Spec[]
- * }}
- */
-const getTagsByType = (context, mode, tags) => {
-  /**
-   * @type {import('comment-parser').Spec[]}
-   */
-  const tagsWithoutNames = [];
-  const tagsWithNames = tags.filter(tag => {
-    const {
-      tag: tagName
-    } = tag;
-    const tagWithName = tagsWithNamesAndDescriptions.has(tagName);
-    if (!tagWithName) {
-      tagsWithoutNames.push(tag);
-    }
-    return tagWithName;
-  });
-  return {
-    tagsWithNames,
-    tagsWithoutNames
-  };
-};
-
-/**
- * @param {import('eslint').SourceCode|{
- *   text: string
- * }} sourceCode
- * @returns {string}
- */
-exports.getTagsByType = getTagsByType;
-const getIndent = sourceCode => {
-  return (sourceCode.text.match(/^\n*([ \t]+)/v)?.[1] ?? '') + ' ';
-};
-
-/**
- * @param {import('eslint').Rule.Node|null} node
- * @returns {boolean}
- */
-exports.getIndent = getIndent;
-const isConstructor = node => {
-  return node?.type === 'MethodDefinition' && node.kind === 'constructor' || /** @type {import('@typescript-eslint/types').TSESTree.MethodDefinition} */node?.parent?.kind === 'constructor';
-};
-
-/**
- * @param {import('eslint').Rule.Node|null} node
- * @returns {boolean}
- */
-exports.isConstructor = isConstructor;
-const isGetter = node => {
-  return node !== null &&
-  /**
-   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
-   *   import('@typescript-eslint/types').TSESTree.Property}
-   */
-  node.parent?.kind === 'get';
-};
-
-/**
- * @param {import('eslint').Rule.Node|null} node
- * @returns {boolean}
- */
-exports.isGetter = isGetter;
-const isSetter = node => {
-  return node !== null &&
-  /**
-   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
-   *   import('@typescript-eslint/types').TSESTree.Property}
-   */
-  node.parent?.kind === 'set';
-};
-
-/**
- * @param {import('eslint').Rule.Node} node
- * @returns {boolean}
- */
-exports.isSetter = isSetter;
-const hasAccessorPair = node => {
-  const {
-    key,
-    kind: sourceKind,
-    type
-  } =
-  /**
-   * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
-   *   import('@typescript-eslint/types').TSESTree.Property}
-   */
-  node;
-  const sourceName = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */key.name;
-  const oppositeKind = sourceKind === 'get' ? 'set' : 'get';
-  const sibling = type === 'MethodDefinition' ? /** @type {import('@typescript-eslint/types').TSESTree.ClassBody} */node.parent.body : /** @type {import('@typescript-eslint/types').TSESTree.ObjectExpression} */node.parent.properties;
-  return sibling.some(child => {
-    const {
-      key: ky,
-      kind
-    } =
-    /**
-     * @type {import('@typescript-eslint/types').TSESTree.MethodDefinition|
-     *   import('@typescript-eslint/types').TSESTree.Property}
-     */
-    child;
-    const name = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ky.name;
-    return kind === oppositeKind && name === sourceName;
-  });
-};
-
-/**
- * @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
- * @returns {boolean}
- */
-const exemptSpeciaMethods = (jsdoc, node, context, schema) => {
-  /**
-   * @param {"checkGetters"|"checkSetters"|"checkConstructors"} prop
-   * @returns {boolean|"no-setter"|"no-getter"}
-   */
-  const hasSchemaOption = prop => {
-    const schemaProperties = schema[0].properties;
-    return context.options[0]?.[prop] ?? (schemaProperties[prop] && schemaProperties[prop].default);
-  };
-  const checkGetters = hasSchemaOption('checkGetters');
-  const checkSetters = hasSchemaOption('checkSetters');
-  return !hasSchemaOption('checkConstructors') && (isConstructor(node) || hasATag(jsdoc, ['class', 'constructor'])) || isGetter(node) && (!checkGetters || checkGetters === 'no-setter' && hasAccessorPair(/** @type {import('./iterateJsdoc.js').Node} */
-  /** @type {import('./iterateJsdoc.js').Node} */node.parent)) || isSetter(node) && (!checkSetters || checkSetters === 'no-getter' && hasAccessorPair(/** @type {import('./iterateJsdoc.js').Node} */
-  /** @type {import('./iterateJsdoc.js').Node} */node.parent));
-};
-
-/**
- * Since path segments may be unquoted (if matching a reserved word,
- * 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}
- */
-exports.exemptSpeciaMethods = exemptSpeciaMethods;
-const dropPathSegmentQuotes = str => {
-  return str.replaceAll(/\.(['"])(.*)\1/gv, '.$2');
-};
-
-/**
- * @param {string} name
- * @returns {(otherPathName: string) => boolean}
- */
-exports.dropPathSegmentQuotes = dropPathSegmentQuotes;
-const comparePaths = name => {
-  return otherPathName => {
-    return otherPathName === name || dropPathSegmentQuotes(otherPathName) === dropPathSegmentQuotes(name);
-  };
-};
-
-/**
- * @callback PathDoesNotBeginWith
- * @param {string} name
- * @param {string} otherPathName
- * @returns {boolean}
- */
-
-/** @type {PathDoesNotBeginWith} */
-exports.comparePaths = comparePaths;
-const pathDoesNotBeginWith = (name, otherPathName) => {
-  return !name.startsWith(otherPathName) && !dropPathSegmentQuotes(name).startsWith(dropPathSegmentQuotes(otherPathName));
-};
-
-/**
- * @param {string} regexString
- * @param {string} [requiredFlags]
- * @returns {RegExp}
- */
-exports.pathDoesNotBeginWith = pathDoesNotBeginWith;
-const getRegexFromString = (regexString, requiredFlags) => {
-  const match = regexString.match(/^\/(.*)\/([gimyvus]*)$/vs);
-  let flags = 'v';
-  let regex = regexString;
-  if (match) {
-    [, regex, flags] = match;
-    if (!flags) {
-      flags = 'v';
-    }
-  }
-  const uniqueFlags = [...new Set(flags + (requiredFlags || ''))];
-  flags = uniqueFlags.join('');
-  return new RegExp(regex, flags);
-};
-exports.getRegexFromString = getRegexFromString;
-const strictNativeTypes = exports.strictNativeTypes = ['undefined', 'null', 'boolean', 'number', 'bigint', 'string', 'symbol', 'object', 'Array', 'Function', 'Date', 'RegExp'];
-
-/**
- * @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
- * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
- * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType
- * @param {string} indent
- * @param {string} typeBracketSpacing
- */
-const rewireByParsedType = (jsdoc, tag, parsedType, indent, typeBracketSpacing = '') => {
-  const typeLines = (0, _jsdoccomment.stringify)(parsedType).split('\n');
-  const firstTypeLine = typeLines.shift();
-  const lastTypeLine = typeLines.pop();
-  const beginNameOrDescIdx = tag.source.findIndex(({
-    tokens
-  }) => {
-    return tokens.name || tokens.description;
-  });
-  const nameAndDesc = beginNameOrDescIdx === -1 ? null : tag.source.slice(beginNameOrDescIdx);
-  const initialNumber = tag.source[0].number;
-  const src = [
-  // Get inevitably present tag from first `tag.source`
-  {
-    number: initialNumber,
-    source: '',
-    tokens: {
-      ...tag.source[0].tokens,
-      ...(typeLines.length || lastTypeLine ? {
-        end: '',
-        name: '',
-        postName: '',
-        postType: ''
-      } : nameAndDesc ? {
-        name: nameAndDesc[0].tokens.name,
-        postType: ' '
-      } : {}),
-      type: '{' + typeBracketSpacing + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? typeBracketSpacing + '}' : '')
-    }
-  },
-  // Get any intervening type lines
-  ...(typeLines.length ? typeLines.map((typeLine, idx) => {
-    return {
-      number: initialNumber + idx + 1,
-      source: '',
-      tokens: {
-        // Grab any delimiter info from first item
-        ...tag.source[0].tokens,
-        delimiter: tag.source[0].tokens.delimiter === '/**' ? '*' : tag.source[0].tokens.delimiter,
-        end: '',
-        name: '',
-        postName: '',
-        postTag: '',
-        postType: '',
-        start: indent + ' ',
-        tag: '',
-        type: typeLine
-      }
-    };
-  }) : [])];
-
-  // Merge any final type line and name and description
-  if (
-  // Name and description may be already included if present with the tag
-  nameAndDesc && beginNameOrDescIdx > 0) {
-    if (typeLines.length || lastTypeLine !== undefined) {
-      src.push({
-        number: src.length + 1,
-        source: '',
-        tokens: {
-          ...nameAndDesc[0].tokens,
-          type: lastTypeLine + typeBracketSpacing + '}'
-        }
-      });
-    }
-    if (
-    // Get any remaining description lines
-    nameAndDesc.length > 1) {
-      src.push(...nameAndDesc.slice(1).map(({
-        source,
-        tokens
-      }, idx) => {
-        return {
-          number: src.length + idx + 2,
-          source,
-          tokens
-        };
-      }));
-    }
-  } else if (nameAndDesc) {
-    if ((typeLines.length || lastTypeLine !== undefined) && lastTypeLine) {
-      src.push({
-        number: src.length + 1,
-        source: '',
-        tokens: {
-          ...nameAndDesc[0].tokens,
-          delimiter: nameAndDesc[0].tokens.delimiter === '/**' ? '*' : nameAndDesc[0].tokens.delimiter,
-          postTag: '',
-          start: indent + ' ',
-          tag: '',
-          type: lastTypeLine + typeBracketSpacing + '}'
-        }
-      });
-    }
-    if (
-    // Get any remaining description lines
-    nameAndDesc.length > 1) {
-      src.push(...nameAndDesc.slice(1).map(({
-        source,
-        tokens
-      }, idx) => {
-        return {
-          number: src.length + idx + 2,
-          source,
-          tokens
-        };
-      }));
-    }
-  } else if (lastTypeLine) {
-    src.push({
-      number: src.length + 1,
-      source: '',
-      tokens: {
-        ...tag.source[0].tokens,
-        delimiter: tag.source[0].tokens.delimiter === '/**' ? '*' : tag.source[0].tokens.delimiter,
-        postTag: '',
-        start: indent + ' ',
-        tag: '',
-        type: lastTypeLine + typeBracketSpacing + '}'
-      }
-    });
-  }
-  tag.source = src;
-
-  // Properly rewire `jsdoc.source`
-  const firstTagIdx = jsdoc.source.findIndex(({
-    tokens: {
-      tag: tg
-    }
-  }) => {
-    return tg;
-  });
-  const initialEndSource = jsdoc.source.find(({
-    tokens: {
-      end
-    }
-  }) => {
-    return end;
-  });
-  jsdoc.source = [...jsdoc.source.slice(0, firstTagIdx), ...jsdoc.tags.flatMap(({
-    source
-  }) => {
-    return source;
-  })];
-  if (initialEndSource && !jsdoc.source.at(-1)?.tokens?.end) {
-    jsdoc.source.push(initialEndSource);
-  }
-};
-exports.rewireByParsedType = rewireByParsedType;
-//# sourceMappingURL=jsdocUtils.cjs.map