eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/requireDescription.js

@@ -0,0 +1,136 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+/**
+ * @param {string} description
+ * @returns {import('../iterateJsdoc.js').Integer}
+ */
+const checkDescription = (description) => {
+    return description
+        .trim()
+        .split('\n')
+        .filter(Boolean)
+        .length;
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, utils, }) => {
+    if (utils.avoidDocs()) {
+        return;
+    }
+    const { descriptionStyle = 'body', } = context.options[0] || {};
+    let targetTagName = utils.getPreferredTagName({
+        // We skip reporting except when `@description` is essential to the rule,
+        //  so user can block the tag and still meaningfully use this rule
+        //  even if the tag is present (and `check-tag-names` is the one to
+        //  normally report the fact that it is blocked but present)
+        skipReportingBlockedTag: descriptionStyle !== 'tag',
+        tagName: 'description',
+    });
+    if (!targetTagName) {
+        return;
+    }
+    const isBlocked = typeof targetTagName === 'object' && 'blocked' in targetTagName && targetTagName.blocked;
+    if (isBlocked) {
+        targetTagName = /** @type {{blocked: true; tagName: string;}} */ (targetTagName).tagName;
+    }
+    if (descriptionStyle !== 'tag') {
+        const { description, } = utils.getDescription();
+        if (checkDescription(description || '')) {
+            return;
+        }
+        if (descriptionStyle === 'body') {
+            const descTags = utils.getPresentTags([
+                'desc', 'description',
+            ]);
+            if (descTags.length) {
+                const [{ tag: tagName, },] = descTags;
+                report(`Remove the @${tagName} tag to leave a plain block description or add additional description text above the @${tagName} line.`);
+            }
+            else {
+                report('Missing JSDoc block description.');
+            }
+            return;
+        }
+    }
+    const functionExamples = isBlocked ?
+        [] :
+        jsdoc.tags.filter(({ tag, }) => {
+            return tag === targetTagName;
+        });
+    if (!functionExamples.length) {
+        report(descriptionStyle === 'any' ?
+            `Missing JSDoc block description or @${targetTagName} declaration.` :
+            `Missing JSDoc @${targetTagName} declaration.`);
+        return;
+    }
+    for (const example of functionExamples) {
+        if (!checkDescription(`${example.name} ${utils.getTagDescription(example)}`)) {
+            report(`Missing JSDoc @${targetTagName} description.`, null, example);
+        }
+    }
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that all functions have a description.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description.md#repos-sticky-header',
+        },
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    checkConstructors: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkGetters: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkSetters: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                    descriptionStyle: {
+                        enum: [
+                            'body', 'tag', 'any',
+                        ],
+                        type: 'string',
+                    },
+                    exemptedBy: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireDescriptionCompleteSentence.js

@@ -0,0 +1,258 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+const escape_string_regexp_1 = __importDefault(require("escape-string-regexp"));
+const otherDescriptiveTags = new Set([
+    'classdesc', 'deprecated', 'exception', 'file', 'fileoverview', 'overview',
+    // 'copyright' and 'see' might be good addition, but as the former may be
+    //   sensitive text, and the latter may have just a link, they are not
+    //   included by default
+    'summary', 'throws', 'todo', 'yield', 'yields',
+]);
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+const extractParagraphs = (text) => {
+    return text.split(/(?<![;:])\n\n+/v);
+};
+/**
+ * @param {string} text
+ * @param {string|RegExp} abbreviationsRegex
+ * @returns {string[]}
+ */
+const extractSentences = (text, abbreviationsRegex) => {
+    const txt = text
+        // Remove all {} tags.
+        .replaceAll(/(?<!^)\{[\s\S]*?\}\s*/gv, '')
+        // Remove custom abbreviations
+        .replace(abbreviationsRegex, '');
+    const sentenceEndGrouping = /([.?!])(?:\s+|$)/gv;
+    const puncts = [
+        ...txt.matchAll(sentenceEndGrouping),
+    ].map((sentEnd) => {
+        return sentEnd[0];
+    });
+    return txt
+        .split(/[.?!](?:\s+|$)/v)
+        // Re-add the dot.
+        .map((sentence, idx) => {
+        return !puncts[idx] && /^\s*$/v.test(sentence) ? sentence : `${sentence}${puncts[idx] || ''}`;
+    });
+};
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+const isNewLinePrecededByAPeriod = (text) => {
+    /** @type {boolean} */
+    let lastLineEndsSentence;
+    const lines = text.split('\n');
+    return !lines.some((line) => {
+        if (lastLineEndsSentence === false && /^[A-Z][a-z]/v.test(line)) {
+            return true;
+        }
+        lastLineEndsSentence = /[.:?!\|]$/v.test(line);
+        return false;
+    });
+};
+/**
+ * @param {string} str
+ * @returns {boolean}
+ */
+const isCapitalized = (str) => {
+    return str[0] === str[0].toUpperCase();
+};
+/**
+ * @param {string} str
+ * @returns {boolean}
+ */
+const isTable = (str) => {
+    return str.charAt(0) === '|';
+};
+/**
+ * @param {string} str
+ * @returns {string}
+ */
+const capitalize = (str) => {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+};
+/**
+ * @param {string} description
+ * @param {import('../iterateJsdoc.js').Report} reportOrig
+ * @param {import('eslint').Rule.Node} jsdocNode
+ * @param {string|RegExp} abbreviationsRegex
+ * @param {import('eslint').SourceCode} sourceCode
+ * @param {import('comment-parser').Spec|{
+ *   line: import('../iterateJsdoc.js').Integer
+ * }} tag
+ * @param {boolean} newlineBeforeCapsAssumesBadSentenceEnd
+ * @returns {boolean}
+ */
+const validateDescription = (description, reportOrig, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd) => {
+    if (!description || (/^\n+$/v).test(description)) {
+        return false;
+    }
+    const descriptionNoHeadings = description.replaceAll(/^\s*#[^\n]*(\n|$)/gmv, '');
+    const paragraphs = extractParagraphs(descriptionNoHeadings).filter(Boolean);
+    return paragraphs.some((paragraph, parIdx) => {
+        const sentences = extractSentences(paragraph, abbreviationsRegex);
+        const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
+            let text = sourceCode.getText(jsdocNode);
+            if (!/[.:?!]$/v.test(paragraph)) {
+                const line = paragraph.split('\n').findLast(Boolean);
+                text = text.replace(new RegExp(`${(0, escape_string_regexp_1.default)(
+                /** @type {string} */
+                (line))}$`, 'mv'), `${line}.`);
+            }
+            for (const sentence of sentences.filter((sentence_) => {
+                return !(/^\s*$/v).test(sentence_) && !isCapitalized(sentence_) &&
+                    !isTable(sentence_);
+            })) {
+                const beginning = sentence.split('\n')[0];
+                if ('tag' in tag && tag.tag) {
+                    const reg = new RegExp(`(@${(0, escape_string_regexp_1.default)(tag.tag)}.*)${(0, escape_string_regexp_1.default)(beginning)}`, 'v');
+                    text = text.replace(reg, (_$0, $1) => {
+                        return $1 + capitalize(beginning);
+                    });
+                }
+                else {
+                    text = text.replace(new RegExp('((?:[.?!]|\\*|\\})\\s*)' + (0, escape_string_regexp_1.default)(beginning), 'v'), '$1' + capitalize(beginning));
+                }
+            }
+            return fixer.replaceText(jsdocNode, text);
+        };
+        /**
+         * @param {string} msg
+         * @param {import('eslint').Rule.ReportFixer | null | undefined} fixer
+         * @param {{
+         *   line?: number | undefined;
+         *   column?: number | undefined;
+         * } | (import('comment-parser').Spec & {
+         *   line?: number | undefined;
+         *   column?: number | undefined;
+         * })} tagObj
+         * @returns {void}
+         */
+        const report = (msg, fixer, tagObj) => {
+            if ('line' in tagObj) {
+                /**
+                 * @type {{
+                 *   line: number;
+                 * }}
+                 */ (tagObj).line += parIdx * 2;
+            }
+            else {
+                /** @type {import('comment-parser').Spec} */ (tagObj).source[0].number += parIdx * 2;
+            }
+            // Avoid errors if old column doesn't exist here
+            tagObj.column = 0;
+            reportOrig(msg, fixer, tagObj);
+        };
+        if (sentences.some((sentence) => {
+            return (/^[.?!]$/v).test(sentence);
+        })) {
+            report('Sentences must be more than punctuation.', null, tag);
+        }
+        if (sentences.some((sentence) => {
+            return !(/^\s*$/v).test(sentence) && !isCapitalized(sentence) && !isTable(sentence);
+        })) {
+            report('Sentences should start with an uppercase character.', fix, tag);
+        }
+        const paragraphNoAbbreviations = paragraph.replace(abbreviationsRegex, '');
+        if (!/(?:[.?!\|]|```)\s*$/v.test(paragraphNoAbbreviations)) {
+            report('Sentences must end with a period.', fix, tag);
+            return true;
+        }
+        if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {
+            report('A line of text is started with an uppercase character, but the preceding line does not end the sentence.', null, tag);
+            return true;
+        }
+        return false;
+    });
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, jsdocNode, report, sourceCode, utils, }) => {
+    const /** @type {{abbreviations: string[], newlineBeforeCapsAssumesBadSentenceEnd: boolean}} */ { abbreviations = [], newlineBeforeCapsAssumesBadSentenceEnd = false, } = context.options[0] || {};
+    const abbreviationsRegex = abbreviations.length ?
+        new RegExp('\\b' + abbreviations.map((abbreviation) => {
+            return (0, escape_string_regexp_1.default)(abbreviation.replaceAll(/\.$/gv, '') + '.');
+        }).join('|') + '(?:$|\\s)', 'gv') :
+        '';
+    let { description, } = utils.getDescription();
+    const indices = [
+        ...description.matchAll(/```[\s\S]*```/gv),
+    ].map((match) => {
+        const { index, } = match;
+        const [{ length, },] = match;
+        return {
+            index,
+            length,
+        };
+    }).toReversed();
+    for (const { index, length, } of indices) {
+        description = description.slice(0, index) +
+            description.slice(/** @type {import('../iterateJsdoc.js').Integer} */ (index) + length);
+    }
+    if (validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, {
+        line: jsdoc.source[0].number + 1,
+    }, newlineBeforeCapsAssumesBadSentenceEnd)) {
+        return;
+    }
+    utils.forEachPreferredTag('description', (matchingJsdocTag) => {
+        const desc = `${matchingJsdocTag.name} ${utils.getTagDescription(matchingJsdocTag)}`.trim();
+        validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);
+    }, true);
+    const { tagsWithNames, } = utils.getTagsByType(jsdoc.tags);
+    const tagsWithoutNames = utils.filterTags(({ tag: tagName, }) => {
+        return otherDescriptiveTags.has(tagName) ||
+            utils.hasOptionTag(tagName) && !tagsWithNames.some(({ tag, }) => {
+                // If user accidentally adds tags with names (or like `returns`
+                //  get parsed as having names), do not add to this list
+                return tag === tagName;
+            });
+    });
+    tagsWithNames.some((tag) => {
+        const desc = /** @type {string} */ (utils.getTagDescription(tag)).replace(/^- /v, '').trimEnd();
+        return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
+    });
+    tagsWithoutNames.some((tag) => {
+        const desc = `${tag.name} ${utils.getTagDescription(tag)}`.trim();
+        return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);
+    });
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description-complete-sentence.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    abbreviations: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    newlineBeforeCapsAssumesBadSentenceEnd: {
+                        type: 'boolean',
+                    },
+                    tags: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

package/dist/cjs/rules/requireExample.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireExample.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, utils, }) => {
+    if (utils.avoidDocs()) {
+        return;
+    }
+    const { enableFixer = true, exemptNoArguments = false, } = context.options[0] || {};
+    const targetTagName = 'example';
+    const functionExamples = jsdoc.tags.filter(({ tag, }) => {
+        return tag === targetTagName;
+    });
+    if (!functionExamples.length) {
+        if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&
+            !utils.hasParams()) {
+            return;
+        }
+        utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
+            if (enableFixer) {
+                utils.addTag(targetTagName);
+            }
+        });
+        return;
+    }
+    for (const example of functionExamples) {
+        const exampleContent = `${example.name} ${utils.getTagDescription(example)}`
+            .trim()
+            .split('\n')
+            .filter(Boolean);
+        if (!exampleContent.length) {
+            report(`Missing JSDoc @${targetTagName} description.`, null, example);
+        }
+    }
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that all functions have examples.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    checkConstructors: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkGetters: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    checkSetters: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                    enableFixer: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    exemptedBy: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    exemptNoArguments: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

package/dist/cjs/rules/requireFileOverview.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireFileOverview.js

@@ -0,0 +1,117 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+const defaultTags = {
+    file: {
+        initialCommentsOnly: true,
+        mustExist: true,
+        preventDuplicates: true,
+    },
+};
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @returns {void}
+ */
+const setDefaults = (state) => {
+    // First iteration
+    if (!state.globalTags) {
+        state.globalTags = {};
+        state.hasDuplicates = {};
+        state.hasTag = {};
+        state.hasNonCommentBeforeTag = {};
+    }
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdocNode, state, utils, }) => {
+    const { tags = defaultTags, } = context.options[0] || {};
+    setDefaults(state);
+    for (const tagName of Object.keys(tags)) {
+        const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+            tagName,
+        }));
+        const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));
+        state.hasTag[tagName] = hasTag || state.hasTag[tagName];
+        const hasDuplicate = state.hasDuplicates[tagName];
+        if (hasDuplicate === false) {
+            // Was marked before, so if a tag now, is a dupe
+            state.hasDuplicates[tagName] = hasTag;
+        }
+        else if (!hasDuplicate && hasTag) {
+            // No dupes set before, but has first tag, so change state
+            //   from `undefined` to `false` so can detect next time
+            state.hasDuplicates[tagName] = false;
+            state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&
+                state.hasNonComment < jsdocNode.range[0];
+        }
+    }
+}, {
+    exit({ context, state, utils, }) {
+        setDefaults(state);
+        const { tags = defaultTags, } = context.options[0] || {};
+        for (const [tagName, { initialCommentsOnly = false, mustExist = false, preventDuplicates = false, },] of Object.entries(tags)) {
+            const obj = utils.getPreferredTagNameObject({
+                tagName,
+            });
+            if (obj && typeof obj === 'object' && 'blocked' in obj) {
+                utils.reportSettings(`\`settings.jsdoc.tagNamePreference\` cannot block @${obj.tagName} ` +
+                    'for the `require-file-overview` rule');
+            }
+            else {
+                const targetTagName = (obj && typeof obj === 'object' && obj.replacement) || obj;
+                if (mustExist && !state.hasTag[tagName]) {
+                    utils.reportSettings(`Missing @${targetTagName}`);
+                }
+                if (preventDuplicates && state.hasDuplicates[tagName]) {
+                    utils.reportSettings(`Duplicate @${targetTagName}`);
+                }
+                if (initialCommentsOnly &&
+                    state.hasNonCommentBeforeTag[tagName]) {
+                    utils.reportSettings(`@${targetTagName} should be at the beginning of the file`);
+                }
+            }
+        }
+    },
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',
+        },
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    tags: {
+                        patternProperties: {
+                            '.*': {
+                                additionalProperties: false,
+                                properties: {
+                                    initialCommentsOnly: {
+                                        type: 'boolean',
+                                    },
+                                    mustExist: {
+                                        type: 'boolean',
+                                    },
+                                    preventDuplicates: {
+                                        type: 'boolean',
+                                    },
+                                },
+                                type: 'object',
+                            },
+                        },
+                        type: 'object',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+    nonComment({ node, state, }) {
+        if (!state.hasNonComment) {
+            state.hasNonComment = node.range[0];
+        }
+    },
+});

package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;