eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/informativeDocs.js

@@ -1,153 +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 are_docs_informative_1 = require("are-docs-informative");
-const defaultAliases = {
-    a: [
-        'an', 'our',
-    ],
-};
-const defaultUselessWords = [
-    'a', 'an', 'i', 'in', 'of', 's', 'the',
-];
-/* eslint-disable complexity -- Temporary */
-/**
- * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node
- * @returns {string[]}
- */
-const getNamesFromNode = (node) => {
-    switch (node?.type) {
-        case 'AccessorProperty':
-        case 'MethodDefinition':
-        case 'PropertyDefinition':
-        case 'TSAbstractAccessorProperty':
-        case 'TSAbstractMethodDefinition':
-        case 'TSAbstractPropertyDefinition':
-            return [
-                ...getNamesFromNode(
-                /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (node.parent).parent),
-                ...getNamesFromNode(
-                /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-                (node.key)),
-            ];
-        case 'ClassDeclaration':
-        case 'ClassExpression':
-        case 'FunctionDeclaration':
-        case 'FunctionExpression':
-        case 'TSDeclareFunction':
-        case 'TSEnumDeclaration':
-        case 'TSEnumMember':
-        case 'TSInterfaceDeclaration':
-        case 'TSMethodSignature':
-        case 'TSModuleDeclaration':
-        case 'TSTypeAliasDeclaration':
-            return getNamesFromNode(
-            /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */
-            (node).id);
-        case 'ExportDefaultDeclaration':
-        case 'ExportNamedDeclaration':
-            return getNamesFromNode(
-            /** @type {import('@typescript-eslint/types').TSESTree.ExportNamedDeclaration} */
-            (node).declaration);
-        case 'Identifier':
-            return [
-                node.name,
-            ];
-        case 'Property':
-            return getNamesFromNode(
-            /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-            (node.key));
-        case 'VariableDeclaration':
-            return getNamesFromNode(
-            /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-            (node.declarations[0]));
-        case 'VariableDeclarator':
-            return [
-                ...getNamesFromNode(
-                /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-                (node.id)),
-                ...getNamesFromNode(
-                /** @type {import('@typescript-eslint/types').TSESTree.Node} */
-                (node.init)),
-            ].filter(Boolean);
-        default:
-            return [];
-    }
-};
-/* eslint-enable complexity -- Temporary */
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, node, report, utils, }) => {
-    const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ { aliases = defaultAliases, excludedTags = [], uselessWords = defaultUselessWords, } = context.options[0] || {};
-    const nodeNames = getNamesFromNode(node);
-    /**
-     * @param {string} text
-     * @param {string} extraName
-     * @returns {boolean}
-     */
-    const descriptionIsRedundant = (text, extraName = '') => {
-        const textTrimmed = text.trim();
-        return Boolean(textTrimmed) && !(0, are_docs_informative_1.areDocsInformative)(textTrimmed, [
-            extraName, nodeNames,
-        ].filter(Boolean).join(' '), {
-            aliases,
-            uselessWords,
-        });
-    };
-    const { description, lastDescriptionLine, } = utils.getDescription();
-    let descriptionReported = false;
-    for (const tag of jsdoc.tags) {
-        if (excludedTags.includes(tag.tag)) {
-            continue;
-        }
-        if (descriptionIsRedundant(tag.description, tag.name)) {
-            utils.reportJSDoc('This tag description only repeats the name it describes.', tag);
-        }
-        descriptionReported ||= tag.description === description &&
-            /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */
-            (tag).line === lastDescriptionLine;
-    }
-    if (!descriptionReported && descriptionIsRedundant(description)) {
-        report('This description only repeats the name it describes.');
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'This rule reports doc comments that only restate their attached name.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    aliases: {
-                        patternProperties: {
-                            '.*': {
-                                items: {
-                                    type: 'string',
-                                },
-                                type: 'array',
-                            },
-                        },
-                    },
-                    excludedTags: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    uselessWords: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/linesBeforeBlock.js

@@ -1,106 +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"));
-/**
- * Punctuators that begin a logical group should not require a line before it skipped. Specifically
- * `[` starts an array, `{` starts an object or block, `(` starts a grouping, and `=` starts a
- * declaration (like a variable or a type alias).
- */
-const startPunctuators = new Set([
-    '(', '=', '[', '{',
-]);
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdocNode, report, sourceCode, utils, }) => {
-    const { checkBlockStarts, excludedTags = [
-        'type',
-    ], ignoreSameLine = true, ignoreSingleLines = true, lines = 1, } = context.options[0] || {};
-    if (utils.hasATag(excludedTags)) {
-        return;
-    }
-    const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {
-        includeComments: true,
-    });
-    const tokenBefore = tokensBefore.at(-1);
-    if (!tokenBefore || (tokenBefore.type === 'Punctuator' &&
-        !checkBlockStarts &&
-        startPunctuators.has(tokenBefore.value))) {
-        return;
-    }
-    if (tokenBefore.loc?.end?.line + lines >=
-        /** @type {number} */
-        (jsdocNode.loc?.start?.line)) {
-        const startLine = jsdocNode.loc?.start?.line;
-        const sameLine = tokenBefore.loc?.end?.line === startLine;
-        if (sameLine && ignoreSameLine) {
-            return;
-        }
-        if (ignoreSingleLines && jsdocNode.loc?.start.line === jsdocNode.loc?.end.line) {
-            return;
-        }
-        /** @type {import('eslint').Rule.ReportFixer} */
-        const fix = (fixer) => {
-            let indent = '';
-            if (sameLine) {
-                const spaceDiff = /** @type {number} */ (jsdocNode.loc?.start?.column) -
-                    /** @type {number} */ (tokenBefore.loc?.end?.column);
-                // @ts-expect-error Should be a comment
-                indent = /** @type {import('estree').Comment} */ (jsdocNode).value.match(/^\*\n([\t ]*) \*/v)?.[1]?.slice(spaceDiff);
-                if (!indent) {
-                    /** @type {import('eslint').AST.Token|import('estree').Comment|undefined} */
-                    let tokenPrior = tokenBefore;
-                    let startColumn;
-                    while (tokenPrior && tokenPrior?.loc?.start?.line === startLine) {
-                        startColumn = tokenPrior.loc?.start?.column;
-                        tokenPrior = tokensBefore.pop();
-                    }
-                    indent = ' '.repeat(
-                    /* c8 ignore next */
-                    /** @type {number} */ (startColumn ? startColumn - 1 : 0));
-                }
-            }
-            return fixer.insertTextAfter(
-            /** @type {import('eslint').AST.Token} */
-            (tokenBefore), '\n'.repeat(lines) +
-                (sameLine ? '\n' + indent : ''));
-        };
-        report(`Required ${lines} line(s) before JSDoc block`, fix);
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Enforces minimum number of newlines before JSDoc comment blocks',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/lines-before-block.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    checkBlockStarts: {
-                        type: 'boolean',
-                    },
-                    excludedTags: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    ignoreSameLine: {
-                        type: 'boolean',
-                    },
-                    ignoreSingleLines: {
-                        type: 'boolean',
-                    },
-                    lines: {
-                        type: 'integer',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/matchDescription.js

@@ -1,240 +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"));
-// If supporting Node >= 10, we could loosen the default to this for the
-//   initial letter: \\p{Upper}
-const matchDescriptionDefault = '^\n?([A-Z`\\d_][\\s\\S]*[.?!`\\p{RGI_Emoji}]\\s*)?$';
-/**
- * @param {string} value
- * @param {string} userDefault
- * @returns {string}
- */
-const stringOrDefault = (value, userDefault) => {
-    return typeof value === 'string' ?
-        value :
-        userDefault || matchDescriptionDefault;
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, utils, }) => {
-    const { mainDescription, matchDescription, message, nonemptyTags = true, tags = {}, } = context.options[0] || {};
-    /**
-     * @param {string} desc
-     * @param {import('comment-parser').Spec} [tag]
-     * @returns {void}
-     */
-    const validateDescription = (desc, tag) => {
-        let mainDescriptionMatch = mainDescription;
-        let errorMessage = message;
-        if (typeof mainDescription === 'object') {
-            mainDescriptionMatch = mainDescription.match;
-            errorMessage = mainDescription.message;
-        }
-        if (mainDescriptionMatch === false && (!tag || !Object.hasOwn(tags, tag.tag))) {
-            return;
-        }
-        let tagValue = mainDescriptionMatch;
-        if (tag) {
-            const tagName = tag.tag;
-            if (typeof tags[tagName] === 'object') {
-                tagValue = tags[tagName].match;
-                errorMessage = tags[tagName].message;
-            }
-            else {
-                tagValue = tags[tagName];
-            }
-        }
-        const regex = utils.getRegexFromString(stringOrDefault(tagValue, matchDescription));
-        if (!regex.test(desc)) {
-            report(errorMessage || 'JSDoc description does not satisfy the regex pattern.', null, tag || {
-                // Add one as description would typically be into block
-                line: jsdoc.source[0].number + 1,
-            });
-        }
-    };
-    const { description, } = utils.getDescription();
-    if (description) {
-        validateDescription(description);
-    }
-    /**
-     * @param {string} tagName
-     * @returns {boolean}
-     */
-    const hasNoTag = (tagName) => {
-        return !tags[tagName];
-    };
-    for (const tag of [
-        'description',
-        'summary',
-        'file',
-        'classdesc',
-    ]) {
-        utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
-            const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
-            if (hasNoTag(targetTagName)) {
-                validateDescription(desc, matchingJsdocTag);
-            }
-        }, true);
-    }
-    if (nonemptyTags) {
-        for (const tag of [
-            'copyright',
-            'example',
-            'see',
-            'todo',
-        ]) {
-            utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
-                const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
-                if (hasNoTag(targetTagName) && !(/.+/v).test(desc)) {
-                    report('JSDoc description must not be empty.', null, matchingJsdocTag);
-                }
-            });
-        }
-    }
-    if (!Object.keys(tags).length) {
-        return;
-    }
-    /**
-     * @param {string} tagName
-     * @returns {boolean}
-     */
-    const hasOptionTag = (tagName) => {
-        return Boolean(tags[tagName]);
-    };
-    const whitelistedTags = utils.filterTags(({ tag: tagName, }) => {
-        return hasOptionTag(tagName);
-    });
-    const { tagsWithNames, tagsWithoutNames, } = utils.getTagsByType(whitelistedTags);
-    tagsWithNames.some((tag) => {
-        const desc = /** @type {string} */ (utils.getTagDescription(tag)).replace(/^[\- ]*/v, '')
-            .trim();
-        return validateDescription(desc, tag);
-    });
-    tagsWithoutNames.some((tag) => {
-        const desc = (tag.name + ' ' + utils.getTagDescription(tag)).trim();
-        return validateDescription(desc, tag);
-    });
-}, {
-    contextDefaults: true,
-    meta: {
-        docs: {
-            description: 'Enforces a regular expression pattern on descriptions.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-description.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    contexts: {
-                        items: {
-                            anyOf: [
-                                {
-                                    type: 'string',
-                                },
-                                {
-                                    additionalProperties: false,
-                                    properties: {
-                                        comment: {
-                                            type: 'string',
-                                        },
-                                        context: {
-                                            type: 'string',
-                                        },
-                                    },
-                                    type: 'object',
-                                },
-                            ],
-                        },
-                        type: 'array',
-                    },
-                    mainDescription: {
-                        oneOf: [
-                            {
-                                format: 'regex',
-                                type: 'string',
-                            },
-                            {
-                                type: 'boolean',
-                            },
-                            {
-                                additionalProperties: false,
-                                properties: {
-                                    match: {
-                                        oneOf: [
-                                            {
-                                                format: 'regex',
-                                                type: 'string',
-                                            },
-                                            {
-                                                type: 'boolean',
-                                            },
-                                        ],
-                                    },
-                                    message: {
-                                        type: 'string',
-                                    },
-                                },
-                                type: 'object',
-                            },
-                        ],
-                    },
-                    matchDescription: {
-                        format: 'regex',
-                        type: 'string',
-                    },
-                    message: {
-                        type: 'string',
-                    },
-                    nonemptyTags: {
-                        type: 'boolean',
-                    },
-                    tags: {
-                        patternProperties: {
-                            '.*': {
-                                oneOf: [
-                                    {
-                                        format: 'regex',
-                                        type: 'string',
-                                    },
-                                    {
-                                        enum: [
-                                            true,
-                                        ],
-                                        type: 'boolean',
-                                    },
-                                    {
-                                        additionalProperties: false,
-                                        properties: {
-                                            match: {
-                                                oneOf: [
-                                                    {
-                                                        format: 'regex',
-                                                        type: 'string',
-                                                    },
-                                                    {
-                                                        enum: [
-                                                            true,
-                                                        ],
-                                                        type: 'boolean',
-                                                    },
-                                                ],
-                                            },
-                                            message: {
-                                                type: 'string',
-                                            },
-                                        },
-                                        type: 'object',
-                                    },
-                                ],
-                            },
-                        },
-                        type: 'object',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/matchName.js

@@ -1,122 +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"));
-// eslint-disable-next-line complexity
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, info: { lastIndex, }, jsdoc, report, utils, }) => {
-    const { match, } = context.options[0] || {};
-    if (!match) {
-        report('Rule `no-restricted-syntax` is missing a `match` option.');
-        return;
-    }
-    const { allowName, disallowName, replacement, tags = [
-        '*',
-    ], } = match[ /** @type {import('../iterateJsdoc.js').Integer} */(lastIndex)];
-    const allowNameRegex = allowName && utils.getRegexFromString(allowName);
-    const disallowNameRegex = disallowName && utils.getRegexFromString(disallowName);
-    let applicableTags = jsdoc.tags;
-    if (!tags.includes('*')) {
-        applicableTags = utils.getPresentTags(tags);
-    }
-    let reported = false;
-    for (const tag of applicableTags) {
-        const tagName = tag.name.replace(/^\[/v, '').replace(/(=.*)?\]$/v, '');
-        const allowed = !allowNameRegex || allowNameRegex.test(tagName);
-        const disallowed = disallowNameRegex && disallowNameRegex.test(tagName);
-        const hasRegex = allowNameRegex || disallowNameRegex;
-        if (hasRegex && allowed && !disallowed) {
-            continue;
-        }
-        if (!hasRegex && reported) {
-            continue;
-        }
-        const fixer = () => {
-            for (const src of tag.source) {
-                if (src.tokens.name) {
-                    src.tokens.name = src.tokens.name.replace(disallowNameRegex, replacement);
-                    break;
-                }
-            }
-        };
-        let { message, } = match[ /** @type {import('../iterateJsdoc.js').Integer} */(lastIndex)];
-        if (!message) {
-            if (hasRegex) {
-                message = disallowed ?
-                    `Only allowing names not matching \`${disallowNameRegex}\` but found "${tagName}".` :
-                    `Only allowing names matching \`${allowNameRegex}\` but found "${tagName}".`;
-            }
-            else {
-                message = `Prohibited context for "${tagName}".`;
-            }
-        }
-        utils.reportJSDoc(message, hasRegex ? tag : null, 
-        // We could match up
-        disallowNameRegex && replacement !== undefined ?
-            fixer :
-            null, false, {
-            // Could also supply `context`, `comment`, `tags`
-            allowName,
-            disallowName,
-            name: tagName,
-        });
-        if (!hasRegex) {
-            reported = true;
-        }
-    }
-}, {
-    matchContext: true,
-    meta: {
-        docs: {
-            description: 'Reports the name portion of a JSDoc tag if matching or not matching a given regular expression.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-name.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    match: {
-                        items: {
-                            additionalProperties: false,
-                            properties: {
-                                allowName: {
-                                    type: 'string',
-                                },
-                                comment: {
-                                    type: 'string',
-                                },
-                                context: {
-                                    type: 'string',
-                                },
-                                disallowName: {
-                                    type: 'string',
-                                },
-                                message: {
-                                    type: 'string',
-                                },
-                                replacement: {
-                                    type: 'string',
-                                },
-                                tags: {
-                                    items: {
-                                        type: 'string',
-                                    },
-                                    type: 'array',
-                                },
-                            },
-                            type: 'object',
-                        },
-                        type: 'array',
-                    },
-                },
-                required: [
-                    'match',
-                ],
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});