eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/emptyTags.js

@@ -0,0 +1,79 @@
+"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 defaultEmptyTags = new Set([
+    'abstract', 'async', 'generator', 'global', 'hideconstructor',
+    // jsdoc doesn't use this form in its docs, but allow for compatibility with
+    //  TypeScript which allows and Closure which requires
+    'ignore',
+    // jsdoc doesn't use but allow for TypeScript
+    'inheritDoc', 'inner', 'instance',
+    'internal',
+    'overload',
+    'override',
+    'readonly',
+]);
+const emptyIfNotClosure = new Set([
+    // Closure doesn't allow with this casing
+    'inheritdoc', 'package', 'private', 'protected', 'public',
+    'static',
+]);
+const emptyIfClosure = new Set([
+    'interface',
+]);
+exports.default = (0, iterateJsdoc_js_1.default)(({ jsdoc, settings, utils, }) => {
+    const emptyTags = utils.filterTags(({ tag: tagName, }) => {
+        return defaultEmptyTags.has(tagName) ||
+            utils.hasOptionTag(tagName) && jsdoc.tags.some(({ tag, }) => {
+                return tag === tagName;
+            }) ||
+            settings.mode === 'closure' && emptyIfClosure.has(tagName) ||
+            settings.mode !== 'closure' && emptyIfNotClosure.has(tagName);
+    });
+    for (const [key, tag,] of emptyTags.entries()) {
+        const content = tag.name || tag.description || tag.type;
+        if (content.trim() && (
+        // Allow for JSDoc-block final asterisks
+        key !== emptyTags.length - 1 || !(/^\s*\*+$/v).test(content))) {
+            const fix = () => {
+                // By time of call in fixer, `tag` will have `line` added
+                utils.setTag(
+                /**
+                 * @type {import('comment-parser').Spec & {
+                 *   line: import('../iterateJsdoc.js').Integer
+                 * }}
+                 */ (tag));
+            };
+            utils.reportJSDoc(`@${tag.tag} should be empty.`, tag, fix, true);
+        }
+    }
+}, {
+    checkInternal: true,
+    checkPrivate: true,
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Expects specific tags to be empty of any content.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/empty-tags.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    tags: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/implementsOnClasses.js

@@ -0,0 +1,63 @@
+"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)(({ report, utils, }) => {
+    const iteratingFunction = utils.isIteratingFunctionOrVariable();
+    if (iteratingFunction) {
+        if (utils.hasATag([
+            'class',
+            'constructor',
+        ]) ||
+            utils.isConstructor()) {
+            return;
+        }
+    }
+    else if (!utils.isVirtualFunction()) {
+        return;
+    }
+    utils.forEachPreferredTag('implements', (tag) => {
+        report('@implements used on a non-constructor function', null, tag);
+    });
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Reports an issue with any non-constructor function using `@implements`.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/implements-on-classes.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',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/importsAsDependencies.js

@@ -0,0 +1,105 @@
+"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 jsdoccomment_1 = require("@es-joy/jsdoccomment");
+const fs_1 = require("fs");
+const node_module_1 = require("node:module");
+const path_1 = require("path");
+/**
+ * @type {Set<string>|null}
+ */
+let deps;
+const setDeps = function () {
+    try {
+        const pkg = JSON.parse(
+        // @ts-expect-error It's ok
+        (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), './package.json')));
+        deps = new Set([
+            ...(pkg.dependencies ?
+                /* c8 ignore next 2 */
+                Object.keys(pkg.dependencies) :
+                []),
+            ...(pkg.devDependencies ?
+                /* c8 ignore next 2 */
+                Object.keys(pkg.devDependencies) :
+                []),
+        ]);
+        /* c8 ignore next -- our package.json exists */
+    }
+    catch (error) {
+        /* c8 ignore next -- our package.json exists */
+        deps = null;
+        /* c8 ignore next 4 -- our package.json exists */
+        /* eslint-disable no-console -- Inform user */
+        console.log(error);
+        /* eslint-enable no-console -- Inform user */
+    }
+};
+const moduleCheck = new Map();
+exports.default = (0, iterateJsdoc_js_1.default)(({ jsdoc, settings, utils, }) => {
+    if (deps === undefined) {
+        setDeps();
+    }
+    /* c8 ignore next 3 -- our package.json exists */
+    if (deps === null) {
+        return;
+    }
+    const { mode, } = settings;
+    for (const tag of jsdoc.tags) {
+        let typeAst;
+        try {
+            typeAst = mode === 'permissive' ? (0, jsdoccomment_1.tryParse)(tag.type) : (0, jsdoccomment_1.parse)(tag.type, mode);
+        }
+        catch {
+            continue;
+        }
+        // eslint-disable-next-line no-loop-func -- Safe
+        (0, jsdoccomment_1.traverse)(typeAst, (nde) => {
+            /* c8 ignore next 3 -- TS guard */
+            if (deps === null) {
+                return;
+            }
+            if (nde.type === 'JsdocTypeImport') {
+                let mod = nde.element.value.replace(/^(@[^\/]+\/[^\/]+|[^\/]+).*$/v, '$1');
+                if ((/^[.\/]/v).test(mod)) {
+                    return;
+                }
+                if ((0, node_module_1.isBuiltin)(mod)) {
+                    // mod = '@types/node';
+                    // moduleCheck.set(mod, !deps.has(mod));
+                    return;
+                }
+                else if (!moduleCheck.has(mod)) {
+                    let pkg;
+                    try {
+                        pkg = JSON.parse(
+                        // @ts-expect-error It's ok
+                        (0, fs_1.readFileSync)((0, path_1.join)(process.cwd(), 'node_modules', mod, './package.json')));
+                    }
+                    catch {
+                        // Ignore
+                    }
+                    if (!pkg || (!pkg.types && !pkg.typings)) {
+                        mod = `@types/${mod}`;
+                    }
+                    moduleCheck.set(mod, !deps.has(mod));
+                }
+                if (moduleCheck.get(mod)) {
+                    utils.reportJSDoc('import points to package which is not found in dependencies', tag);
+                }
+            }
+        });
+    }
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Reports if JSDoc `import()` statements point to a package which is not listed in `dependencies` or `devDependencies`',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/imports-as-dependencies.md#repos-sticky-header',
+        },
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/informativeDocs.js

@@ -0,0 +1,153 @@
+"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.d.ts

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

package/dist/cjs/rules/linesBeforeBlock.js

@@ -0,0 +1,106 @@
+"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.d.ts

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