eslint-plugin-jsdoc
Version:
JSDoc linting rules for ESLint.
1 lines • 104 kB
Source Map (JSON)
{"version":3,"file":"iterateJsdoc.cjs","names":["jsdocUtils","_interopRequireWildcard","require","_jsdoccomment","_commentParser","_esquery","_interopRequireDefault","e","__esModule","default","t","WeakMap","r","n","o","i","f","__proto__","has","get","set","hasOwnProperty","call","Object","defineProperty","getOwnPropertyDescriptor","rewireSpecs","seedTokens","util","globalState","Map","getBasicUtils","context","mode","tagNamePreference","utils","reportSettings","message","report","loc","end","column","line","start","parseClosureTemplateTag","tag","pathDoesNotBeginWith","getPreferredTagNameObject","tagName","ret","getPreferredTagNameSimple","isObject","replacement","blocked","getUtils","node","jsdoc","jsdocNode","settings","sc","iteratingAll","ruleConfig","indent","ancestors","getAncestors","sourceCode","getSourceCode","augmentsExtendsReplacesDocs","ignoreReplacesDocs","implementsReplacesDocs","maxLines","minLines","overrideReplacesDocs","isIteratingFunction","includes","String","type","isVirtualFunction","Boolean","hasATag","stringify","tagBlock","specRewire","block","commentStringify","reportJSDoc","msg","handler","data","fixer","text","getText","lastLineBreakPos","slice","range","search","removeRange","test","charAt","replaceText","getRegexFromString","str","requiredFlags","getTagDescription","tg","returnArray","setTagDescription","matcher","setter","finalIdx","source","some","tokens","description","idx","getDescription","descriptions","lastDescriptionLine","tagsBegun","push","length","join","setBlockDescription","descLines","startIdx","endIdx","info","delimiter","postDelimiter","undefined","splice","setDescriptionLines","changeTag","src","entries","setTag","number","removeTag","tagIndex","removeEmptyBlock","tagSourceOffset","tagSource","tags","lastIndex","firstNumber","tagIdx","sourceIndex","findIndex","srcNumber","spliceCount","ending","spliceIdx","item","addTag","targetTagName","getFirstLine","firstLine","emptyTokens","prop","addLine","addLines","numLines","makeLine","makeLines","Array","from","lines","makeMultiline","lineEnd","name","postName","postTag","postType","trimEnd","flattenRoots","getFunctionParameterNames","useDefaultObjectProperties","hasParams","isGenerator","generator","value","declaration","isConstructor","getJsdocTagsDeep","getPreferredTagName","args","isValidTag","definedTags","names","hasTag","comparePaths","dropPathSegmentQuotes","avoidDocs","classHasTag","exemptSpeciaMethods","meta","schema","exemptedBy","options","getPresentTags","method","otherModeMaps","result","otherResult","otherModeMap","otherMode","tagMissingRequiredTypeOrNamepath","every","getTagStructureForMode","mde","structuredTags","mayBeUndefinedTypeTag","hasValueOrExecutorHasNonEmptyResolveValue","anyPromiseAsReturn","allBranches","hasYieldValue","hasYieldReturnValue","hasThrowValue","isAsync","async","getTags","tagList","filterTags","filter","filterAllTags","getAllTags","getTagsByType","hasOptionTag","getClassNode","reverse","find","parent","getClassJsdoc","classNode","classJsdocNode","getJSDocComment","parseComment","classJsdoc","forEachPreferredTag","arrayHandler","skipReportingBlockedTag","findContext","contexts","comment","foundContext","cntxt","esquery","matches","parse","visitorKeys","contextStr","getSettings","ignorePrivate","ignoreInternal","Number","preferredTypes","exemptDestructuredRootsFromChecks","setTagStructure","overrideTagStructure","error","exports","makeReport","commentNode","fix","jsdocLoc","lineNumber","colNumber","iterate","iterator","state","jsdocNde","checkInternal","checkPrivate","getIndentAndJSDoc","sourceLine","indentChar","indnt","repeat","jsdc","iterateAllJsdocs","additiveCommentContexts","trackedJsdocs","Set","callIterator","jsdocNodes","lastCall","selector","lastComment","settngs","exit","create","commentHandler","*:not(Program)","noTracking","nonComment","ste","add","Program:exit","allComments","getAllComments","untrackedJSdoc","checkFile","allComms","iterateJsdoc","metaType","TypeError","contextDefaults","contextSelected","matchContext","match","enforcedContexts","nonGlobalSettings","map","obj","hasPlainAny","hasObjectAny","ctxt","checkJsdoc","contextObject","getContextObject","bind"],"sources":["../src/iterateJsdoc.js"],"sourcesContent":["import * as jsdocUtils from './jsdocUtils.js';\nimport {\n commentHandler,\n getJSDocComment,\n parseComment,\n} from '@es-joy/jsdoccomment';\nimport {\n stringify as commentStringify,\n util,\n} from 'comment-parser';\nimport esquery from 'esquery';\n\n/**\n * @typedef {number} Integer\n */\n\n/**\n * @typedef {import('@es-joy/jsdoccomment').JsdocBlockWithInline} JsdocBlockWithInline\n */\n\n/**\n * @typedef {{\n * disallowName?: string,\n * allowName?: string,\n * context?: string,\n * comment?: string,\n * tags?: string[],\n * replacement?: string,\n * minimum?: Integer,\n * message?: string,\n * forceRequireReturn?: boolean\n * }} ContextObject\n */\n/**\n * @typedef {string|ContextObject} Context\n */\n\n/**\n * @callback CheckJsdoc\n * @param {{\n * lastIndex?: Integer,\n * isFunctionContext?: boolean,\n * selector?: string,\n * comment?: string\n * }} info\n * @param {null|((jsdoc: import('@es-joy/jsdoccomment').JsdocBlockWithInline) => boolean|undefined)} handler\n * @param {import('eslint').Rule.Node} node\n * @returns {void}\n */\n\n/**\n * @callback ForEachPreferredTag\n * @param {string} tagName\n * @param {(\n * matchingJsdocTag: import('@es-joy/jsdoccomment').JsdocTagWithInline,\n * targetTagName: string\n * ) => void} arrayHandler\n * @param {boolean} [skipReportingBlockedTag]\n * @returns {void}\n */\n\n/**\n * @callback ReportSettings\n * @param {string} message\n * @returns {void}\n */\n\n/**\n * @callback ParseClosureTemplateTag\n * @param {import('comment-parser').Spec} tag\n * @returns {string[]}\n */\n\n/**\n * @callback GetPreferredTagNameObject\n * @param {{\n * tagName: string\n * }} cfg\n * @returns {string|false|{\n * message: string;\n * replacement?: string|undefined\n * }|{\n * blocked: true,\n * tagName: string\n * }}\n */\n\n/**\n * @typedef {{\n * forEachPreferredTag: ForEachPreferredTag,\n * reportSettings: ReportSettings,\n * parseClosureTemplateTag: ParseClosureTemplateTag,\n * getPreferredTagNameObject: GetPreferredTagNameObject,\n * pathDoesNotBeginWith: import('./jsdocUtils.js').PathDoesNotBeginWith\n * }} BasicUtils\n */\n\n/**\n * @callback IsIteratingFunction\n * @returns {boolean}\n */\n\n/**\n * @callback IsVirtualFunction\n * @returns {boolean}\n */\n\n/**\n * @callback Stringify\n * @param {import('comment-parser').Block} tagBlock\n * @param {boolean} [specRewire]\n * @returns {string}\n */\n\n/**\n * @callback ReportJSDoc\n * @param {string} msg\n * @param {null|import('comment-parser').Spec|{line: Integer, column?: Integer}} [tag]\n * @param {(() => void)|null} [handler]\n * @param {boolean} [specRewire]\n * @param {undefined|{\n * [key: string]: string\n * }} [data]\n */\n\n/**\n * @callback GetRegexFromString\n * @param {string} str\n * @param {string} [requiredFlags]\n * @returns {RegExp}\n */\n\n/**\n * @callback GetTagDescription\n * @param {import('comment-parser').Spec} tg\n * @param {boolean} [returnArray]\n * @returns {string[]|string}\n */\n\n/**\n * @callback SetTagDescription\n * @param {import('comment-parser').Spec} tg\n * @param {RegExp} matcher\n * @param {(description: string) => string} setter\n * @returns {Integer}\n */\n\n/**\n * @callback GetDescription\n * @returns {{\n * description: string,\n * descriptions: string[],\n * lastDescriptionLine: Integer\n * }}\n */\n\n/**\n * @callback SetBlockDescription\n * @param {(\n * info: {\n * delimiter: string,\n * postDelimiter: string,\n * start: string\n * },\n * seedTokens: (\n * tokens?: Partial<import('comment-parser').Tokens>\n * ) => import('comment-parser').Tokens,\n * descLines: string[]\n * ) => import('comment-parser').Line[]} setter\n * @returns {void}\n */\n\n/**\n * @callback SetDescriptionLines\n * @param {RegExp} matcher\n * @param {(description: string) => string} setter\n * @returns {Integer}\n */\n\n/**\n * @callback ChangeTag\n * @param {import('comment-parser').Spec} tag\n * @param {...Partial<import('comment-parser').Tokens>} tokens\n * @returns {void}\n */\n\n/**\n * @callback SetTag\n * @param {import('comment-parser').Spec & {\n * line: Integer\n * }} tag\n * @param {Partial<import('comment-parser').Tokens>} [tokens]\n * @returns {void}\n */\n\n/**\n * @callback RemoveTag\n * @param {Integer} tagIndex\n * @param {{\n * removeEmptyBlock?: boolean,\n * tagSourceOffset?: Integer\n * }} [cfg]\n * @returns {void}\n */\n\n/**\n * @callback AddTag\n * @param {string} targetTagName\n * @param {Integer} [number]\n * @param {import('comment-parser').Tokens|{}} [tokens]\n * @returns {void}\n */\n\n/**\n * @callback GetFirstLine\n * @returns {Integer|undefined}\n */\n\n/**\n * @typedef {(\n * tokens?: Partial<import('comment-parser').Tokens> | undefined\n * ) => import('comment-parser').Tokens} SeedTokens\n */\n\n/**\n * Sets tokens to empty string.\n * @callback EmptyTokens\n * @param {import('comment-parser').Tokens} tokens\n * @returns {void}\n */\n\n/**\n * @callback AddLine\n * @param {Integer} sourceIndex\n * @param {Partial<import('comment-parser').Tokens>} tokens\n * @returns {void}\n */\n\n/**\n * @callback AddLines\n * @param {Integer} tagIndex\n * @param {Integer} tagSourceOffset\n * @param {Integer} numLines\n * @returns {void}\n */\n\n/**\n * @callback MakeMultiline\n * @returns {void}\n */\n\n/**\n * @callback GetFunctionParameterNames\n * @param {boolean} [useDefaultObjectProperties]\n * @returns {import('./jsdocUtils.js').ParamNameInfo[]}\n */\n\n/**\n * @callback HasParams\n * @returns {Integer}\n */\n\n/**\n * @callback IsGenerator\n * @returns {boolean}\n */\n\n/**\n * @callback IsConstructor\n * @returns {boolean}\n */\n\n/**\n * @callback GetJsdocTagsDeep\n * @param {string} tagName\n * @returns {false|{\n * idx: Integer,\n * name: string,\n * type: string\n * }[]}\n */\n\n/**\n * @callback GetPreferredTagName\n * @param {{\n * tagName: string,\n * skipReportingBlockedTag?: boolean,\n * allowObjectReturn?: boolean,\n * defaultMessage?: string\n * }} cfg\n * @returns {string|undefined|false|{\n * message: string;\n * replacement?: string|undefined;\n * }|{\n * blocked: true,\n * tagName: string\n * }}\n */\n\n/**\n * @callback IsValidTag\n * @param {string} name\n * @param {string[]} definedTags\n * @returns {boolean}\n */\n\n/**\n * @callback HasATag\n * @param {string[]} names\n * @returns {boolean}\n */\n\n/**\n * @callback HasTag\n * @param {string} name\n * @returns {boolean}\n */\n\n/**\n * @callback ComparePaths\n * @param {string} name\n * @returns {(otherPathName: string) => boolean}\n */\n\n/**\n * @callback DropPathSegmentQuotes\n * @param {string} name\n * @returns {string}\n */\n\n/**\n * @callback AvoidDocs\n * @returns {boolean}\n */\n\n/**\n * @callback TagMightHaveNamePositionTypePosition\n * @param {string} tagName\n * @param {import('./getDefaultTagStructureForMode.js').\n * TagStructure[]} [otherModeMaps]\n * @returns {boolean|{otherMode: true}}\n */\n\n/**\n * @callback TagMustHave\n * @param {string} tagName\n * @param {import('./getDefaultTagStructureForMode.js').\n * TagStructure[]} otherModeMaps\n * @returns {boolean|{\n * otherMode: false\n * }}\n */\n\n/**\n * @callback TagMissingRequiredTypeOrNamepath\n * @param {import('comment-parser').Spec} tag\n * @param {import('./getDefaultTagStructureForMode.js').\n * TagStructure[]} otherModeMaps\n * @returns {boolean|{\n * otherMode: false\n * }}\n */\n\n/**\n * @callback IsNamepathX\n * @param {string} tagName\n * @returns {boolean}\n */\n\n/**\n * @callback GetTagStructureForMode\n * @param {import('./jsdocUtils.js').ParserMode} mde\n * @returns {import('./getDefaultTagStructureForMode.js').TagStructure}\n */\n\n/**\n * @callback MayBeUndefinedTypeTag\n * @param {import('comment-parser').Spec} tag\n * @returns {boolean}\n */\n\n/**\n * @callback HasValueOrExecutorHasNonEmptyResolveValue\n * @param {boolean} anyPromiseAsReturn\n * @param {boolean} [allBranches]\n * @returns {boolean}\n */\n\n/**\n * @callback HasYieldValue\n * @returns {boolean}\n */\n\n/**\n * @callback HasYieldReturnValue\n * @returns {boolean}\n */\n\n/**\n * @callback HasThrowValue\n * @returns {boolean}\n */\n\n/**\n * @callback IsAsync\n * @returns {boolean|undefined}\n */\n\n/**\n * @callback GetTags\n * @param {string} tagName\n * @returns {import('comment-parser').Spec[]}\n */\n\n/**\n * @callback GetPresentTags\n * @param {string[]} tagList\n * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}\n */\n\n/**\n * @callback FilterTags\n * @param {(tag: import('@es-joy/jsdoccomment').JsdocTagWithInline) => boolean} filter\n * @returns {import('@es-joy/jsdoccomment').JsdocTagWithInline[]}\n */\n\n/**\n * @callback FilterAllTags\n * @param {(tag: (import('comment-parser').Spec|\n * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)) => boolean} filter\n * @returns {(import('comment-parser').Spec|\n * import('@es-joy/jsdoccomment').JsdocInlineTagNoType)[]}\n */\n\n/**\n * @callback GetTagsByType\n * @param {import('comment-parser').Spec[]} tags\n * @returns {{\n * tagsWithNames: import('comment-parser').Spec[],\n * tagsWithoutNames: import('comment-parser').Spec[]\n * }}\n */\n\n/**\n * @callback HasOptionTag\n * @param {string} tagName\n * @returns {boolean}\n */\n\n/**\n * @callback GetClassNode\n * @returns {Node|null}\n */\n\n/**\n * @callback GetClassJsdoc\n * @returns {null|JsdocBlockWithInline}\n */\n\n/**\n * @callback ClassHasTag\n * @param {string} tagName\n * @returns {boolean}\n */\n\n/**\n * @callback FindContext\n * @param {Context[]} contexts\n * @param {string|undefined} comment\n * @returns {{\n * foundContext: Context|undefined,\n * contextStr: string\n * }}\n */\n\n/**\n * @typedef {BasicUtils & {\n * isIteratingFunction: IsIteratingFunction,\n * isVirtualFunction: IsVirtualFunction,\n * stringify: Stringify,\n * reportJSDoc: ReportJSDoc,\n * getRegexFromString: GetRegexFromString,\n * getTagDescription: GetTagDescription,\n * setTagDescription: SetTagDescription,\n * getDescription: GetDescription,\n * setBlockDescription: SetBlockDescription,\n * setDescriptionLines: SetDescriptionLines,\n * changeTag: ChangeTag,\n * setTag: SetTag,\n * removeTag: RemoveTag,\n * addTag: AddTag,\n * getFirstLine: GetFirstLine,\n * seedTokens: SeedTokens,\n * emptyTokens: EmptyTokens,\n * addLine: AddLine,\n * addLines: AddLines,\n * makeMultiline: MakeMultiline,\n * flattenRoots: import('./jsdocUtils.js').FlattenRoots,\n * getFunctionParameterNames: GetFunctionParameterNames,\n * hasParams: HasParams,\n * isGenerator: IsGenerator,\n * isConstructor: IsConstructor,\n * getJsdocTagsDeep: GetJsdocTagsDeep,\n * getPreferredTagName: GetPreferredTagName,\n * isValidTag: IsValidTag,\n * hasATag: HasATag,\n * hasTag: HasTag,\n * comparePaths: ComparePaths,\n * dropPathSegmentQuotes: DropPathSegmentQuotes,\n * avoidDocs: AvoidDocs,\n * tagMightHaveNamePosition: TagMightHaveNamePositionTypePosition,\n * tagMightHaveTypePosition: TagMightHaveNamePositionTypePosition,\n * tagMustHaveNamePosition: TagMustHave,\n * tagMustHaveTypePosition: TagMustHave,\n * tagMissingRequiredTypeOrNamepath: TagMissingRequiredTypeOrNamepath,\n * isNamepathDefiningTag: IsNamepathX,\n * isNamepathReferencingTag: IsNamepathX,\n * isNamepathOrUrlReferencingTag: IsNamepathX,\n * tagMightHaveNamepath: IsNamepathX,\n * getTagStructureForMode: GetTagStructureForMode,\n * mayBeUndefinedTypeTag: MayBeUndefinedTypeTag,\n * hasValueOrExecutorHasNonEmptyResolveValue: HasValueOrExecutorHasNonEmptyResolveValue,\n * hasYieldValue: HasYieldValue,\n * hasYieldReturnValue: HasYieldReturnValue,\n * hasThrowValue: HasThrowValue,\n * isAsync: IsAsync,\n * getTags: GetTags,\n * getPresentTags: GetPresentTags,\n * filterTags: FilterTags,\n * filterAllTags: FilterAllTags,\n * getTagsByType: GetTagsByType,\n * hasOptionTag: HasOptionTag,\n * getClassNode: GetClassNode,\n * getClassJsdoc: GetClassJsdoc,\n * classHasTag: ClassHasTag,\n * findContext: FindContext\n * }} Utils\n */\n\nconst {\n rewireSpecs,\n seedTokens,\n} = util;\n\n// todo: Change these `any` types once importing types properly.\n\n/**\n * Should use ESLint rule's typing.\n * @typedef {import('eslint').Rule.RuleMetaData} EslintRuleMeta\n */\n\n/**\n * A plain object for tracking state as needed by rules across iterations.\n * @typedef {{\n * globalTags: {},\n * hasDuplicates: {\n * [key: string]: boolean\n * },\n * selectorMap: {\n * [selector: string]: {\n * [comment: string]: Integer\n * }\n * },\n * hasTag: {\n * [key: string]: boolean\n * },\n * hasNonComment: number,\n * hasNonCommentBeforeTag: {\n * [key: string]: boolean|number\n * }\n * }} StateObject\n */\n\n/**\n * The Node AST as supplied by the parser.\n * @typedef {import('eslint').Rule.Node} Node\n */\n\n/*\nconst {\n align as commentAlign,\n flow: commentFlow,\n indent: commentIndent,\n} = transforms;\n*/\n\nconst globalState = new Map();\n/**\n * @param {import('eslint').Rule.RuleContext} context\n * @param {{\n * tagNamePreference?: import('./jsdocUtils.js').TagNamePreference,\n * mode?: import('./jsdocUtils.js').ParserMode\n * }} cfg\n * @returns {BasicUtils}\n */\nconst getBasicUtils = (context, {\n mode,\n tagNamePreference,\n}) => {\n /** @type {BasicUtils} */\n const utils = {};\n\n /** @type {ReportSettings} */\n utils.reportSettings = (message) => {\n context.report({\n loc: {\n end: {\n column: 1,\n line: 1,\n },\n start: {\n column: 1,\n line: 1,\n },\n },\n message,\n });\n };\n\n /** @type {ParseClosureTemplateTag} */\n utils.parseClosureTemplateTag = (tag) => {\n return jsdocUtils.parseClosureTemplateTag(tag);\n };\n\n utils.pathDoesNotBeginWith = jsdocUtils.pathDoesNotBeginWith;\n\n /** @type {GetPreferredTagNameObject} */\n utils.getPreferredTagNameObject = ({\n tagName,\n }) => {\n const ret = jsdocUtils.getPreferredTagNameSimple(\n tagName,\n /** @type {import('./jsdocUtils.js').ParserMode} */ (mode),\n tagNamePreference,\n context,\n );\n const isObject = ret && typeof ret === 'object';\n if (ret === false || (isObject && !ret.replacement)) {\n return {\n blocked: true,\n tagName,\n };\n }\n\n return ret;\n };\n\n return utils;\n};\n\n/**\n * @callback Report\n * @param {string} message\n * @param {import('eslint').Rule.ReportFixer|null} [fix]\n * @param {null|\n * {line?: Integer, column?: Integer}|\n * import('comment-parser').Spec & {line?: Integer}\n * } [jsdocLoc]\n * @param {undefined|{\n * [key: string]: string\n * }} [data]\n * @returns {void}\n */\n\n/**\n * @param {Node|null} node\n * @param {JsdocBlockWithInline} jsdoc\n * @param {import('eslint').AST.Token} jsdocNode\n * @param {Settings} settings\n * @param {Report} report\n * @param {import('eslint').Rule.RuleContext} context\n * @param {import('eslint').SourceCode} sc\n * @param {boolean|undefined} iteratingAll\n * @param {RuleConfig} ruleConfig\n * @param {string} indent\n * @returns {Utils}\n */\nconst getUtils = (\n node,\n jsdoc,\n jsdocNode,\n settings,\n report,\n context,\n sc,\n iteratingAll,\n ruleConfig,\n indent,\n) => {\n const ancestors = /** @type {import('eslint').Rule.Node[]} */ (node ?\n (sc.getAncestors ?\n (\n sc.getAncestors(node)\n /* c8 ignore next 4 */\n ) :\n (\n context.getAncestors()\n )) :\n []);\n\n /* c8 ignore next -- Fallback to deprecated method */\n const {\n sourceCode = context.getSourceCode(),\n } = context;\n\n const utils = /** @type {Utils} */ (getBasicUtils(context, settings));\n\n const {\n augmentsExtendsReplacesDocs,\n ignoreReplacesDocs,\n implementsReplacesDocs,\n maxLines,\n minLines,\n mode,\n overrideReplacesDocs,\n tagNamePreference,\n } = settings;\n\n /** @type {IsIteratingFunction} */\n utils.isIteratingFunction = () => {\n return !iteratingAll || [\n 'ArrowFunctionExpression',\n 'FunctionDeclaration',\n 'FunctionExpression',\n 'MethodDefinition',\n ].includes(String(node && node.type));\n };\n\n /** @type {IsVirtualFunction} */\n utils.isVirtualFunction = () => {\n return Boolean(iteratingAll) && utils.hasATag([\n 'callback', 'function', 'func', 'method',\n ]);\n };\n\n /** @type {Stringify} */\n utils.stringify = (tagBlock, specRewire) => {\n let block;\n if (specRewire) {\n block = rewireSpecs(tagBlock);\n }\n\n return commentStringify(/** @type {import('comment-parser').Block} */ (\n specRewire ? block : tagBlock));\n };\n\n /** @type {ReportJSDoc} */\n utils.reportJSDoc = (msg, tag, handler, specRewire, data) => {\n report(msg, handler ? /** @type {import('eslint').Rule.ReportFixer} */ (\n fixer,\n ) => {\n handler();\n const replacement = utils.stringify(jsdoc, specRewire);\n\n if (!replacement) {\n const text = sourceCode.getText();\n const lastLineBreakPos = text.slice(\n 0, jsdocNode.range[0],\n ).search(/\\n[ \\t]*$/u);\n if (lastLineBreakPos > -1) {\n return fixer.removeRange([\n lastLineBreakPos, jsdocNode.range[1],\n ]);\n }\n\n return fixer.removeRange(\n (/\\s/u).test(text.charAt(jsdocNode.range[1])) ?\n [\n jsdocNode.range[0], jsdocNode.range[1] + 1,\n ] :\n jsdocNode.range,\n );\n }\n\n return fixer.replaceText(jsdocNode, replacement);\n } : null, tag, data);\n };\n\n /** @type {GetRegexFromString} */\n utils.getRegexFromString = (str, requiredFlags) => {\n return jsdocUtils.getRegexFromString(str, requiredFlags);\n };\n\n /** @type {GetTagDescription} */\n utils.getTagDescription = (tg, returnArray) => {\n return jsdocUtils.getTagDescription(tg, returnArray);\n };\n\n /** @type {SetTagDescription} */\n utils.setTagDescription = (tg, matcher, setter) => {\n let finalIdx = 0;\n tg.source.some(({\n tokens: {\n description,\n },\n }, idx) => {\n if (description && matcher.test(description)) {\n tg.source[idx].tokens.description = setter(description);\n finalIdx = idx;\n return true;\n }\n\n return false;\n });\n\n return finalIdx;\n };\n\n /** @type {GetDescription} */\n utils.getDescription = () => {\n /** @type {string[]} */\n const descriptions = [];\n let lastDescriptionLine = 0;\n let tagsBegun = false;\n jsdoc.source.some(({\n tokens: {\n description,\n end,\n tag,\n },\n }, idx) => {\n if (tag) {\n tagsBegun = true;\n }\n\n if (idx && (tag || end)) {\n lastDescriptionLine = idx - 1;\n if (!tagsBegun && description) {\n descriptions.push(description);\n }\n\n return true;\n }\n\n if (!tagsBegun && (idx || description)) {\n descriptions.push(description || (descriptions.length ? '' : '\\n'));\n }\n\n return false;\n });\n\n return {\n description: descriptions.join('\\n'),\n descriptions,\n lastDescriptionLine,\n };\n };\n\n /** @type {SetBlockDescription} */\n utils.setBlockDescription = (setter) => {\n /** @type {string[]} */\n const descLines = [];\n /**\n * @type {undefined|Integer}\n */\n let startIdx;\n /**\n * @type {undefined|Integer}\n */\n let endIdx;\n\n /**\n * @type {undefined|{\n * delimiter: string,\n * postDelimiter: string,\n * start: string\n * }}\n */\n let info;\n\n jsdoc.source.some(({\n tokens: {\n delimiter,\n description,\n end,\n postDelimiter,\n start,\n tag,\n },\n }, idx) => {\n if (delimiter === '/**') {\n return false;\n }\n\n if (startIdx === undefined) {\n startIdx = idx;\n info = {\n delimiter,\n postDelimiter,\n start,\n };\n }\n\n if (tag || end) {\n endIdx = idx;\n return true;\n }\n\n descLines.push(description);\n return false;\n });\n\n /* c8 ignore else -- Won't be called if missing */\n if (descLines.length) {\n jsdoc.source.splice(\n /** @type {Integer} */ (startIdx),\n /** @type {Integer} */ (endIdx) - /** @type {Integer} */ (startIdx),\n ...setter(\n /**\n * @type {{\n * delimiter: string,\n * postDelimiter: string,\n * start: string\n * }}\n */\n (info),\n seedTokens,\n descLines,\n ),\n );\n }\n };\n\n /** @type {SetDescriptionLines} */\n utils.setDescriptionLines = (matcher, setter) => {\n let finalIdx = 0;\n jsdoc.source.some(({\n tokens: {\n description,\n end,\n tag,\n },\n }, idx) => {\n /* c8 ignore next 3 -- Already checked */\n if (idx && (tag || end)) {\n return true;\n }\n\n if (description && matcher.test(description)) {\n jsdoc.source[idx].tokens.description = setter(description);\n finalIdx = idx;\n return true;\n }\n\n return false;\n });\n\n return finalIdx;\n };\n\n /** @type {ChangeTag} */\n utils.changeTag = (tag, ...tokens) => {\n for (const [\n idx,\n src,\n ] of tag.source.entries()) {\n src.tokens = {\n ...src.tokens,\n ...tokens[idx],\n };\n }\n };\n\n /** @type {SetTag} */\n utils.setTag = (tag, tokens) => {\n tag.source = [\n {\n number: tag.line,\n // Or tag.source[0].number?\n source: '',\n tokens: seedTokens({\n delimiter: '*',\n postDelimiter: ' ',\n start: indent + ' ',\n tag: '@' + tag.tag,\n ...tokens,\n }),\n },\n ];\n };\n\n /** @type {RemoveTag} */\n utils.removeTag = (tagIndex, {\n removeEmptyBlock = false,\n tagSourceOffset = 0,\n } = {}) => {\n const {\n source: tagSource,\n } = jsdoc.tags[tagIndex];\n /** @type {Integer|undefined} */\n let lastIndex;\n const firstNumber = jsdoc.source[0].number;\n tagSource.some(({\n number,\n }, tagIdx) => {\n const sourceIndex = jsdoc.source.findIndex(({\n number: srcNumber,\n }) => {\n return number === srcNumber;\n });\n // c8 ignore else\n if (sourceIndex > -1) {\n let spliceCount = 1;\n tagSource.slice(tagIdx + 1).some(({\n tokens: {\n end: ending,\n tag,\n },\n }) => {\n if (!tag && !ending) {\n spliceCount++;\n\n return false;\n }\n\n return true;\n });\n\n const spliceIdx = sourceIndex + tagSourceOffset;\n\n const {\n delimiter,\n end,\n } = jsdoc.source[spliceIdx].tokens;\n\n if (\n spliceIdx === 0 && jsdoc.tags.length >= 2 ||\n !removeEmptyBlock && (end || delimiter === '/**')\n ) {\n const {\n tokens,\n } = jsdoc.source[spliceIdx];\n for (const item of [\n 'postDelimiter',\n 'tag',\n 'postTag',\n 'type',\n 'postType',\n 'name',\n 'postName',\n 'description',\n ]) {\n tokens[\n /**\n * @type {\"postDelimiter\"|\"tag\"|\"type\"|\"postType\"|\n * \"postTag\"|\"name\"|\"postName\"|\"description\"}\n */ (\n item\n )\n ] = '';\n }\n } else {\n jsdoc.source.splice(spliceIdx, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));\n tagSource.splice(tagIdx + tagSourceOffset, spliceCount - tagSourceOffset + (spliceIdx ? 0 : jsdoc.source.length));\n }\n\n lastIndex = sourceIndex;\n\n return true;\n }\n /* c8 ignore next 2 */\n // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8\n return false;\n });\n for (const [\n idx,\n src,\n ] of jsdoc.source.slice(lastIndex).entries()) {\n src.number = firstNumber + /** @type {Integer} */ (lastIndex) + idx;\n }\n\n // Todo: Once rewiring of tags may be fixed in comment-parser to reflect\n // missing tags, this step should be added here (so that, e.g.,\n // if accessing `jsdoc.tags`, such as to add a new tag, the\n // correct information will be available)\n };\n\n /** @type {AddTag} */\n utils.addTag = (\n targetTagName,\n number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({\n tokens: {\n tag,\n },\n }) => {\n return tag;\n }) - 1) + 1,\n tokens = {},\n ) => {\n jsdoc.source.splice(number, 0, {\n number,\n source: '',\n tokens: seedTokens({\n delimiter: '*',\n postDelimiter: ' ',\n start: indent + ' ',\n tag: `@${targetTagName}`,\n ...tokens,\n }),\n });\n for (const src of jsdoc.source.slice(number + 1)) {\n src.number++;\n }\n };\n\n /** @type {GetFirstLine} */\n utils.getFirstLine = () => {\n let firstLine;\n for (const {\n number,\n tokens: {\n tag,\n },\n } of jsdoc.source) {\n if (tag) {\n firstLine = number;\n break;\n }\n }\n\n return firstLine;\n };\n\n /** @type {SeedTokens} */\n utils.seedTokens = seedTokens;\n\n /** @type {EmptyTokens} */\n utils.emptyTokens = (tokens) => {\n for (const prop of [\n 'start',\n 'postDelimiter',\n 'tag',\n 'type',\n 'postType',\n 'postTag',\n 'name',\n 'postName',\n 'description',\n 'end',\n 'lineEnd',\n ]) {\n tokens[\n /**\n * @type {\"start\"|\"postDelimiter\"|\"tag\"|\"type\"|\"postType\"|\n * \"postTag\"|\"name\"|\"postName\"|\"description\"|\"end\"|\"lineEnd\"}\n */ (\n prop\n )\n ] = '';\n }\n };\n\n /** @type {AddLine} */\n utils.addLine = (sourceIndex, tokens) => {\n const number = (jsdoc.source[sourceIndex - 1]?.number || 0) + 1;\n jsdoc.source.splice(sourceIndex, 0, {\n number,\n source: '',\n tokens: seedTokens(tokens),\n });\n\n for (const src of jsdoc.source.slice(number + 1)) {\n src.number++;\n }\n // If necessary, we can rewire the tags (misnamed method)\n // rewireSource(jsdoc);\n };\n\n /** @type {AddLines} */\n utils.addLines = (tagIndex, tagSourceOffset, numLines) => {\n const {\n source: tagSource,\n } = jsdoc.tags[tagIndex];\n /** @type {Integer|undefined} */\n let lastIndex;\n const firstNumber = jsdoc.source[0].number;\n tagSource.some(({\n number,\n }) => {\n const makeLine = () => {\n return {\n number,\n source: '',\n tokens: seedTokens({\n delimiter: '*',\n start: indent + ' ',\n }),\n };\n };\n\n const makeLines = () => {\n return Array.from({\n length: numLines,\n }, makeLine);\n };\n\n const sourceIndex = jsdoc.source.findIndex(({\n number: srcNumber,\n tokens: {\n end,\n },\n }) => {\n return number === srcNumber && !end;\n });\n // c8 ignore else\n if (sourceIndex > -1) {\n const lines = makeLines();\n jsdoc.source.splice(sourceIndex + tagSourceOffset, 0, ...lines);\n\n // tagSource.splice(tagIdx + 1, 0, ...makeLines());\n lastIndex = sourceIndex;\n\n return true;\n }\n /* c8 ignore next 2 */\n // eslint-disable-next-line @stylistic/padding-line-between-statements -- c8\n return false;\n });\n\n for (const [\n idx,\n src,\n ] of jsdoc.source.slice(lastIndex).entries()) {\n src.number = firstNumber + /** @type {Integer} */ (lastIndex) + idx;\n }\n };\n\n /** @type {MakeMultiline} */\n utils.makeMultiline = () => {\n const {\n source: [\n {\n tokens,\n },\n ],\n } = jsdoc;\n const {\n description,\n lineEnd,\n name,\n postDelimiter,\n tag,\n type,\n } = tokens;\n\n let {\n tokens: {\n postName,\n postTag,\n postType,\n },\n } = jsdoc.source[0];\n\n // Strip trailing leftovers from single line ending\n if (!description) {\n if (postName) {\n postName = '';\n } else if (postType) {\n postType = '';\n } else /* c8 ignore else -- `comment-parser` prevents empty blocks currently per https://github.com/syavorsky/comment-parser/issues/128 */ if (postTag) {\n postTag = '';\n }\n }\n\n utils.emptyTokens(tokens);\n\n utils.addLine(1, {\n delimiter: '*',\n\n // If a description were present, it may have whitespace attached\n // due to being at the end of the single line\n description: description.trimEnd(),\n name,\n postDelimiter,\n postName,\n postTag,\n postType,\n start: indent + ' ',\n tag,\n type,\n });\n utils.addLine(2, {\n end: '*/',\n lineEnd,\n start: indent + ' ',\n });\n };\n\n /**\n * @type {import('./jsdocUtils.js').FlattenRoots}\n */\n utils.flattenRoots = jsdocUtils.flattenRoots;\n\n /** @type {GetFunctionParameterNames} */\n utils.getFunctionParameterNames = (useDefaultObjectProperties) => {\n return jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties);\n };\n\n /** @type {HasParams} */\n utils.hasParams = () => {\n return jsdocUtils.hasParams(/** @type {Node} */ (node));\n };\n\n /** @type {IsGenerator} */\n utils.isGenerator = () => {\n return node !== null && Boolean(\n /**\n * @type {import('estree').FunctionDeclaration|\n * import('estree').FunctionExpression}\n */ (node).generator ||\n node.type === 'MethodDefinition' && node.value.generator ||\n [\n 'ExportDefaultDeclaration', 'ExportNamedDeclaration',\n ].includes(node.type) &&\n /** @type {import('estree').FunctionDeclaration} */\n (\n /**\n * @type {import('estree').ExportNamedDeclaration|\n * import('estree').ExportDefaultDeclaration}\n */ (node).declaration\n )?.generator,\n );\n };\n\n /** @type {IsConstructor} */\n utils.isConstructor = () => {\n return jsdocUtils.isConstructor(/** @type {Node} */ (node));\n };\n\n /** @type {GetJsdocTagsDeep} */\n utils.getJsdocTagsDeep = (tagName) => {\n const name = /** @type {string|false} */ (utils.getPreferredTagName({\n tagName,\n }));\n if (!name) {\n return false;\n }\n\n return jsdocUtils.getJsdocTagsDeep(jsdoc, name);\n };\n\n /** @type {GetPreferredTagName} */\n utils.getPreferredTagName = (args) => {\n return jsdocUtils.getPreferredTagName(\n jsdoc, {\n ...args,\n context,\n mode,\n report,\n tagNamePreference,\n },\n );\n };\n\n /** @type {IsValidTag} */\n utils.isValidTag = (name, definedTags) => {\n return jsdocUtils.isValidTag(context, mode, name, definedTags);\n };\n\n /** @type {HasATag} */\n utils.hasATag = (names) => {\n return jsdocUtils.hasATag(jsdoc, names);\n };\n\n /** @type {HasTag} */\n utils.hasTag = (name) => {\n return jsdocUtils.hasTag(jsdoc, name);\n };\n\n /** @type {ComparePaths} */\n utils.comparePaths = (name) => {\n return jsdocUtils.comparePaths(name);\n };\n\n /** @type {DropPathSegmentQuotes} */\n utils.dropPathSegmentQuotes = (name) => {\n return jsdocUtils.dropPathSegmentQuotes(name);\n };\n\n /** @type {AvoidDocs} */\n utils.avoidDocs = () => {\n if (\n ignoreReplacesDocs !== false &&\n (utils.hasTag('ignore') || utils.classHasTag('ignore')) ||\n overrideReplacesDocs !== false &&\n (utils.hasTag('override') || utils.classHasTag('override')) ||\n implementsReplacesDocs !== false &&\n (utils.hasTag('implements') || utils.classHasTag('implements')) ||\n\n augmentsExtendsReplacesDocs &&\n (utils.hasATag([\n 'augments', 'extends',\n ]) ||\n utils.classHasTag('augments') ||\n utils.classHasTag('extends'))) {\n return true;\n }\n\n if (jsdocUtils.exemptSpeciaMethods(\n jsdoc,\n node,\n context,\n /** @type {import('json-schema').JSONSchema4|import('json-schema').JSONSchema4[]} */ (\n ruleConfig.meta.schema\n ),\n )) {\n return true;\n }\n\n const exemptedBy = context.options[0]?.exemptedBy ?? [\n 'inheritDoc',\n ...mode === 'closure' ? [] : [\n 'inheritdoc',\n ],\n ];\n if (exemptedBy.length && utils.getPresentTags(exemptedBy).length) {\n return true;\n }\n\n return false;\n };\n\n for (const method of [\n 'tagMightHaveNamePosition',\n 'tagMightHaveTypePosition',\n ]) {\n /** @type {TagMightHaveNamePositionTypePosition} */\n utils[\n /** @type {\"tagMightHaveNamePosition\"|\"tagMightHaveTypePosition\"} */ (\n method\n )\n ] = (tagName, otherModeMaps) => {\n const result = jsdocUtils[\n /** @type {\"tagMightHaveNamePosition\"|\"tagMightHaveTypePosition\"} */\n (method)\n ](tagName);\n if (result) {\n return true;\n }\n\n if (!otherModeMaps) {\n return false;\n }\n\n const otherResult = otherModeMaps.some((otherModeMap) => {\n return jsdocUtils[\n /** @type {\"tagMightHaveNamePosition\"|\"tagMightHaveTypePosition\"} */\n (method)\n ](tagName, otherModeMap);\n });\n\n return otherResult ? {\n otherMode: true,\n } : false;\n };\n }\n\n /** @type {TagMissingRequiredTypeOrNamepath} */\n utils.tagMissingRequiredTypeOrNamepath = (tagName, otherModeMaps) => {\n const result = jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName);\n if (!result) {\n return false;\n }\n\n const otherResult = otherModeMaps.every((otherModeMap) => {\n return jsdocUtils.tagMissingRequiredTypeOrNamepath(tagName, otherModeMap);\n });\n\n return otherResult ? true : {\n otherMode: false,\n };\n };\n\n for (const method of [\n 'tagMustHaveNamePosition',\n 'tagMustHaveTypePosition',\n ]) {\n /** @type {TagMustHave} */\n utils[\n /** @type {\"tagMustHaveNamePosition\"|\"tagMustHaveTypePosition\"} */\n (method)\n ] = (tagName, otherModeMaps) => {\n const result = jsdocUtils[\n /** @type {\"tagMustHaveNamePosition\"|\"tagMustHaveTypePosition\"} */\n (method)\n ](tagName);\n if (!result) {\n return false;\n }\n\n // if (!otherModeMaps) { return true; }\n\n const otherResult = otherModeMaps.every((otherModeMap) => {\n return jsdocUtils[\n /** @type {\"tagMustHaveNamePosition\"|\"tagMustHaveTypePosition\"} */\n (method)\n ](tagName, otherModeMap);\n });\n\n return otherResult ? true : {\n otherMode: false,\n };\n };\n }\n\n for (const method of [\n 'isNamepathDefiningTag',\n 'isNamepathReferencingTag',\n 'isNamepathOrUrlReferencingTag',\n 'tagMightHaveNamepath',\n ]) {\n /** @type {IsNamepathX} */\n utils[\n /** @type {\"isNamepathDefiningTag\"|\"isNamepathReferencingTag\"|\"isNamepathOrUrlReferencingTag\"|\"tagMightHaveNamepath\"} */ (\n method\n )] = (tagName) => {\n return jsdocUtils[\n /** @type {\"isNamepathDefiningTag\"|\"isNamepathReferencingTag\"|\"isNamepathOrUrlReferencingTag\"|\"tagMightHaveNamepath\"} */\n (method)\n ](tagName);\n };\n }\n\n /** @type {GetTagStructureForMode} */\n utils.getTagStructureForMode = (mde) => {\n return jsdocUtils.getTagStructureForMode(mde, settings.structuredTags);\n };\n\n /** @type {MayBeUndefinedTypeTag} */\n utils.mayBeUndefinedTypeTag = (tag) => {\n return jsdocUtils.mayBeUndefinedTypeTag(tag, settings.mode);\n };\n\n /** @type {HasValueOrExecutorHasNonEmptyResolveValue} */\n utils.hasValueOrExecutorHasNonEmptyResolveValue = (anyPromiseAsReturn, allBranches) => {\n return jsdocUtils.hasValueOrExecutorHasNonEmptyResolveValue(\n /** @type {Node} */ (node), anyPromiseAsReturn, allBranches,\n );\n };\n\n /** @type {HasYieldValue} */\n utils.hasYieldValue = () => {\n if ([\n 'ExportDefaultDeclaration', 'ExportNamedDeclaration',\n ].includes(/** @type {Node} */ (node).type)) {\n return jsdocUtils.hasYieldValue(\n /** @type {import('estree').Declaration|import('estree').Expression} */ (\n /** @type {import('estree').ExportNamedDeclaration|import('estree').ExportDefaultDeclaration} */\n (node).declaration\n ),\n );\n }\n\n return jsdocUtils.hasYieldValue(/** @type {Node} */ (node));\n };\n\n /** @type {HasYieldReturnValue} */\n utils.hasYieldReturnValue = () => {\n return jsdocUtils.hasYieldValue(/** @type {Node} */ (node), true);\n };\n\n /** @type {HasThrowValue} */\n utils.hasThrowValue = () => {\n return jsdocUtils.hasThrowValue(node);\n };\n\n /** @type {IsAsync} */\n utils.isAsync = () => {\n return Boolean(node && 'async' in node && node.async);\n };\n\n /** @type {GetTags} */\n utils.getTags = (tagName) => {\n return jsdocUtils.getTags(jsdoc, tagName);\n };\n\n /** @type {GetPresentTags} */\n utils.getPresentTags = (tagList) => {\n return jsdocUtils.filterTags(jsdoc, (tag) => {\n return tagList.includes(tag.tag);\n });\n };\n\n /** @type {FilterTags} */\n utils.filterTags = (filter) => {\n return jsdocUtils.filterTags(jsdoc, (tag) => {\n return filter(tag);\n });\n };\n\n /** @type {FilterAllTags} */\n utils.filterAllTags = (filter) => {\n const tags = jsdocUtils.getAllTags(jsdoc);\n return tags.filter((tag) => {\n return filter(tag);\n });\n };\n\n /** @type {GetTagsByType} */\n utils.getTagsByType = (tags) => {\n return jsdocUtils.getTagsByType(context, mode, tags);\n };\n\n /** @type {HasOptionTag} */\n utils.hasOptionTag = (tagName) => {\n const {\n tags,\n } = context.options[0] ?? {};\n\n return Boolean(tags && tags.includes(tagName));\n };\n\n /** @type {GetClassNode} */\n utils.getClassNode = () => {\n return [\n ...ancestors, node,\n ].reverse().find((parent) => {\n return parent && [\n 'ClassDeclaration', 'ClassExpression',\n ].includes(parent.type);\n }) ?? null;\n };\n\n /** @type {GetClassJsdoc} */\n utils.getClassJsdoc = () => {\n const classNode = utils.getClassNode();\n\n if (!classNode) {\n return null;\n }\n\n const classJsdocNode = getJSDocComment(sourceCode, classNode, {\n maxLines,\n minLines,\n });\n\n if (classJsdocNode) {\n return parseComment(classJsdocNode, '');\n }\n\n return null;\n };\n\n /** @type {ClassHasTag} */\n utils.classHasTag = (tagName) => {\n const classJsdoc = utils.getClassJsdoc();\n\n return classJsdoc !== null && jsdocUtils.hasTag(classJsdoc, tagName);\n };\n\n /** @type {ForEachPreferredTag} */\n utils.forEachPreferredTag = (tagName, arrayHandler, skipReportingBlockedTag) => {\n return jsdocUtils.forEachPreferredTag(\n jsdoc, tagName, arrayHandler, {\n context,\n mode,\n report,\n skipReportingBlockedTag,\n tagNamePreference,\n },\n );\n };\n\n /** @type {FindContext} */\n utils.findContext = (contexts, comment) => {\n const foundContext = contexts.find((cntxt) => {\n return typeof cntxt === 'string' ?\n esquery.matches(\n /** @type {Node} */ (node),\n esquery.parse(cntxt),\n undefined,\n {\n visitorKeys: sourceCode.visitorKeys,\n },\n ) :\n (!cntxt.context || cntxt.context === 'any' ||\n esquery.matches(\n /** @type {Node} */ (node),\n esquery.parse(cntxt.context),\n undefined,\n {\n visitorKeys: sourceCode.visitorKeys,\n },\n )) && comment === cntxt.comment;\n });\n\n const contextStr = typeof foundContext === 'object' ?\n foundContext.context ?? 'any' :\n String(foundContext);\n\n return {\n contextStr,\n foundContext,\n };\n };\n\n return utils;\n};\n\n/**\n * @typedef {{\n * [key: string]: false|string|{\n * message: string,\n * replacement?: false|string\n * skipRootChecking?: boolean\n * }\n * }} PreferredTypes\n */\n/**\n * @typedef {{\n * [key: string]: {\n * name?: \"text\"|\"namepath-defining\"|\"namepath-referencing\"|false,\n * type?: boolean|string[],\n * required?: (\"name\"|\"type\"|\"typeOrNameRequired\")[]\n * }\n * }} StructuredTags\n */\n/**\n * Settings from ESLint types.\n * @typedef {{\n * maxLines: Integer,\n * minLines: Integer,\n * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,\n * mode: import('./jsdocUtils.js').ParserMode,\n * preferredTypes: PreferredTypes,\n * structuredTags: StructuredTags,\n * [name: string]: any,\n * contexts?: Context[]\n * }} Settings\n */\n\n/**\n * @typedef {{\n * settings?: {\n * jsdoc?: {\n * ignorePrivate: boolean,\n * ignoreInternal: boolean,\n * maxLines: Integer,\n * minLines: Integer,\n * tagNamePreference: import('./jsdocUtils.js').TagNamePreference,\n * preferredTypes: PreferredTypes,\n * structuredTags: StructuredTags,\n * overrideReplacesDocs: boolean,\n * ignoreReplacesDocs: boolean,\n * implementsReplacesDocs: boolean,\n * augmentsExtendsReplacesDocs: boolean,\n * exemptDestructuredRootsFromChecks: boolean,\n * mode: import('./jsdocUtils.js').ParserMode,\n * contexts: Context[],\n * }\n * }\n * }} JSDocSettings\n */\n\n/**\n * @param {import('eslint').Rule.RuleContext & JSDocSettings} context\n * @returns {Settings|false}\n */\nconst getSettings = (context) => {\n /* eslint-disable perfectionist/sort-objects */\n const settings = {\n // All rules\n ignorePrivate: Boolean(context.settings.jsdoc?.ignorePrivate),\n ignoreInternal: Boolean(context.settings.jsdoc?.ignoreInternal),\n maxLines: Number(context.settings.jsdoc?.maxLines ?? 1),\n minLines: Number(context.settings.jsdoc?.minLines ?? 0),\n\n // `check-tag-names` and many returns/param rules\n tagNamePreference: context.settings.jsdoc?.tagNamePreference ?? {},\n\n // `check-types` and `no-undefined-types`\n preferredTypes: context.settings.jsdoc?.preferredTypes ?? {},\n\n // `check-types`, `no-undefined-types`, `valid-types`\n structuredTags: context.settings.jsdoc?.structuredTags ?? {},\n\n // `require-param`, `require-description`, `require-example`,\n // `require-returns`, `require-throw`, `require-yields`\n overrideReplacesDocs: context.settings.jsdoc?.overrideReplacesDocs,\n ignoreReplacesDocs: context.settings.jsdoc?.ignoreReplacesDocs,\n implementsReplacesDocs: context.settings.jsdoc?.implementsReplacesDocs,\n augmentsExtendsReplacesDocs: context.settings.jsdoc?.augmentsExtendsReplacesDocs,\n\n // `require-param-type`, `require-param-description`\n exemptDestructuredRootsFromChecks: context.settings.jsdoc?.exemptDestructuredRootsFromChecks,\n\n // Many rules, e.g., `check-tag-names`\n mode: context.settings.jsdoc?.mode ?? 'typescript',\n\n // Many rules\n contexts: context.settings.jsdoc?.contexts,\n };\n /* eslint-enable perfectionist/sort-objects */\n\n jsdocUtils.setTagStructure(settings.mode);\n try {\n jsdocUtils.overrideTagStructure(settings.structuredTags);\n } catch (error) {\n context.report({\n loc: {\n end: {\n column: 1,\n line: 1,\n },\n start: {\n column: 1,\n line: 1,\n },\n },\n message: /** @type {Error} */ (error).message,\n });\n\n return false;\n }\n\n return settings;\n};\n\n/**\n * Create the report function\n * @callback MakeReport\n * @param {import('eslint').Rule.RuleContext} context\n * @param {import('estree').Node} commentNode\n * @returns {Report}\n */\n\n/** @type {MakeReport} */\nconst makeReport = (context, commentNode) => {\n /** @type {Report} */\n const report = (message, fix = null, jsdocLoc = null, data = undefined) => {\n let loc;\n\n if (jsdocLoc) {\n if (!('line' in jsdocLoc)) {\n jsdocLoc.line = /** @type {import('comment-parser').Spec & {line?: Integer}} */ (\n jsdocLoc\n ).source[0].number;\n }\n\n const lineNumber = /** @type {import('eslint').AST.SourceLocation} */ (\n commentNode.loc\n ).start.line +\n /** @type {Integer} */ (jsdocLoc.line);\n\n loc = {\n end: {\n column: 0,\n line: lineNumber,\n },\n start: {\n column: 0,\n line: lineNumber,\n },\n };\n\n if ('column' in jsdocLoc && typeof jsdocLoc.column === 'number') {\n const colNumber = /** @type {import('eslint').AST.SourceLocation} */ (\n commentNode.loc\n ).start.column + jsdocLoc.column;\n\n l