eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/getJsdocProcessorPlugin.cjs

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const getJsdocProcessorPlugin_js_1 = require("./getJsdocProcessorPlugin.js");
+exports.getJsdocProcessorPlugin = getJsdocProcessorPlugin_js_1.getJsdocProcessorPlugin;

package/dist/cjs/getJsdocProcessorPlugin.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/cjs/getJsdocProcessorPlugin.d.ts

@@ -0,0 +1,66 @@
+export function getJsdocProcessorPlugin(options?: JsdocProcessorOptions): ESLint.Plugin;
+export type Integer = number;
+export type JsdocProcessorOptions = {
+    /**
+     * Require captions for example tags
+     */
+    captionRequired?: boolean | undefined;
+    /**
+     * See docs
+     */
+    paddedIndent?: number | undefined;
+    /**
+     * See docs
+     */
+    checkDefaults?: boolean | undefined;
+    /**
+     * See docs
+     */
+    checkParams?: boolean | undefined;
+    /**
+     * See docs
+     */
+    checkExamples?: boolean | undefined;
+    /**
+     * See docs
+     */
+    checkProperties?: boolean | undefined;
+    /**
+     * See docs
+     */
+    matchingFileName?: string | undefined;
+    /**
+     * See docs
+     */
+    matchingFileNameDefaults?: string | undefined;
+    /**
+     * See docs
+     */
+    matchingFileNameParams?: string | undefined;
+    /**
+     * See docs
+     */
+    matchingFileNameProperties?: string | undefined;
+    /**
+     * See docs
+     */
+    exampleCodeRegex?: string | RegExp | undefined;
+    /**
+     * See docs
+     */
+    rejectExampleCodeRegex?: string | RegExp | undefined;
+    /**
+     * See docs
+     */
+    allowedLanguagesToProcess?: string[] | undefined;
+    /**
+     * See docs
+     */
+    sourceType?: "module" | "script" | undefined;
+    /**
+     * See docs
+     */
+    parser?: Linter.ESTreeParser | Linter.NonESTreeParser | undefined;
+};
+import type { ESLint } from 'eslint';
+import type { Linter } from 'eslint';

package/dist/cjs/getJsdocProcessorPlugin.js

@@ -0,0 +1,553 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getJsdocProcessorPlugin = void 0;
+const jsdocUtils_js_1 = require("./jsdocUtils.js");
+const jsdoccomment_1 = require("@es-joy/jsdoccomment");
+const espree = __importStar(require("espree"));
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * @import {
+ *   Integer,
+ *   JsdocBlockWithInline,
+ * } from './iterateJsdoc.js';
+ * @import {
+ *   ESLint,
+ *   Linter,
+ * } from 'eslint';
+ */
+const { version, } = JSON.parse(
+// @ts-expect-error `Buffer` is ok for `JSON.parse`
+(0, node_fs_1.readFileSync)((0, node_path_1.join)(import.meta.dirname, '../package.json')));
+// const zeroBasedLineIndexAdjust = -1;
+const likelyNestedJSDocIndentSpace = 1;
+const preTagSpaceLength = 1;
+// If a space is present, we should ignore it
+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 = undefined, rejectExampleCodeRegex = null, sourceType = 'module', } = options;
+    /** @type {RegExp} */
+    let exampleCodeRegExp;
+    /** @type {RegExp} */
+    let rejectExampleCodeRegExp;
+    if (exampleCodeRegex) {
+        exampleCodeRegExp = typeof exampleCodeRegex === 'string' ?
+            (0, jsdocUtils_js_1.getRegexFromString)(exampleCodeRegex) :
+            exampleCodeRegex;
+    }
+    if (rejectExampleCodeRegex) {
+        rejectExampleCodeRegExp = typeof rejectExampleCodeRegex === 'string' ?
+            (0, jsdocUtils_js_1.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;
+                // Programmatic ESLint API: https://eslint.org/docs/developer-guide/nodejs-api
+                const file = filename || defaultFileName;
+                if (!('line' in tag)) {
+                    tag.line = tag.source[0].number;
+                }
+                // NOTE: `tag.line` can be 0 if of form `/** @tag ... */`
+                const codeStartLine = /**
+                                       * @type {import('comment-parser').Spec & {
+                                       *     line: Integer,
+                                       * }}
+                                       */ (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');
+            (0, jsdocUtils_js_1.forEachPreferredTag)(jsdoc, 'default', (tag, targetTagName) => {
+                if (!tag.description.trim()) {
+                    return;
+                }
+                checkSource({
+                    source: `(${(0, jsdocUtils_js_1.getTagDescription)(tag)})`,
+                    targetTagName,
+                    ...filenameInfo,
+                });
+            });
+        }
+        if (checkParams) {
+            const filenameInfo = getFilenameInfo(matchingFileNameParams, 'jsdoc-params');
+            (0, jsdocUtils_js_1.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');
+            (0, jsdocUtils_js_1.forEachPreferredTag)(jsdoc, 'property', (tag, targetTagName) => {
+                if (!tag.default || !tag.default.trim()) {
+                    return;
+                }
+                checkSource({
+                    source: `(${tag.default})`,
+                    targetTagName,
+                    ...filenameInfo,
+                });
+            });
+        }
+        if (!checkExamples) {
+            return textsAndFileNames;
+        }
+        const tagName = /** @type {string} */ ((0, jsdocUtils_js_1.getPreferredTagName)(jsdoc, {
+            tagName: 'example',
+        }));
+        if (!(0, jsdocUtils_js_1.hasTag)(jsdoc, tagName)) {
+            return textsAndFileNames;
+        }
+        const matchingFilenameInfo = getFilenameInfo(matchingFileName);
+        (0, jsdocUtils_js_1.forEachPreferredTag)(jsdoc, 'example', (tag, targetTagName) => {
+            let source = /** @type {string} */ ((0, jsdocUtils_js_1.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` is falsy, all languages should be processed.
+            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;
+                    // Count anything preceding user regex match (can affect line numbering)
+                    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;
+                    // Ignore `preMatch` delta if newlines here
+                    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;
+    };
+    // See https://eslint.org/docs/latest/extend/plugins#processors-in-plugins
+    // See https://eslint.org/docs/latest/extend/custom-processors
+    // From https://github.com/eslint/eslint/issues/14745#issuecomment-869457265
+    /*
+      {
+        "files": ["*.js", "*.ts"],
+        "processor": "jsdoc/example" // a pretended value here
+      },
+      {
+        "files": [
+          "*.js/*_jsdoc-example.js",
+          "*.ts/*_jsdoc-example.js",
+          "*.js/*_jsdoc-example.ts"
+        ],
+        "rules": {
+          // specific rules for examples in jsdoc only here
+          // And other rules for `.js` and `.ts` will also be enabled for them
+        }
+      }
+    */
+    return {
+        meta: {
+            name: 'eslint-plugin-jsdoc/processor',
+            version,
+        },
+        processors: {
+            examples: {
+                meta: {
+                    name: 'eslint-plugin-jsdoc/preprocessor',
+                    version,
+                },
+                /**
+                 * @param {import('eslint').Linter.LintMessage[][]} messages
+                 * @param {string} filename
+                 */
+                postprocess([jsMessages, ...messages
+                // eslint-disable-next-line no-unused-vars -- Placeholder
+                ], 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,
+                            // Todo: Make fixable
+                            // fix
+                            // fix: {range: [number, number], text: string}
+                            // suggestions: {desc: , messageId:, fix: }[],
+                             } = msg;
+                            delete msg.fix;
+                            const [codeCtxLine, codeCtxColumn,] = commentLineCols;
+                            const startLine = codeCtxLine + codeStartLine + line;
+                            // Seems to need one more now
+                            const startCol = 1 +
+                                codeCtxColumn + codeStartCol + (
+                            // This might not work for line 0, but line 0 is unlikely for examples
+                            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;
+                            // added `- column` to offset what `endColumn` already seemed to include
+                            msg.endColumn = endColumn ? startCol - column + endColumn : startCol;
+                        }
+                    }
+                    const ret = [
+                        ...jsMessages,
+                    ].concat(...messages, ...extraMessages);
+                    extraMessages = [];
+                    return ret;
+                },
+                /**
+                 * @param {string} text
+                 * @param {string} filename
+                 * @returns {(string | Linter.ProcessorFile)[]}
+                 */
+                preprocess(text, filename) {
+                    try {
+                        let ast;
+                        // May be running a second time so catch and ignore
+                        try {
+                            ast = parser ?
+                                // @ts-expect-error Should be present
+                                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 = /** @type {import('estree').Comment[]} */ (
+                        /**
+                         * @type {import('estree').Program & {
+                         *   comments?: import('estree').Comment[]
+                         * }}
+                         */
+                        (ast).comments).filter((comment) => {
+                            return (/^\*\s/v).test(comment.value);
+                        }).map((comment) => {
+                            const [start,
+                            /* c8 ignore next -- Unsupporting processors only? */
+                            ] = comment.range ?? [];
+                            const textToStart = text.slice(0, start);
+                            const [lines, cols,] = getLinesCols(textToStart);
+                            // const lines = [...textToStart.matchAll(/\n/gv)].length
+                            // const lastLinePos = textToStart.lastIndexOf('\n');
+                            // const cols = lastLinePos === -1
+                            //   ? 0
+                            //   : textToStart.slice(lastLinePos).length;
+                            commentLineCols.push([
+                                lines, cols,
+                            ]);
+                            return (0, jsdoccomment_1.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 !== undefined;
+                            }),
+                        ];
+                        /* c8 ignore next 6 */
+                    }
+                    catch (error) {
+                        // eslint-disable-next-line no-console -- Debugging
+                        console.log('err', filename, error);
+                    }
+                    return [];
+                },
+                supportsAutofix: true,
+            },
+        },
+    };
+};
+exports.getJsdocProcessorPlugin = getJsdocProcessorPlugin;

package/dist/cjs/index-cjs.d.ts

@@ -0,0 +1,16 @@
+export default index;
+export type ConfigGroups = "recommended" | "stylistic" | "contents" | "logical" | "requirements";
+export type ConfigVariants = "" | "-typescript" | "-typescript-flavor";
+export type ErrorLevelVariants = "" | "-error";
+/**
+ * @typedef {"recommended" | "stylistic" | "contents" | "logical" | "requirements"} ConfigGroups
+ * @typedef {"" | "-typescript" | "-typescript-flavor"} ConfigVariants
+ * @typedef {"" | "-error"} ErrorLevelVariants
+ * @type {import('eslint').ESLint.Plugin & {
+ *   configs: Record<`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`,
+ *   import('eslint').Linter.Config>
+ * }}
+ */
+declare const index: import("eslint").ESLint.Plugin & {
+    configs: Record<`flat/${ConfigGroups}${ConfigVariants}${ErrorLevelVariants}`, import("eslint").Linter.Config>;
+};