eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/requireDescription.js

@@ -1,136 +0,0 @@
-"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.js

@@ -1,258 +0,0 @@
-"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.js

@@ -1,103 +0,0 @@
-"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.js

@@ -1,117 +0,0 @@
-"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];
-        }
-    },
-});