eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/multilineBlocks.js

@@ -0,0 +1,339 @@
+"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 {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {number} requireSingleLineUnderCount
+ */
+const checkForShortTags = (jsdoc, utils, requireSingleLineUnderCount) => {
+    if (!requireSingleLineUnderCount || !jsdoc.tags.length) {
+        return false;
+    }
+    let lastLineWithTag = 0;
+    let isUnderCountLimit = false;
+    let hasMultiDescOrType = false;
+    const tagLines = jsdoc.source.reduce((acc, { tokens: { delimiter, description: desc, name, postDelimiter, postName, postTag, postType, start, tag, type, }, }, idx) => {
+        if (tag.length) {
+            lastLineWithTag = idx;
+            if (start.length + delimiter.length + postDelimiter.length +
+                type.length + postType.length + name.length + postName.length +
+                tag.length + postTag.length + desc.length <
+                requireSingleLineUnderCount) {
+                isUnderCountLimit = true;
+            }
+            return acc + 1;
+        }
+        else if (desc.length || type.length) {
+            hasMultiDescOrType = true;
+            return acc;
+        }
+        return acc;
+    }, 0);
+    // Could be tagLines > 1
+    if (!hasMultiDescOrType && isUnderCountLimit && tagLines === 1) {
+        const fixer = () => {
+            const tokens = jsdoc.source[lastLineWithTag].tokens;
+            jsdoc.source = [
+                {
+                    number: 0,
+                    source: '',
+                    tokens: utils.seedTokens({
+                        delimiter: '/**',
+                        description: tokens.description.trimEnd() + ' ',
+                        end: '*/',
+                        name: tokens.name,
+                        postDelimiter: ' ',
+                        postName: tokens.postName,
+                        postTag: tokens.postTag,
+                        postType: tokens.postType,
+                        start: jsdoc.source[0].tokens.start,
+                        tag: tokens.tag,
+                        type: tokens.type,
+                    }),
+                },
+            ];
+        };
+        utils.reportJSDoc('Description is too short to be multi-line.', null, fixer);
+        return true;
+    }
+    return false;
+};
+/**
+ * @param {import('@es-joy/jsdoccomment').JsdocBlockWithInline} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {number} requireSingleLineUnderCount
+ */
+const checkForShortDescriptions = (jsdoc, utils, requireSingleLineUnderCount) => {
+    if (!requireSingleLineUnderCount || jsdoc.tags.length) {
+        return false;
+    }
+    let lastLineWithDesc = 0;
+    let isUnderCountLimit = false;
+    const descLines = jsdoc.source.reduce((acc, { tokens: { delimiter, description: desc, postDelimiter, start, }, }, idx) => {
+        if (desc.length) {
+            lastLineWithDesc = idx;
+            if (start.length + delimiter.length + postDelimiter.length + desc.length <
+                requireSingleLineUnderCount) {
+                isUnderCountLimit = true;
+            }
+            return acc + 1;
+        }
+        return acc;
+    }, 0);
+    // Could be descLines > 1
+    if (isUnderCountLimit && descLines === 1) {
+        const fixer = () => {
+            const desc = jsdoc.source[lastLineWithDesc].tokens.description;
+            jsdoc.source = [
+                {
+                    number: 0,
+                    source: '',
+                    tokens: utils.seedTokens({
+                        delimiter: '/**',
+                        description: desc.trimEnd() + ' ',
+                        end: '*/',
+                        postDelimiter: ' ',
+                        start: jsdoc.source[0].tokens.start,
+                    }),
+                },
+            ];
+        };
+        utils.reportJSDoc('Description is too short to be multi-line.', null, fixer);
+        return true;
+    }
+    return false;
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
+    const { allowMultipleTags = true, minimumLengthForMultiline = Number.POSITIVE_INFINITY, multilineTags = [
+        '*',
+    ], noFinalLineText = true, noMultilineBlocks = false, noSingleLineBlocks = false, noZeroLineText = true, requireSingleLineUnderCount = null, singleLineTags = [
+        'lends', 'type',
+    ], } = context.options[0] || {};
+    const { source: [{ tokens, },], } = jsdoc;
+    const { description, tag, } = tokens;
+    const sourceLength = jsdoc.source.length;
+    /**
+     * @param {string} tagName
+     * @returns {boolean}
+     */
+    const isInvalidSingleLine = (tagName) => {
+        return noSingleLineBlocks &&
+            (!tagName ||
+                !singleLineTags.includes(tagName) && !singleLineTags.includes('*'));
+    };
+    if (sourceLength === 1) {
+        if (!isInvalidSingleLine(tag.slice(1))) {
+            return;
+        }
+        const fixer = () => {
+            utils.makeMultiline();
+        };
+        utils.reportJSDoc('Single line blocks are not permitted by your configuration.', null, fixer, true);
+        return;
+    }
+    if (checkForShortDescriptions(jsdoc, utils, requireSingleLineUnderCount)) {
+        return;
+    }
+    if (checkForShortTags(jsdoc, utils, requireSingleLineUnderCount)) {
+        return;
+    }
+    const lineChecks = () => {
+        if (noZeroLineText &&
+            (tag || description)) {
+            const fixer = () => {
+                const line = {
+                    ...tokens,
+                };
+                utils.emptyTokens(tokens);
+                const { tokens: { delimiter, start, }, } = jsdoc.source[1];
+                utils.addLine(1, {
+                    ...line,
+                    delimiter,
+                    start,
+                });
+            };
+            utils.reportJSDoc('Should have no text on the "0th" line (after the `/**`).', null, fixer);
+            return;
+        }
+        const finalLine = jsdoc.source[jsdoc.source.length - 1];
+        const finalLineTokens = finalLine.tokens;
+        if (noFinalLineText &&
+            finalLineTokens.description.trim()) {
+            const fixer = () => {
+                const line = {
+                    ...finalLineTokens,
+                };
+                line.description = line.description.trimEnd();
+                const { delimiter, } = line;
+                for (const prop of [
+                    'delimiter',
+                    'postDelimiter',
+                    'tag',
+                    'type',
+                    'lineEnd',
+                    'postType',
+                    'postTag',
+                    'name',
+                    'postName',
+                    'description',
+                ]) {
+                    finalLineTokens[
+                    /**
+                     * @type {"delimiter"|"postDelimiter"|"tag"|"type"|
+                     *   "lineEnd"|"postType"|"postTag"|"name"|
+                     *   "postName"|"description"}
+                     */ (prop)] = '';
+                }
+                utils.addLine(jsdoc.source.length - 1, {
+                    ...line,
+                    delimiter,
+                    end: '',
+                });
+            };
+            utils.reportJSDoc('Should have no text on the final line (before the `*/`).', null, fixer);
+        }
+    };
+    if (noMultilineBlocks) {
+        if (jsdoc.tags.length &&
+            (multilineTags.includes('*') || utils.hasATag(multilineTags))) {
+            lineChecks();
+            return;
+        }
+        if (jsdoc.description.length >= minimumLengthForMultiline) {
+            lineChecks();
+            return;
+        }
+        if (noSingleLineBlocks &&
+            (!jsdoc.tags.length ||
+                !utils.filterTags(({ tag: tg, }) => {
+                    return !isInvalidSingleLine(tg);
+                }).length)) {
+            utils.reportJSDoc('Multiline jsdoc blocks are prohibited by ' +
+                'your configuration but fixing would result in a single ' +
+                'line block which you have prohibited with `noSingleLineBlocks`.');
+            return;
+        }
+        if (jsdoc.tags.length > 1) {
+            if (!allowMultipleTags) {
+                utils.reportJSDoc('Multiline jsdoc blocks are prohibited by ' +
+                    'your configuration but the block has multiple tags.');
+                return;
+            }
+        }
+        else if (jsdoc.tags.length === 1 && jsdoc.description.trim()) {
+            if (!allowMultipleTags) {
+                utils.reportJSDoc('Multiline jsdoc blocks are prohibited by ' +
+                    'your configuration but the block has a description with a tag.');
+                return;
+            }
+        }
+        else {
+            const fixer = () => {
+                jsdoc.source = [
+                    {
+                        number: 1,
+                        source: '',
+                        tokens: jsdoc.source.reduce((obj, { tokens: { description: desc, lineEnd, name: nme, postName, postTag, postType, tag: tg, type: typ, }, }) => {
+                            if (typ) {
+                                obj.type = typ;
+                            }
+                            if (tg && typ && nme) {
+                                obj.postType = postType;
+                            }
+                            if (nme) {
+                                obj.name += nme;
+                            }
+                            if (nme && desc) {
+                                obj.postName = postName;
+                            }
+                            obj.description += desc;
+                            const nameOrDescription = obj.description || obj.name;
+                            if (nameOrDescription && nameOrDescription.slice(-1) !== ' ') {
+                                obj.description += ' ';
+                            }
+                            obj.lineEnd = lineEnd;
+                            // Already filtered for multiple tags
+                            obj.tag += tg;
+                            if (tg) {
+                                obj.postTag = postTag || ' ';
+                            }
+                            return obj;
+                        }, utils.seedTokens({
+                            delimiter: '/**',
+                            end: '*/',
+                            postDelimiter: ' ',
+                        })),
+                    },
+                ];
+            };
+            utils.reportJSDoc('Multiline jsdoc blocks are prohibited by ' +
+                'your configuration.', null, fixer);
+            return;
+        }
+    }
+    lineChecks();
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Controls how and whether jsdoc blocks can be expressed as single or multiple line blocks.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/multiline-blocks.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    allowMultipleTags: {
+                        type: 'boolean',
+                    },
+                    minimumLengthForMultiline: {
+                        type: 'integer',
+                    },
+                    multilineTags: {
+                        anyOf: [
+                            {
+                                enum: [
+                                    '*',
+                                ],
+                                type: 'string',
+                            }, {
+                                items: {
+                                    type: 'string',
+                                },
+                                type: 'array',
+                            },
+                        ],
+                    },
+                    noFinalLineText: {
+                        type: 'boolean',
+                    },
+                    noMultilineBlocks: {
+                        type: 'boolean',
+                    },
+                    noSingleLineBlocks: {
+                        type: 'boolean',
+                    },
+                    noZeroLineText: {
+                        type: 'boolean',
+                    },
+                    requireSingleLineUnderCount: {
+                        type: 'number',
+                    },
+                    singleLineTags: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/noBadBlocks.js

@@ -0,0 +1,88 @@
+"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 comment_parser_1 = require("comment-parser");
+// Neither a single nor 3+ asterisks are valid jsdoc per
+//  https://jsdoc.app/about-getting-started.html#adding-documentation-comments-to-your-code
+const commentRegexp = /^\/\*(?!\*)/v;
+const extraAsteriskCommentRegexp = /^\/\*{3,}/v;
+exports.default = (0, iterateJsdoc_js_1.default)(({ allComments, context, makeReport, sourceCode, }) => {
+    const [{ ignore = [
+        'ts-check',
+        'ts-expect-error',
+        'ts-ignore',
+        'ts-nocheck',
+    ], preventAllMultiAsteriskBlocks = false, } = {},] = context.options;
+    let extraAsterisks = false;
+    const nonJsdocNodes = /** @type {import('estree').Node[]} */ (allComments).filter((comment) => {
+        const commentText = sourceCode.getText(comment);
+        const initialText = commentText.replace(commentRegexp, '').trimStart();
+        if ([
+            'eslint',
+        ].some((directive) => {
+            return initialText.startsWith(directive);
+        })) {
+            return false;
+        }
+        let sliceIndex = 2;
+        if (!commentRegexp.test(commentText)) {
+            const multiline = extraAsteriskCommentRegexp.exec(commentText)?.[0];
+            if (!multiline) {
+                return false;
+            }
+            sliceIndex = multiline.length;
+            extraAsterisks = true;
+            if (preventAllMultiAsteriskBlocks) {
+                return true;
+            }
+        }
+        const tags = ((0, comment_parser_1.parse)(`${commentText.slice(0, 2)}*${commentText.slice(sliceIndex)}`)[0] || {}).tags ?? [];
+        return tags.length && !tags.some(({ tag, }) => {
+            return ignore.includes(tag);
+        });
+    });
+    if (!nonJsdocNodes.length) {
+        return;
+    }
+    for (const node of nonJsdocNodes) {
+        const report = /** @type {import('../iterateJsdoc.js').MakeReport} */ (makeReport)(context, node);
+        // eslint-disable-next-line no-loop-func
+        const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
+            const text = sourceCode.getText(node);
+            return fixer.replaceText(node, extraAsterisks ?
+                text.replace(extraAsteriskCommentRegexp, '/**') :
+                text.replace('/*', '/**'));
+        };
+        report('Expected JSDoc-like comment to begin with two asterisks.', fix);
+    }
+}, {
+    checkFile: true,
+    meta: {
+        docs: {
+            description: 'This rule checks for multi-line-style comments which fail to meet the criteria of a jsdoc block.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-bad-blocks.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    ignore: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    preventAllMultiAsteriskBlocks: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'layout',
+    },
+});

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

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

package/dist/cjs/rules/noBlankBlockDescriptions.js

@@ -0,0 +1,56 @@
+"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 anyWhitespaceLines = /^\s*$/v;
+const atLeastTwoLinesWhitespace = /^[ \t]*\n[ \t]*\n\s*$/v;
+exports.default = (0, iterateJsdoc_js_1.default)(({ jsdoc, utils, }) => {
+    const { description, descriptions, lastDescriptionLine, } = utils.getDescription();
+    const regex = jsdoc.tags.length ?
+        anyWhitespaceLines :
+        atLeastTwoLinesWhitespace;
+    if (descriptions.length && regex.test(description)) {
+        if (jsdoc.tags.length) {
+            utils.reportJSDoc('There should be no blank lines in block descriptions followed by tags.', {
+                line: lastDescriptionLine,
+            }, () => {
+                utils.setBlockDescription(() => {
+                    // Remove all lines
+                    return [];
+                });
+            });
+        }
+        else {
+            utils.reportJSDoc('There should be no extra blank lines in block descriptions not followed by tags.', {
+                line: lastDescriptionLine,
+            }, () => {
+                utils.setBlockDescription((info, seedTokens) => {
+                    return [
+                        // Keep the starting line
+                        {
+                            number: 0,
+                            source: '',
+                            tokens: seedTokens({
+                                ...info,
+                                description: '',
+                            }),
+                        },
+                    ];
+                });
+            });
+        }
+    }
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Detects and removes extra lines of a blank block description',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-block-descriptions.md#repos-sticky-header',
+        },
+        fixable: 'whitespace',
+        schema: [],
+        type: 'layout',
+    },
+});

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

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

package/dist/cjs/rules/noBlankBlocks.js

@@ -0,0 +1,41 @@
+"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, utils, }) => {
+    if (jsdoc.tags.length) {
+        return;
+    }
+    const { description, lastDescriptionLine, } = utils.getDescription();
+    if (description.trim()) {
+        return;
+    }
+    const { enableFixer, } = context.options[0] || {};
+    utils.reportJSDoc('No empty blocks', {
+        line: lastDescriptionLine,
+    }, enableFixer ? () => {
+        jsdoc.source.splice(0);
+    } : null);
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Removes empty blocks with nothing but possibly line breaks',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-blank-blocks.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    enableFixer: {
+                        type: 'boolean',
+                    },
+                },
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/noDefaults.js

@@ -0,0 +1,84 @@
+"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, utils, }) => {
+    const { noOptionalParamNames, } = context.options[0] || {};
+    const paramTags = utils.getPresentTags([
+        'param', 'arg', 'argument',
+    ]);
+    for (const tag of paramTags) {
+        if (noOptionalParamNames && tag.optional) {
+            utils.reportJSDoc(`Optional param names are not permitted on @${tag.tag}.`, tag, () => {
+                utils.changeTag(tag, {
+                    name: tag.name.replace(/([^=]*)(=.+)?/v, '$1'),
+                });
+            });
+        }
+        else if (tag.default) {
+            utils.reportJSDoc(`Defaults are not permitted on @${tag.tag}.`, tag, () => {
+                utils.changeTag(tag, {
+                    name: tag.name.replace(/([^=]*)(=.+)?/v, '[$1]'),
+                });
+            });
+        }
+    }
+    const defaultTags = utils.getPresentTags([
+        'default', 'defaultvalue',
+    ]);
+    for (const tag of defaultTags) {
+        if (tag.description.trim()) {
+            utils.reportJSDoc(`Default values are not permitted on @${tag.tag}.`, tag, () => {
+                utils.changeTag(tag, {
+                    description: '',
+                    postTag: '',
+                });
+            });
+        }
+    }
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'This rule reports defaults being used on the relevant portion of `@param` or `@default`.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-defaults.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                    noOptionalParamNames: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

@@ -0,0 +1,9 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;
+export type ContextObject = {
+    comment: string;
+    context: string;
+    message: string;
+    minimum: import("../iterateJsdoc.js").Integer;
+};
+export type Context = string | ContextObject;