eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/convertToJsdocComments.js

@@ -1,313 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = require("../iterateJsdoc.js");
-const jsdocUtils_js_1 = require("../jsdocUtils.js");
-const jsdoccomment_1 = require("@es-joy/jsdoccomment");
-/** @type {import('eslint').Rule.RuleModule} */
-exports.default = {
-    create(context) {
-        /**
-         * @typedef {import('eslint').AST.Token | import('estree').Comment | {
-         *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-         *   range: [number, number],
-         *   value: string
-         * }} Token
-         */
-        /**
-         * @callback AddComment
-         * @param {boolean|undefined} inlineCommentBlock
-         * @param {Token} comment
-         * @param {string} indent
-         * @param {number} lines
-         * @param {import('eslint').Rule.RuleFixer} fixer
-         */
-        /* c8 ignore next -- Fallback to deprecated method */
-        const { sourceCode = context.getSourceCode(), } = context;
-        const settings = (0, iterateJsdoc_js_1.getSettings)(context);
-        if (!settings) {
-            return {};
-        }
-        const { allowedPrefixes = [
-            '@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-',
-        ], contexts = settings.contexts || [], contextsAfter = /** @type {string[]} */ ([]), contextsBeforeAndAfter = [
-            'VariableDeclarator', 'TSPropertySignature', 'PropertyDefinition',
-        ], enableFixer = true, enforceJsdocLineStyle = 'multi', lineOrBlockStyle = 'both', } = context.options[0] ?? {};
-        let reportingNonJsdoc = false;
-        /**
-         * @param {string} messageId
-         * @param {import('estree').Comment|Token} comment
-         * @param {import('eslint').Rule.Node} node
-         * @param {import('eslint').Rule.ReportFixer} fixer
-         */
-        const report = (messageId, comment, node, fixer) => {
-            const loc = {
-                end: {
-                    column: 0,
-                    /* c8 ignore next 2 -- Guard */
-                    // @ts-expect-error Ok
-                    line: (comment.loc?.start?.line ?? 1),
-                },
-                start: {
-                    column: 0,
-                    /* c8 ignore next 2 -- Guard */
-                    // @ts-expect-error Ok
-                    line: (comment.loc?.start?.line ?? 1),
-                },
-            };
-            context.report({
-                fix: enableFixer ? fixer : null,
-                loc,
-                messageId,
-                node,
-            });
-        };
-        /**
-         * @param {import('eslint').Rule.Node} node
-         * @param {import('eslint').AST.Token | import('estree').Comment | {
-         *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-         *   range: [number, number],
-         *   value: string
-         * }} comment
-         * @param {AddComment} addComment
-         * @param {import('../iterateJsdoc.js').Context[]} ctxts
-         */
-        const getFixer = (node, comment, addComment, ctxts) => {
-            return /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
-                // Default to one line break if the `minLines`/`maxLines` settings allow
-                const lines = settings.minLines === 0 && settings.maxLines >= 1 ? 1 : settings.minLines;
-                let baseNode = 
-                /**
-                 * @type {import('@typescript-eslint/types').TSESTree.Node|import('eslint').Rule.Node}
-                 */ ((0, jsdoccomment_1.getReducedASTNode)(node, sourceCode));
-                const decorator = (0, jsdoccomment_1.getDecorator)(
-                /** @type {import('eslint').Rule.Node} */
-                (baseNode));
-                if (decorator) {
-                    baseNode = /** @type {import('@typescript-eslint/types').TSESTree.Decorator} */ (decorator);
-                }
-                const indent = (0, jsdocUtils_js_1.getIndent)({
-                    text: sourceCode.getText(
-                    /** @type {import('eslint').Rule.Node} */ (baseNode), 
-                    /** @type {import('eslint').AST.SourceLocation} */
-                    (
-                    /** @type {import('eslint').Rule.Node} */ (baseNode).loc).start.column),
-                });
-                const { inlineCommentBlock, } = 
-                /**
-                 * @type {{
-                 *     context: string,
-                 *     inlineCommentBlock: boolean,
-                 *     minLineCount: import('../iterateJsdoc.js').Integer
-                 *   }[]}
-                 */ (ctxts).find((contxt) => {
-                    if (typeof contxt === 'string') {
-                        return false;
-                    }
-                    const { context: ctxt, } = contxt;
-                    return ctxt === node.type;
-                }) || {};
-                return addComment(inlineCommentBlock, comment, indent, lines, fixer);
-            };
-        };
-        /**
-         * @param {import('eslint').AST.Token | import('estree').Comment | {
-         *   type: import('eslint').AST.TokenType|"Line"|"Block"|"Shebang",
-         *   range: [number, number],
-         *   value: string
-         * }} comment
-         * @param {import('eslint').Rule.Node} node
-         * @param {AddComment} addComment
-         * @param {import('../iterateJsdoc.js').Context[]} ctxts
-         */
-        const reportings = (comment, node, addComment, ctxts) => {
-            const fixer = getFixer(node, comment, addComment, ctxts);
-            if (comment.type === 'Block') {
-                if (lineOrBlockStyle === 'line') {
-                    return;
-                }
-                report('blockCommentsJsdocStyle', comment, node, fixer);
-                return;
-            }
-            if (comment.type === 'Line') {
-                if (lineOrBlockStyle === 'block') {
-                    return;
-                }
-                report('lineCommentsJsdocStyle', comment, node, fixer);
-            }
-        };
-        /**
-         * @type {import('../iterateJsdoc.js').CheckJsdoc}
-         */
-        const checkNonJsdoc = (_info, _handler, node) => {
-            const comment = (0, jsdoccomment_1.getNonJsdocComment)(sourceCode, node, settings);
-            if (!comment ||
-                /** @type {string[]} */
-                (allowedPrefixes).some((prefix) => {
-                    return comment.value.trimStart().startsWith(prefix);
-                })) {
-                return;
-            }
-            reportingNonJsdoc = true;
-            /** @type {AddComment} */
-            // eslint-disable-next-line unicorn/consistent-function-scoping -- Avoid conflicts
-            const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-                const insertion = (inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-                    `/** ${commentToAdd.value.trim()} ` :
-                    `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`) +
-                    `*/${'\n'.repeat((lines || 1) - 1)}`;
-                return fixer.replaceText(
-                /** @type {import('eslint').AST.Token} */
-                (commentToAdd), insertion);
-            };
-            reportings(comment, node, addComment, contexts);
-        };
-        /**
-         * @param {import('eslint').Rule.Node} node
-         * @param {import('../iterateJsdoc.js').Context[]} ctxts
-         */
-        const checkNonJsdocAfter = (node, ctxts) => {
-            const comment = (0, jsdoccomment_1.getFollowingComment)(sourceCode, node);
-            if (!comment ||
-                comment.value.startsWith('*') ||
-                /** @type {string[]} */
-                (allowedPrefixes).some((prefix) => {
-                    return comment.value.trimStart().startsWith(prefix);
-                })) {
-                return;
-            }
-            /** @type {AddComment} */
-            const addComment = (inlineCommentBlock, commentToAdd, indent, lines, fixer) => {
-                const insertion = (inlineCommentBlock || enforceJsdocLineStyle === 'single' ?
-                    `/** ${commentToAdd.value.trim()} ` :
-                    `/**\n${indent}*${commentToAdd.value.trimEnd()}\n${indent}`) +
-                    `*/${'\n'.repeat((lines || 1) - 1)}${lines ? `\n${indent.slice(1)}` : ' '}`;
-                return [
-                    fixer.remove(
-                    /** @type {import('eslint').AST.Token} */
-                    (commentToAdd)), fixer.insertTextBefore(node.type === 'VariableDeclarator' ? node.parent : node, insertion),
-                ];
-            };
-            reportings(comment, node, addComment, ctxts);
-        };
-        // Todo: add contexts to check after (and handle if want both before and after)
-        return {
-            ...(0, jsdocUtils_js_1.getContextObject)((0, jsdocUtils_js_1.enforcedContexts)(context, true, settings), checkNonJsdoc),
-            ...(0, jsdocUtils_js_1.getContextObject)(contextsAfter, (_info, _handler, node) => {
-                checkNonJsdocAfter(node, contextsAfter);
-            }),
-            ...(0, jsdocUtils_js_1.getContextObject)(contextsBeforeAndAfter, (_info, _handler, node) => {
-                checkNonJsdoc({}, null, node);
-                if (!reportingNonJsdoc) {
-                    checkNonJsdocAfter(node, contextsBeforeAndAfter);
-                }
-            }),
-        };
-    },
-    meta: {
-        docs: {
-            description: 'Converts non-JSDoc comments preceding or following nodes into JSDoc ones',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/convert-to-jsdoc-comments.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        messages: {
-            blockCommentsJsdocStyle: 'Block comments should be JSDoc-style.',
-            lineCommentsJsdocStyle: 'Line comments should be JSDoc-style.',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    allowedPrefixes: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    contexts: {
-                        items: {
-                            anyOf: [
-                                {
-                                    type: 'string',
-                                },
-                                {
-                                    additionalProperties: false,
-                                    properties: {
-                                        context: {
-                                            type: 'string',
-                                        },
-                                        inlineCommentBlock: {
-                                            type: 'boolean',
-                                        },
-                                    },
-                                    type: 'object',
-                                },
-                            ],
-                        },
-                        type: 'array',
-                    },
-                    contextsAfter: {
-                        items: {
-                            anyOf: [
-                                {
-                                    type: 'string',
-                                },
-                                {
-                                    additionalProperties: false,
-                                    properties: {
-                                        context: {
-                                            type: 'string',
-                                        },
-                                        inlineCommentBlock: {
-                                            type: 'boolean',
-                                        },
-                                    },
-                                    type: 'object',
-                                },
-                            ],
-                        },
-                        type: 'array',
-                    },
-                    contextsBeforeAndAfter: {
-                        items: {
-                            anyOf: [
-                                {
-                                    type: 'string',
-                                },
-                                {
-                                    additionalProperties: false,
-                                    properties: {
-                                        context: {
-                                            type: 'string',
-                                        },
-                                        inlineCommentBlock: {
-                                            type: 'boolean',
-                                        },
-                                    },
-                                    type: 'object',
-                                },
-                            ],
-                        },
-                        type: 'array',
-                    },
-                    enableFixer: {
-                        type: 'boolean',
-                    },
-                    enforceJsdocLineStyle: {
-                        enum: [
-                            'multi', 'single',
-                        ],
-                        type: 'string',
-                    },
-                    lineOrBlockStyle: {
-                        enum: [
-                            'block', 'line', 'both',
-                        ],
-                        type: 'string',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-};

package/dist/cjs/rules/emptyTags.js

@@ -1,79 +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 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.js

@@ -1,63 +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)(({ 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.js

@@ -1,105 +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 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',
-    },
-});