eslint-plugin-jsdoc 52.0.1 → 52.0.3

package/dist/getJsdocProcessorPlugin.js

@@ -0,0 +1,383 @@
+import { forEachPreferredTag, getPreferredTagName, getRegexFromString, getTagDescription, hasTag } from "./jsdocUtils.js";
+import { parseComment } from "@es-joy/jsdoccomment";
+import * as espree from "espree";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/getJsdocProcessorPlugin.js
+/**
+* @import {
+*   Integer,
+*   JsdocBlockWithInline,
+* } from './iterateJsdoc.js';
+* @import {
+*   ESLint,
+*   Linter,
+* } from 'eslint';
+*/
+const { version } = JSON.parse(readFileSync(join(import.meta.dirname, "../package.json")));
+const likelyNestedJSDocIndentSpace = 1;
+const preTagSpaceLength = 1;
+const firstLinePrefixLength = preTagSpaceLength;
+const hasCaptionRegex = /^\s*<caption>([\s\S]*?)<\/caption>/v;
+/**
+* @param {string} str
+* @returns {string}
+*/
+const escapeStringRegexp = (str) => {
+	return str.replaceAll(/[.*+?^$\{\}\(\)\|\[\]\\]/gv, "\\$&");
+};
+/**
+* @param {string} str
+* @param {string} ch
+* @returns {Integer}
+*/
+const countChars = (str, ch) => {
+	return (str.match(new RegExp(escapeStringRegexp(ch), "gv")) || []).length;
+};
+/**
+* @param {string} text
+* @returns {[
+*   Integer,
+*   Integer
+* ]}
+*/
+const getLinesCols = (text) => {
+	const matchLines = countChars(text, "\n");
+	const colDelta = matchLines ? text.slice(text.lastIndexOf("\n") + 1).length : text.length;
+	return [matchLines, colDelta];
+};
+/**
+* @typedef {number} Integer
+*/
+/**
+* @typedef {object} JsdocProcessorOptions
+* @property {boolean} [captionRequired] Require captions for example tags
+* @property {Integer} [paddedIndent] See docs
+* @property {boolean} [checkDefaults] See docs
+* @property {boolean} [checkParams] See docs
+* @property {boolean} [checkExamples] See docs
+* @property {boolean} [checkProperties] See docs
+* @property {string} [matchingFileName] See docs
+* @property {string} [matchingFileNameDefaults] See docs
+* @property {string} [matchingFileNameParams] See docs
+* @property {string} [matchingFileNameProperties] See docs
+* @property {string|RegExp} [exampleCodeRegex] See docs
+* @property {string|RegExp} [rejectExampleCodeRegex] See docs
+* @property {string[]} [allowedLanguagesToProcess] See docs
+* @property {"script"|"module"} [sourceType] See docs
+* @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser] See docs
+*/
+/**
+* We use a function for the ability of the user to pass in a config, but
+* without requiring all users of the plugin to do so.
+* @param {JsdocProcessorOptions} [options]
+* @returns {ESLint.Plugin}
+*/
+const getJsdocProcessorPlugin = (options = {}) => {
+	const { allowedLanguagesToProcess = [
+		"js",
+		"ts",
+		"javascript",
+		"typescript"
+	], captionRequired = false, checkDefaults = false, checkExamples = true, checkParams = false, checkProperties = false, exampleCodeRegex = null, matchingFileName = null, matchingFileNameDefaults = null, matchingFileNameParams = null, matchingFileNameProperties = null, paddedIndent = 0, parser = void 0, rejectExampleCodeRegex = null, sourceType = "module" } = options;
+	/** @type {RegExp} */
+	let exampleCodeRegExp;
+	/** @type {RegExp} */
+	let rejectExampleCodeRegExp;
+	if (exampleCodeRegex) exampleCodeRegExp = typeof exampleCodeRegex === "string" ? getRegexFromString(exampleCodeRegex) : exampleCodeRegex;
+	if (rejectExampleCodeRegex) rejectExampleCodeRegExp = typeof rejectExampleCodeRegex === "string" ? getRegexFromString(rejectExampleCodeRegex) : rejectExampleCodeRegex;
+	/**
+	* @type {{
+	*   targetTagName: string,
+	*   ext: string,
+	*   codeStartLine: number,
+	*   codeStartCol: number,
+	*   nonJSPrefacingCols: number,
+	*   commentLineCols: [number, number]
+	* }[]}
+	*/
+	const otherInfo = [];
+	/** @type {import('eslint').Linter.LintMessage[]} */
+	let extraMessages = [];
+	/**
+	* @param {JsdocBlockWithInline} jsdoc
+	* @param {string} jsFileName
+	* @param {[number, number]} commentLineCols
+	*/
+	const getTextsAndFileNames = (jsdoc, jsFileName, commentLineCols) => {
+		/**
+		* @type {{
+		*   text: string,
+		*   filename: string|null|undefined
+		* }[]}
+		*/
+		const textsAndFileNames = [];
+		/**
+		* @param {{
+		*   filename: string|null,
+		*   defaultFileName: string|undefined,
+		*   source: string,
+		*   targetTagName: string,
+		*   rules?: import('eslint').Linter.RulesRecord|undefined,
+		*   lines?: Integer,
+		*   cols?: Integer,
+		*   skipInit?: boolean,
+		*   ext: string,
+		*   sources?: {
+		*     nonJSPrefacingCols: Integer,
+		*     nonJSPrefacingLines: Integer,
+		*     string: string,
+		*   }[],
+		*   tag?: import('comment-parser').Spec & {
+		*     line?: Integer,
+		*   }|{
+		*     line: Integer,
+		*   }
+		* }} cfg
+		*/
+		const checkSource = ({ cols = 0, defaultFileName, ext, filename, lines = 0, skipInit, source, sources = [], tag = { line: 0 }, targetTagName }) => {
+			if (!skipInit) sources.push({
+				nonJSPrefacingCols: cols,
+				nonJSPrefacingLines: lines,
+				string: source
+			});
+			/**
+			* @param {{
+			*   nonJSPrefacingCols: Integer,
+			*   nonJSPrefacingLines: Integer,
+			*   string: string
+			* }} cfg
+			*/
+			const addSourceInfo = function({ nonJSPrefacingCols, nonJSPrefacingLines, string }) {
+				const src = paddedIndent ? string.replaceAll(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, "gv"), "\n") : string;
+				const file = filename || defaultFileName;
+				if (!("line" in tag)) tag.line = tag.source[0].number;
+				const codeStartLine = tag.line + nonJSPrefacingLines;
+				const codeStartCol = likelyNestedJSDocIndentSpace;
+				textsAndFileNames.push({
+					filename: file,
+					text: src
+				});
+				otherInfo.push({
+					codeStartCol,
+					codeStartLine,
+					commentLineCols,
+					ext,
+					nonJSPrefacingCols,
+					targetTagName
+				});
+			};
+			for (const targetSource of sources) addSourceInfo(targetSource);
+		};
+		/**
+		*
+		* @param {string|null} filename
+		* @param {string} [ext] Since `eslint-plugin-markdown` v2, and
+		*   ESLint 7, this is the default which other JS-fenced rules will used.
+		*   Formerly "md" was the default.
+		* @returns {{
+		*   defaultFileName: string|undefined,
+		*   filename: string|null,
+		*   ext: string
+		* }}
+		*/
+		const getFilenameInfo = (filename, ext = "md/*.js") => {
+			let defaultFileName;
+			if (!filename) if (typeof jsFileName === "string" && jsFileName.includes(".")) defaultFileName = jsFileName.replace(/\.[^.]*$/v, `.${ext}`);
+			else defaultFileName = `dummy.${ext}`;
+			return {
+				defaultFileName,
+				ext,
+				filename
+			};
+		};
+		if (checkDefaults) {
+			const filenameInfo = getFilenameInfo(matchingFileNameDefaults, "jsdoc-defaults");
+			forEachPreferredTag(jsdoc, "default", (tag, targetTagName) => {
+				if (!tag.description.trim()) return;
+				checkSource({
+					source: `(${getTagDescription(tag)})`,
+					targetTagName,
+					...filenameInfo
+				});
+			});
+		}
+		if (checkParams) {
+			const filenameInfo = getFilenameInfo(matchingFileNameParams, "jsdoc-params");
+			forEachPreferredTag(jsdoc, "param", (tag, targetTagName) => {
+				if (!tag.default || !tag.default.trim()) return;
+				checkSource({
+					source: `(${tag.default})`,
+					targetTagName,
+					...filenameInfo
+				});
+			});
+		}
+		if (checkProperties) {
+			const filenameInfo = getFilenameInfo(matchingFileNameProperties, "jsdoc-properties");
+			forEachPreferredTag(jsdoc, "property", (tag, targetTagName) => {
+				if (!tag.default || !tag.default.trim()) return;
+				checkSource({
+					source: `(${tag.default})`,
+					targetTagName,
+					...filenameInfo
+				});
+			});
+		}
+		if (!checkExamples) return textsAndFileNames;
+		const tagName = getPreferredTagName(jsdoc, { tagName: "example" });
+		if (!hasTag(jsdoc, tagName)) return textsAndFileNames;
+		const matchingFilenameInfo = getFilenameInfo(matchingFileName);
+		forEachPreferredTag(jsdoc, "example", (tag, targetTagName) => {
+			let source = getTagDescription(tag);
+			const match = source.match(hasCaptionRegex);
+			if (captionRequired && (!match || !match[1].trim())) {
+				extraMessages.push({
+					column: commentLineCols[1] + 1,
+					line: 1 + commentLineCols[0] + (tag.line ?? tag.source[0].number),
+					message: `@${targetTagName} error - Caption is expected for examples.`,
+					ruleId: "jsdoc/example-missing-caption",
+					severity: 2
+				});
+				return;
+			}
+			source = source.replace(hasCaptionRegex, "");
+			const [lines, cols] = match ? getLinesCols(match[0]) : [0, 0];
+			if (exampleCodeRegex && !exampleCodeRegExp.test(source) || rejectExampleCodeRegex && rejectExampleCodeRegExp.test(source)) return;
+			if (allowedLanguagesToProcess) {
+				const matches = /^\s*```(?<language>\S+)([\s\S]*)```\s*$/v.exec(source);
+				if (matches?.groups && !allowedLanguagesToProcess.includes(matches.groups.language.toLowerCase())) return;
+			}
+			const sources = [];
+			let skipInit = false;
+			if (exampleCodeRegex) {
+				let nonJSPrefacingCols = 0;
+				let nonJSPrefacingLines = 0;
+				let startingIndex = 0;
+				let lastStringCount = 0;
+				let exampleCode;
+				exampleCodeRegExp.lastIndex = 0;
+				while ((exampleCode = exampleCodeRegExp.exec(source)) !== null) {
+					const { "0": n0, "1": n1, index } = exampleCode;
+					const preMatch = source.slice(startingIndex, index);
+					const [preMatchLines, colDelta] = getLinesCols(preMatch);
+					let nonJSPreface;
+					let nonJSPrefaceLineCount;
+					if (n1) {
+						const idx = n0.indexOf(n1);
+						nonJSPreface = n0.slice(0, idx);
+						nonJSPrefaceLineCount = countChars(nonJSPreface, "\n");
+					} else {
+						nonJSPreface = "";
+						nonJSPrefaceLineCount = 0;
+					}
+					nonJSPrefacingLines += lastStringCount + preMatchLines + nonJSPrefaceLineCount;
+					if (nonJSPrefaceLineCount) {
+						const charsInLastLine = nonJSPreface.slice(nonJSPreface.lastIndexOf("\n") + 1).length;
+						nonJSPrefacingCols += charsInLastLine;
+					} else nonJSPrefacingCols += colDelta + nonJSPreface.length;
+					const string = n1 || n0;
+					sources.push({
+						nonJSPrefacingCols,
+						nonJSPrefacingLines,
+						string
+					});
+					startingIndex = exampleCodeRegExp.lastIndex;
+					lastStringCount = countChars(string, "\n");
+					if (!exampleCodeRegExp.global) break;
+				}
+				skipInit = true;
+			}
+			checkSource({
+				cols,
+				lines,
+				skipInit,
+				source,
+				sources,
+				tag,
+				targetTagName,
+				...matchingFilenameInfo
+			});
+		});
+		return textsAndFileNames;
+	};
+	return {
+		meta: {
+			name: "eslint-plugin-jsdoc/processor",
+			version
+		},
+		processors: { examples: {
+			meta: {
+				name: "eslint-plugin-jsdoc/preprocessor",
+				version
+			},
+			postprocess([jsMessages, ...messages], filename) {
+				for (const [idx, message] of messages.entries()) {
+					const { codeStartCol, codeStartLine, commentLineCols, nonJSPrefacingCols, targetTagName } = otherInfo[idx];
+					for (const msg of message) {
+						const { column, endColumn, endLine, fatal, line, message: messageText, ruleId, severity } = msg;
+						const [codeCtxLine, codeCtxColumn] = commentLineCols;
+						const startLine = codeCtxLine + codeStartLine + line;
+						const startCol = 1 + codeCtxColumn + codeStartCol + (line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength) + column;
+						msg.message = "@" + targetTagName + " " + (severity === 2 ? "error" : "warning") + (ruleId ? " (" + ruleId + ")" : "") + ": " + (fatal ? "Fatal: " : "") + messageText;
+						msg.line = startLine;
+						msg.column = startCol;
+						msg.endLine = endLine ? startLine + endLine : startLine;
+						msg.endColumn = endColumn ? startCol - column + endColumn : startCol;
+					}
+				}
+				const ret = [...jsMessages].concat(...messages, ...extraMessages);
+				extraMessages = [];
+				return ret;
+			},
+			preprocess(text, filename) {
+				try {
+					let ast;
+					try {
+						ast = parser ? parser.parseForESLint(text, {
+							comment: true,
+							ecmaVersion: "latest",
+							sourceType
+						}).ast : espree.parse(text, {
+							comment: true,
+							ecmaVersion: "latest",
+							sourceType
+						});
+					} catch {
+						return [text];
+					}
+					/** @type {[number, number][]} */
+					const commentLineCols = [];
+					const jsdocComments = ast.comments.filter((comment) => {
+						return /^\*\s/v.test(comment.value);
+					}).map((comment) => {
+						const [start] = comment.range ?? [];
+						const textToStart = text.slice(0, start);
+						const [lines, cols] = getLinesCols(textToStart);
+						commentLineCols.push([lines, cols]);
+						return parseComment(comment);
+					});
+					return [text, ...jsdocComments.flatMap((jsdoc, idx) => {
+						return getTextsAndFileNames(jsdoc, filename, commentLineCols[idx]);
+					}).filter(
+						/**
+						* @returns {file is Linter.ProcessorFile}
+						*/
+						(file) => {
+							return file !== null && file !== void 0;
+						}
+					)];
+				} catch (error) {
+					console.log("err", filename, error);
+				}
+				return [];
+			},
+			supportsAutofix: false
+		} }
+	};
+};
+
+//#endregion
+export { getJsdocProcessorPlugin };
+//# sourceMappingURL=getJsdocProcessorPlugin.js.map

package/dist/getJsdocProcessorPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getJsdocProcessorPlugin.js","names":[],"sources":["../src/getJsdocProcessorPlugin.js"],"sourcesContent":["import {\n  forEachPreferredTag,\n  getPreferredTagName,\n  getRegexFromString,\n  getTagDescription,\n  hasTag,\n} from './jsdocUtils.js';\nimport {\n  parseComment,\n} from '@es-joy/jsdoccomment';\nimport * as espree from 'espree';\nimport {\n  readFileSync,\n} from 'node:fs';\nimport {\n  join,\n} from 'node:path';\n\n/**\n * @import {\n *   Integer,\n *   JsdocBlockWithInline,\n * } from './iterateJsdoc.js';\n * @import {\n *   ESLint,\n *   Linter,\n * } from 'eslint';\n */\n\nconst {\n  version,\n} = JSON.parse(\n  // @ts-expect-error `Buffer` is ok for `JSON.parse`\n  readFileSync(join(import.meta.dirname, '../package.json')),\n);\n\n// const zeroBasedLineIndexAdjust = -1;\nconst likelyNestedJSDocIndentSpace = 1;\nconst preTagSpaceLength = 1;\n\n// If a space is present, we should ignore it\nconst firstLinePrefixLength = preTagSpaceLength;\n\nconst hasCaptionRegex = /^\\s*<caption>([\\s\\S]*?)<\\/caption>/v;\n\n/**\n * @param {string} str\n * @returns {string}\n */\nconst escapeStringRegexp = (str) => {\n  return str.replaceAll(/[.*+?^$\\{\\}\\(\\)\\|\\[\\]\\\\]/gv, '\\\\$&');\n};\n\n/**\n * @param {string} str\n * @param {string} ch\n * @returns {Integer}\n */\nconst countChars = (str, ch) => {\n  return (str.match(new RegExp(escapeStringRegexp(ch), 'gv')) || []).length;\n};\n\n/**\n * @param {string} text\n * @returns {[\n *   Integer,\n *   Integer\n * ]}\n */\nconst getLinesCols = (text) => {\n  const matchLines = countChars(text, '\\n');\n\n  const colDelta = matchLines ?\n    text.slice(text.lastIndexOf('\\n') + 1).length :\n    text.length;\n\n  return [\n    matchLines, colDelta,\n  ];\n};\n\n/**\n * @typedef {number} Integer\n */\n\n/**\n * @typedef {object} JsdocProcessorOptions\n * @property {boolean} [captionRequired] Require captions for example tags\n * @property {Integer} [paddedIndent] See docs\n * @property {boolean} [checkDefaults] See docs\n * @property {boolean} [checkParams] See docs\n * @property {boolean} [checkExamples] See docs\n * @property {boolean} [checkProperties] See docs\n * @property {string} [matchingFileName] See docs\n * @property {string} [matchingFileNameDefaults] See docs\n * @property {string} [matchingFileNameParams] See docs\n * @property {string} [matchingFileNameProperties] See docs\n * @property {string|RegExp} [exampleCodeRegex] See docs\n * @property {string|RegExp} [rejectExampleCodeRegex] See docs\n * @property {string[]} [allowedLanguagesToProcess] See docs\n * @property {\"script\"|\"module\"} [sourceType] See docs\n * @property {import('eslint').Linter.ESTreeParser|import('eslint').Linter.NonESTreeParser} [parser] See docs\n */\n\n/**\n * We use a function for the ability of the user to pass in a config, but\n * without requiring all users of the plugin to do so.\n * @param {JsdocProcessorOptions} [options]\n * @returns {ESLint.Plugin}\n */\nexport const getJsdocProcessorPlugin = (options = {}) => {\n  const {\n    allowedLanguagesToProcess = [\n      'js', 'ts', 'javascript', 'typescript',\n    ],\n    captionRequired = false,\n    checkDefaults = false,\n    checkExamples = true,\n    checkParams = false,\n    checkProperties = false,\n    exampleCodeRegex = null,\n    matchingFileName = null,\n    matchingFileNameDefaults = null,\n    matchingFileNameParams = null,\n    matchingFileNameProperties = null,\n    paddedIndent = 0,\n    parser = undefined,\n    rejectExampleCodeRegex = null,\n    sourceType = 'module',\n  } = options;\n\n  /** @type {RegExp} */\n  let exampleCodeRegExp;\n  /** @type {RegExp} */\n  let rejectExampleCodeRegExp;\n\n  if (exampleCodeRegex) {\n    exampleCodeRegExp = typeof exampleCodeRegex === 'string' ?\n      getRegexFromString(exampleCodeRegex) :\n      exampleCodeRegex;\n  }\n\n  if (rejectExampleCodeRegex) {\n    rejectExampleCodeRegExp = typeof rejectExampleCodeRegex === 'string' ?\n      getRegexFromString(rejectExampleCodeRegex) :\n      rejectExampleCodeRegex;\n  }\n\n  /**\n   * @type {{\n   *   targetTagName: string,\n   *   ext: string,\n   *   codeStartLine: number,\n   *   codeStartCol: number,\n   *   nonJSPrefacingCols: number,\n   *   commentLineCols: [number, number]\n   * }[]}\n   */\n  const otherInfo = [];\n\n  /** @type {import('eslint').Linter.LintMessage[]} */\n  let extraMessages = [];\n\n  /**\n   * @param {JsdocBlockWithInline} jsdoc\n   * @param {string} jsFileName\n   * @param {[number, number]} commentLineCols\n   */\n  const getTextsAndFileNames = (jsdoc, jsFileName, commentLineCols) => {\n    /**\n     * @type {{\n     *   text: string,\n     *   filename: string|null|undefined\n     * }[]}\n     */\n    const textsAndFileNames = [];\n\n    /**\n     * @param {{\n     *   filename: string|null,\n     *   defaultFileName: string|undefined,\n     *   source: string,\n     *   targetTagName: string,\n     *   rules?: import('eslint').Linter.RulesRecord|undefined,\n     *   lines?: Integer,\n     *   cols?: Integer,\n     *   skipInit?: boolean,\n     *   ext: string,\n     *   sources?: {\n     *     nonJSPrefacingCols: Integer,\n     *     nonJSPrefacingLines: Integer,\n     *     string: string,\n     *   }[],\n     *   tag?: import('comment-parser').Spec & {\n     *     line?: Integer,\n     *   }|{\n     *     line: Integer,\n     *   }\n     * }} cfg\n     */\n    const checkSource = ({\n      cols = 0,\n      defaultFileName,\n      ext,\n      filename,\n      lines = 0,\n      skipInit,\n      source,\n      sources = [],\n      tag = {\n        line: 0,\n      },\n      targetTagName,\n    }) => {\n      if (!skipInit) {\n        sources.push({\n          nonJSPrefacingCols: cols,\n          nonJSPrefacingLines: lines,\n          string: source,\n        });\n      }\n\n      /**\n       * @param {{\n       *   nonJSPrefacingCols: Integer,\n       *   nonJSPrefacingLines: Integer,\n       *   string: string\n       * }} cfg\n       */\n      const addSourceInfo = function ({\n        nonJSPrefacingCols,\n        nonJSPrefacingLines,\n        string,\n      }) {\n        const src = paddedIndent ?\n          string.replaceAll(new RegExp(`(^|\\n) {${paddedIndent}}(?!$)`, 'gv'), '\\n') :\n          string;\n\n        // Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api\n        const file = filename || defaultFileName;\n\n        if (!('line' in tag)) {\n          tag.line = tag.source[0].number;\n        }\n\n        // NOTE: `tag.line` can be 0 if of form `/** @tag ... */`\n        const codeStartLine = /**\n                               * @type {import('comment-parser').Spec & {\n                               *     line: Integer,\n                               * }}\n                               */ (tag).line + nonJSPrefacingLines;\n        const codeStartCol = likelyNestedJSDocIndentSpace;\n\n        textsAndFileNames.push({\n          filename: file,\n          text: src,\n        });\n        otherInfo.push({\n          codeStartCol,\n          codeStartLine,\n          commentLineCols,\n          ext,\n          nonJSPrefacingCols,\n          targetTagName,\n        });\n      };\n\n      for (const targetSource of sources) {\n        addSourceInfo(targetSource);\n      }\n    };\n\n    /**\n     *\n     * @param {string|null} filename\n     * @param {string} [ext] Since `eslint-plugin-markdown` v2, and\n     *   ESLint 7, this is the default which other JS-fenced rules will used.\n     *   Formerly \"md\" was the default.\n     * @returns {{\n     *   defaultFileName: string|undefined,\n     *   filename: string|null,\n     *   ext: string\n     * }}\n     */\n    const getFilenameInfo = (filename, ext = 'md/*.js') => {\n      let defaultFileName;\n      if (!filename) {\n        if (typeof jsFileName === 'string' && jsFileName.includes('.')) {\n          defaultFileName = jsFileName.replace(/\\.[^.]*$/v, `.${ext}`);\n        } else {\n          defaultFileName = `dummy.${ext}`;\n        }\n      }\n\n      return {\n        defaultFileName,\n        ext,\n        filename,\n      };\n    };\n\n    if (checkDefaults) {\n      const filenameInfo = getFilenameInfo(matchingFileNameDefaults, 'jsdoc-defaults');\n      forEachPreferredTag(jsdoc, 'default', (tag, targetTagName) => {\n        if (!tag.description.trim()) {\n          return;\n        }\n\n        checkSource({\n          source: `(${getTagDescription(tag)})`,\n          targetTagName,\n          ...filenameInfo,\n        });\n      });\n    }\n\n    if (checkParams) {\n      const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');\n      forEachPreferredTag(jsdoc, 'param', (tag, targetTagName) => {\n        if (!tag.default || !tag.default.trim()) {\n          return;\n        }\n\n        checkSource({\n          source: `(${tag.default})`,\n          targetTagName,\n          ...filenameInfo,\n        });\n      });\n    }\n\n    if (checkProperties) {\n      const filenameInfo = getFilenameInfo(matchingFileNameProperties, 'jsdoc-properties');\n      forEachPreferredTag(jsdoc, 'property', (tag, targetTagName) => {\n        if (!tag.default || !tag.default.trim()) {\n          return;\n        }\n\n        checkSource({\n          source: `(${tag.default})`,\n          targetTagName,\n          ...filenameInfo,\n        });\n      });\n    }\n\n    if (!checkExamples) {\n      return textsAndFileNames;\n    }\n\n    const tagName = /** @type {string} */ (getPreferredTagName(jsdoc, {\n      tagName: 'example',\n    }));\n    if (!hasTag(jsdoc, tagName)) {\n      return textsAndFileNames;\n    }\n\n    const matchingFilenameInfo = getFilenameInfo(matchingFileName);\n\n    forEachPreferredTag(jsdoc, 'example', (tag, targetTagName) => {\n      let source = /** @type {string} */ (getTagDescription(tag));\n      const match = source.match(hasCaptionRegex);\n\n      if (captionRequired && (!match || !match[1].trim())) {\n        extraMessages.push({\n          column: commentLineCols[1] + 1,\n          line: 1 + commentLineCols[0] + (tag.line ?? tag.source[0].number),\n          message: `@${targetTagName} error - Caption is expected for examples.`,\n          ruleId: 'jsdoc/example-missing-caption',\n          severity: 2,\n        });\n        return;\n      }\n\n      source = source.replace(hasCaptionRegex, '');\n      const [\n        lines,\n        cols,\n      ] = match ? getLinesCols(match[0]) : [\n        0, 0,\n      ];\n\n      if (exampleCodeRegex && !exampleCodeRegExp.test(source) ||\n        rejectExampleCodeRegex && rejectExampleCodeRegExp.test(source)\n      ) {\n        return;\n      }\n\n      // If `allowedLanguagesToProcess` is falsy, all languages should be processed.\n      if (allowedLanguagesToProcess) {\n        const matches = (/^\\s*```(?<language>\\S+)([\\s\\S]*)```\\s*$/v).exec(source);\n        if (matches?.groups && !allowedLanguagesToProcess.includes(\n          matches.groups.language.toLowerCase(),\n        )) {\n          return;\n        }\n      }\n\n      const sources = [];\n      let skipInit = false;\n      if (exampleCodeRegex) {\n        let nonJSPrefacingCols = 0;\n        let nonJSPrefacingLines = 0;\n\n        let startingIndex = 0;\n        let lastStringCount = 0;\n\n        let exampleCode;\n        exampleCodeRegExp.lastIndex = 0;\n        while ((exampleCode = exampleCodeRegExp.exec(source)) !== null) {\n          const {\n            '0': n0,\n            '1': n1,\n            index,\n          } = exampleCode;\n\n          // Count anything preceding user regex match (can affect line numbering)\n          const preMatch = source.slice(startingIndex, index);\n\n          const [\n            preMatchLines,\n            colDelta,\n          ] = getLinesCols(preMatch);\n\n          let nonJSPreface;\n          let nonJSPrefaceLineCount;\n          if (n1) {\n            const idx = n0.indexOf(n1);\n            nonJSPreface = n0.slice(0, idx);\n            nonJSPrefaceLineCount = countChars(nonJSPreface, '\\n');\n          } else {\n            nonJSPreface = '';\n            nonJSPrefaceLineCount = 0;\n          }\n\n          nonJSPrefacingLines += lastStringCount + preMatchLines + nonJSPrefaceLineCount;\n\n          // Ignore `preMatch` delta if newlines here\n          if (nonJSPrefaceLineCount) {\n            const charsInLastLine = nonJSPreface.slice(nonJSPreface.lastIndexOf('\\n') + 1).length;\n\n            nonJSPrefacingCols += charsInLastLine;\n          } else {\n            nonJSPrefacingCols += colDelta + nonJSPreface.length;\n          }\n\n          const string = n1 || n0;\n          sources.push({\n            nonJSPrefacingCols,\n            nonJSPrefacingLines,\n            string,\n          });\n          startingIndex = exampleCodeRegExp.lastIndex;\n          lastStringCount = countChars(string, '\\n');\n          if (!exampleCodeRegExp.global) {\n            break;\n          }\n        }\n\n        skipInit = true;\n      }\n\n      checkSource({\n        cols,\n        lines,\n        skipInit,\n        source,\n        sources,\n        tag,\n        targetTagName,\n        ...matchingFilenameInfo,\n      });\n    });\n\n    return textsAndFileNames;\n  };\n\n  // See https://eslint.org/docs/latest/extend/plugins#processors-in-plugins\n  // See https://eslint.org/docs/latest/extend/custom-processors\n  // From https://github.com/eslint/eslint/issues/14745#issuecomment-869457265\n  /*\n    {\n      \"files\": [\"*.js\", \"*.ts\"],\n      \"processor\": \"jsdoc/example\" // a pretended value here\n    },\n    {\n      \"files\": [\n        \"*.js/*_jsdoc-example.js\",\n        \"*.ts/*_jsdoc-example.js\",\n        \"*.js/*_jsdoc-example.ts\"\n      ],\n      \"rules\": {\n        // specific rules for examples in jsdoc only here\n        // And other rules for `.js` and `.ts` will also be enabled for them\n      }\n    }\n  */\n  return {\n    meta: {\n      name: 'eslint-plugin-jsdoc/processor',\n      version,\n    },\n    processors: {\n      examples: {\n        meta: {\n          name: 'eslint-plugin-jsdoc/preprocessor',\n          version,\n        },\n        /**\n         * @param {import('eslint').Linter.LintMessage[][]} messages\n         * @param {string} filename\n         */\n        postprocess ([\n          jsMessages,\n          ...messages\n        // eslint-disable-next-line no-unused-vars -- Placeholder\n        ], filename) {\n          for (const [\n            idx,\n            message,\n          ] of messages.entries()) {\n            const {\n              codeStartCol,\n              codeStartLine,\n              commentLineCols,\n              nonJSPrefacingCols,\n              targetTagName,\n            } = otherInfo[idx];\n\n            for (const msg of message) {\n              const {\n                column,\n                endColumn,\n                endLine,\n                fatal,\n                line,\n                message: messageText,\n                ruleId,\n                severity,\n\n                // Todo: Make fixable\n                // fix\n                // fix: {range: [number, number], text: string}\n                // suggestions: {desc: , messageId:, fix: }[],\n              } = msg;\n\n              const [\n                codeCtxLine,\n                codeCtxColumn,\n              ] = commentLineCols;\n              const startLine = codeCtxLine + codeStartLine + line;\n\n              // Seems to need one more now\n              const startCol = 1 +\n                codeCtxColumn + codeStartCol + (\n              // This might not work for line 0, but line 0 is unlikely for examples\n                line <= 1 ? nonJSPrefacingCols + firstLinePrefixLength : preTagSpaceLength\n              ) + column;\n\n              msg.message = '@' + targetTagName + ' ' + (severity === 2 ? 'error' : 'warning') +\n                (ruleId ? ' (' + ruleId + ')' : '') + ': ' +\n                (fatal ? 'Fatal: ' : '') +\n                messageText;\n              msg.line = startLine;\n              msg.column = startCol;\n              msg.endLine = endLine ? startLine + endLine : startLine;\n              // added `- column` to offset what `endColumn` already seemed to include\n              msg.endColumn = endColumn ? startCol - column + endColumn : startCol;\n            }\n          }\n\n          const ret = [\n            ...jsMessages,\n          ].concat(...messages, ...extraMessages);\n          extraMessages = [];\n          return ret;\n        },\n\n        /**\n         * @param {string} text\n         * @param {string} filename\n         * @returns {(string | Linter.ProcessorFile)[]}\n         */\n        preprocess (text, filename) {\n          try {\n            let ast;\n\n            // May be running a second time so catch and ignore\n            try {\n              ast = parser ?\n                // @ts-expect-error Should be present\n                parser.parseForESLint(text, {\n                  comment: true,\n                  ecmaVersion: 'latest',\n                  sourceType,\n                }).ast :\n                espree.parse(text, {\n                  comment: true,\n                  ecmaVersion: 'latest',\n                  sourceType,\n                });\n            } catch {\n              return [\n                text,\n              ];\n            }\n\n            /** @type {[number, number][]} */\n            const commentLineCols = [];\n            const jsdocComments = /** @type {import('estree').Comment[]} */ (\n              /**\n               * @type {import('estree').Program & {\n               *   comments?: import('estree').Comment[]\n               * }}\n               */\n              (ast).comments\n            ).filter((comment) => {\n              return (/^\\*\\s/v).test(comment.value);\n            }).map((comment) => {\n              const [\n                start,\n                /* c8 ignore next -- Unsupporting processors only? */\n              ] = comment.range ?? [];\n              const textToStart = text.slice(0, start);\n\n              const [\n                lines,\n                cols,\n              ] = getLinesCols(textToStart);\n\n              // const lines = [...textToStart.matchAll(/\\n/gv)].length\n              // const lastLinePos = textToStart.lastIndexOf('\\n');\n              // const cols = lastLinePos === -1\n              //   ? 0\n              //   : textToStart.slice(lastLinePos).length;\n              commentLineCols.push([\n                lines, cols,\n              ]);\n              return parseComment(comment);\n            });\n\n            return [\n              text,\n              ...jsdocComments.flatMap((jsdoc, idx) => {\n                return getTextsAndFileNames(\n                  jsdoc,\n                  filename,\n                  commentLineCols[idx],\n                );\n              }).filter(\n                /**\n                 * @returns {file is Linter.ProcessorFile}\n                 */\n                (file) => {\n                  return file !== null && file !== undefined;\n                },\n              ),\n            ];\n          /* c8 ignore next 6 */\n          } catch (error) {\n            // eslint-disable-next-line no-console -- Debugging\n            console.log('err', filename, error);\n          }\n\n          return [];\n        },\n        // Todo: Reenable\n        supportsAutofix: false,\n      },\n    },\n  };\n};\n"],"mappings":"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"}