eslint-plugin-jsdoc 56.0.0 → 56.0.2

package/dist/cjs/rules/noUndefinedTypes.js

@@ -1,451 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importStar(require("../iterateJsdoc.js"));
-const jsdoccomment_1 = require("@es-joy/jsdoccomment");
-const parse_imports_exports_1 = require("parse-imports-exports");
-const extraTypes = [
-    'null', 'undefined', 'void', 'string', 'boolean', 'object',
-    'function', 'symbol',
-    'number', 'bigint', 'NaN', 'Infinity',
-    'any', '*', 'never', 'unknown', 'const',
-    'this', 'true', 'false',
-    'Array', 'Object', 'RegExp', 'Date', 'Function', 'Intl',
-];
-const typescriptGlobals = [
-    // https://www.typescriptlang.org/docs/handbook/utility-types.html
-    'Awaited',
-    'Partial',
-    'Required',
-    'Readonly',
-    'Record',
-    'Pick',
-    'Omit',
-    'Exclude',
-    'Extract',
-    'NonNullable',
-    'Parameters',
-    'ConstructorParameters',
-    'ReturnType',
-    'InstanceType',
-    'ThisParameterType',
-    'OmitThisParameter',
-    'ThisType',
-    'Uppercase',
-    'Lowercase',
-    'Capitalize',
-    'Uncapitalize',
-];
-/**
- * @param {string|false|undefined} [str]
- * @returns {undefined|string|false}
- */
-const stripPseudoTypes = (str) => {
-    return str && str.replace(/(?:\.|<>|\.<>|\[\])$/v, '');
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, node, report, settings, sourceCode, utils, }) => {
-    const { scopeManager, } = sourceCode;
-    // When is this ever `null`?
-    const globalScope = /** @type {import('eslint').Scope.Scope} */ (scopeManager.globalScope);
-    const 
-    /**
-     * @type {{
-     *   definedTypes: string[],
-     *   disableReporting: boolean,
-     *   markVariablesAsUsed: boolean
-     * }}
-     */ { definedTypes = [], disableReporting = false, markVariablesAsUsed = true, } = context.options[0] || {};
-    /** @type {(string|undefined)[]} */
-    let definedPreferredTypes = [];
-    const { mode, preferredTypes, structuredTags, } = settings;
-    if (Object.keys(preferredTypes).length) {
-        definedPreferredTypes = /** @type {string[]} */ (Object.values(preferredTypes).map((preferredType) => {
-            if (typeof preferredType === 'string') {
-                // May become an empty string but will be filtered out below
-                return stripPseudoTypes(preferredType);
-            }
-            if (!preferredType) {
-                return undefined;
-            }
-            if (typeof preferredType !== 'object') {
-                utils.reportSettings('Invalid `settings.jsdoc.preferredTypes`. Values must be falsy, a string, or an object.');
-            }
-            return stripPseudoTypes(preferredType.replacement);
-        })
-            .filter(Boolean));
-    }
-    const allComments = sourceCode.getAllComments();
-    const comments = allComments
-        .filter((comment) => {
-        return (/^\*\s/v).test(comment.value);
-    })
-        .map((commentNode) => {
-        return (0, iterateJsdoc_js_1.parseComment)(commentNode, '');
-    });
-    const globals = allComments
-        .filter((comment) => {
-        return (/^\s*globals/v).test(comment.value);
-    }).flatMap((commentNode) => {
-        return commentNode.value.replace(/^\s*globals/v, '').trim().split(/,\s*/v);
-    }).concat(Object.keys(context.languageOptions.globals ?? []));
-    const typedefDeclarations = comments
-        .flatMap((doc) => {
-        return doc.tags.filter(({ tag, }) => {
-            return utils.isNamepathDefiningTag(tag);
-        });
-    })
-        .map((tag) => {
-        return tag.name;
-    });
-    const importTags = settings.mode === 'typescript' ? /** @type {string[]} */ (comments.flatMap((doc) => {
-        return doc.tags.filter(({ tag, }) => {
-            return tag === 'import';
-        });
-    }).flatMap((tag) => {
-        const { description, name, type, } = tag;
-        const typePart = type ? `{${type}} ` : '';
-        const imprt = 'import ' + (description ?
-            `${typePart}${name} ${description}` :
-            `${typePart}${name}`);
-        const importsExports = (0, parse_imports_exports_1.parseImportsExports)(imprt.trim());
-        const types = [];
-        const namedImports = Object.values(importsExports.namedImports || {})[0]?.[0];
-        if (namedImports) {
-            if (namedImports.default) {
-                types.push(namedImports.default);
-            }
-            if (namedImports.names) {
-                types.push(...Object.keys(namedImports.names));
-            }
-        }
-        const namespaceImports = Object.values(importsExports.namespaceImports || {})[0]?.[0];
-        if (namespaceImports) {
-            if (namespaceImports.namespace) {
-                types.push(namespaceImports.namespace);
-            }
-            if (namespaceImports.default) {
-                types.push(namespaceImports.default);
-            }
-        }
-        return types;
-    }).filter(Boolean)) : [];
-    const ancestorNodes = [];
-    let currentNode = node;
-    // No need for Program node?
-    while (currentNode?.parent) {
-        ancestorNodes.push(currentNode);
-        currentNode = currentNode.parent;
-    }
-    /**
-     * @param {import('eslint').Rule.Node} ancestorNode
-     * @returns {import('comment-parser').Spec[]}
-     */
-    const getTemplateTags = function (ancestorNode) {
-        const commentNode = (0, jsdoccomment_1.getJSDocComment)(sourceCode, ancestorNode, settings);
-        if (!commentNode) {
-            return [];
-        }
-        const jsdoc = (0, iterateJsdoc_js_1.parseComment)(commentNode, '');
-        return jsdoc.tags.filter((tag) => {
-            return tag.tag === 'template';
-        });
-    };
-    // `currentScope` may be `null` or `Program`, so in such a case,
-    //  we look to present tags instead
-    const templateTags = ancestorNodes.length ?
-        ancestorNodes.flatMap((ancestorNode) => {
-            return getTemplateTags(ancestorNode);
-        }) :
-        utils.getPresentTags([
-            'template',
-        ]);
-    const closureGenericTypes = templateTags.flatMap((tag) => {
-        return utils.parseClosureTemplateTag(tag);
-    });
-    // In modules, including Node, there is a global scope at top with the
-    //  Program scope inside
-    const cjsOrESMScope = globalScope.childScopes[0]?.block?.type === 'Program';
-    /**
-     * @param {import("eslint").Scope.Scope | null} scope
-     * @returns {Set<string>}
-     */
-    const getValidRuntimeIdentifiers = (scope) => {
-        const result = new Set();
-        let scp = scope;
-        while (scp) {
-            for (const { name, } of scp.variables) {
-                result.add(name);
-            }
-            scp = scp.upper;
-        }
-        return result;
-    };
-    /**
-     * We treat imports differently as we can't introspect their children.
-     * @type {string[]}
-     */
-    const imports = [];
-    const allDefinedTypes = new Set(globalScope.variables.map(({ name, }) => {
-        return name;
-    })
-        // If the file is a module, concat the variables from the module scope.
-        .concat(cjsOrESMScope ?
-        globalScope.childScopes.flatMap(({ variables, }) => {
-            return variables;
-        }).flatMap(({ identifiers, name, }) => {
-            const globalItem = /** @type {import('estree').Identifier & {parent: import('@typescript-eslint/types').TSESTree.Node}} */ (identifiers?.[0])?.parent;
-            switch (globalItem?.type) {
-                case 'ClassDeclaration':
-                    return [
-                        name,
-                        ...globalItem.body.body.map((item) => {
-                            const property = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
-                            /** @type {import('@typescript-eslint/types').TSESTree.PropertyDefinition} */ (item)?.key)?.name;
-                            /* c8 ignore next 3 -- Guard */
-                            if (!property) {
-                                return '';
-                            }
-                            return `${name}.${property}`;
-                        }).filter(Boolean),
-                    ];
-                case 'ImportDefaultSpecifier':
-                case 'ImportNamespaceSpecifier':
-                case 'ImportSpecifier':
-                    imports.push(name);
-                    break;
-                case 'TSInterfaceDeclaration':
-                    return [
-                        name,
-                        ...globalItem.body.body.map((item) => {
-                            const property = /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
-                            /** @type {import('@typescript-eslint/types').TSESTree.TSPropertySignature} */ (item)?.key)?.name;
-                            /* c8 ignore next 3 -- Guard */
-                            if (!property) {
-                                return '';
-                            }
-                            return `${name}.${property}`;
-                        }).filter(Boolean),
-                    ];
-                case 'VariableDeclarator':
-                    if ( /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */(
-                    /** @type {import('@typescript-eslint/types').TSESTree.CallExpression} */ (globalItem?.init)?.callee)?.name === 'require') {
-                        imports.push(/** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (globalItem.id).name);
-                        break;
-                    }
-                    return [];
-            }
-            return [
-                name,
-            ];
-            /* c8 ignore next */
-        }) : [])
-        .concat(extraTypes)
-        .concat(typedefDeclarations)
-        .concat(importTags)
-        .concat(definedTypes)
-        .concat(/** @type {string[]} */ (definedPreferredTypes))
-        .concat((() => {
-        // Other methods are not in scope, but we need them, and we grab them here
-        if (node?.type === 'MethodDefinition') {
-            return /** @type {import('estree').ClassBody} */ (node.parent).body.flatMap((methodOrProp) => {
-                if (methodOrProp.type === 'MethodDefinition') {
-                    // eslint-disable-next-line unicorn/no-lonely-if -- Pattern
-                    if (methodOrProp.key.type === 'Identifier') {
-                        return [
-                            methodOrProp.key.name,
-                            `${ /** @type {import('estree').ClassDeclaration} */(node.parent?.parent)?.id?.name}.${methodOrProp.key.name}`,
-                        ];
-                    }
-                }
-                if (methodOrProp.type === 'PropertyDefinition') {
-                    // eslint-disable-next-line unicorn/no-lonely-if -- Pattern
-                    if (methodOrProp.key.type === 'Identifier') {
-                        return [
-                            methodOrProp.key.name,
-                            `${ /** @type {import('estree').ClassDeclaration} */(node.parent?.parent)?.id?.name}.${methodOrProp.key.name}`,
-                        ];
-                    }
-                }
-                /* c8 ignore next 2 -- Not yet built */
-                return '';
-            }).filter(Boolean);
-        }
-        return [];
-    })())
-        .concat(...getValidRuntimeIdentifiers(node && ((sourceCode.getScope &&
-        /* c8 ignore next 3 */
-        sourceCode.getScope(node)) ||
-        // @ts-expect-error ESLint 8
-        context.getScope())))
-        .concat(settings.mode === 'jsdoc' ?
-        [] :
-        [
-            ...settings.mode === 'typescript' ? typescriptGlobals : [],
-            ...closureGenericTypes,
-        ]));
-    /**
-     * @typedef {{
-     *   parsedType: import('jsdoc-type-pratt-parser').RootResult;
-     *   tag: import('comment-parser').Spec|import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
-     *     line?: import('../iterateJsdoc.js').Integer
-     *   }
-     * }} TypeAndTagInfo
-     */
-    /**
-     * @param {string} propertyName
-     * @returns {(tag: (import('@es-joy/jsdoccomment').JsdocInlineTagNoType & {
-     *     name?: string,
-     *     type?: string,
-     *     line?: import('../iterateJsdoc.js').Integer
-     *   })|import('comment-parser').Spec & {
-     *     namepathOrURL?: string
-     *   }
-     * ) => undefined|TypeAndTagInfo}
-     */
-    const tagToParsedType = (propertyName) => {
-        return (tag) => {
-            try {
-                const potentialType = tag[
-                /** @type {"type"|"name"|"namepathOrURL"} */ (propertyName)];
-                return {
-                    parsedType: mode === 'permissive' ?
-                        (0, jsdoccomment_1.tryParse)(/** @type {string} */ (potentialType)) :
-                        (0, jsdoccomment_1.parse)(/** @type {string} */ (potentialType), mode),
-                    tag,
-                };
-            }
-            catch {
-                return undefined;
-            }
-        };
-    };
-    const typeTags = utils.filterTags(({ tag, }) => {
-        return tag !== 'import' && utils.tagMightHaveTypePosition(tag) && (tag !== 'suppress' || settings.mode !== 'closure');
-    }).map(tagToParsedType('type'));
-    const namepathReferencingTags = utils.filterTags(({ tag, }) => {
-        return utils.isNamepathReferencingTag(tag);
-    }).map(tagToParsedType('name'));
-    const namepathOrUrlReferencingTags = utils.filterAllTags(({ tag, }) => {
-        return utils.isNamepathOrUrlReferencingTag(tag);
-    }).map(tagToParsedType('namepathOrURL'));
-    const tagsWithTypes = /** @type {TypeAndTagInfo[]} */ ([
-        ...typeTags,
-        ...namepathReferencingTags,
-        ...namepathOrUrlReferencingTags,
-        // Remove types which failed to parse
-    ].filter(Boolean));
-    for (const { parsedType, tag, } of tagsWithTypes) {
-        (0, jsdoccomment_1.traverse)(parsedType, (nde, parentNode) => {
-            /**
-             * @type {import('jsdoc-type-pratt-parser').NameResult & {
-             *   _parent?: import('jsdoc-type-pratt-parser').NonRootResult
-             * }}
-             */
-            // eslint-disable-next-line canonical/id-match -- Avoid clashes
-            (nde)._parent = parentNode;
-            const { type, value, } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
-            let val = value;
-            /** @type {import('jsdoc-type-pratt-parser').NonRootResult|undefined} */
-            let currNode = nde;
-            do {
-                currNode =
-                    /**
-                     * @type {import('jsdoc-type-pratt-parser').NameResult & {
-                     *   _parent?: import('jsdoc-type-pratt-parser').NonRootResult
-                     * }}
-                     */ (currNode)._parent;
-                if (
-                // Avoid appending for imports and globals since we don't want to
-                //  check their properties which may or may not exist
-                !imports.includes(val) && !globals.includes(val) &&
-                    !importTags.includes(val) &&
-                    !extraTypes.includes(val) &&
-                    !typedefDeclarations.includes(val) &&
-                    currNode && 'right' in currNode &&
-                    currNode.right?.type === 'JsdocTypeProperty') {
-                    val = val + '.' + currNode.right.value;
-                }
-            } while (currNode?.type === 'JsdocTypeNamePath');
-            if (type === 'JsdocTypeName') {
-                const structuredTypes = structuredTags[tag.tag]?.type;
-                if (!allDefinedTypes.has(val) &&
-                    (!Array.isArray(structuredTypes) || !structuredTypes.includes(val))) {
-                    if (!disableReporting) {
-                        report(`The type '${val}' is undefined.`, null, tag);
-                    }
-                }
-                else if (markVariablesAsUsed && !extraTypes.includes(val)) {
-                    if (sourceCode.markVariableAsUsed) {
-                        sourceCode.markVariableAsUsed(val);
-                        /* c8 ignore next 4 */
-                    }
-                    else {
-                        // @ts-expect-error ESLint 8
-                        context.markVariableAsUsed(val);
-                    }
-                }
-            }
-        });
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Checks that types in jsdoc comments are defined.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-undefined-types.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    definedTypes: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    disableReporting: {
-                        type: 'boolean',
-                    },
-                    markVariablesAsUsed: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/requireAsteriskPrefix.js

@@ -1,144 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, indent, jsdoc, utils, }) => {
-    const [defaultRequireValue = 'always', { tags: tagMap = {}, } = {},] = context.options;
-    const { source, } = jsdoc;
-    const always = defaultRequireValue === 'always';
-    const never = defaultRequireValue === 'never';
-    /** @type {string} */
-    let currentTag;
-    source.some(({ number, tokens, }) => {
-        const { delimiter, description, end, tag, } = tokens;
-        /**
-         * @returns {void}
-         */
-        const neverFix = () => {
-            tokens.delimiter = '';
-            tokens.postDelimiter = '';
-        };
-        /**
-         * @param {string} checkValue
-         * @returns {boolean}
-         */
-        const checkNever = (checkValue) => {
-            if (delimiter && delimiter !== '/**' && (never && !tagMap.always?.includes(checkValue) ||
-                tagMap.never?.includes(checkValue))) {
-                utils.reportJSDoc('Expected JSDoc line to have no prefix.', {
-                    column: 0,
-                    line: number,
-                }, neverFix);
-                return true;
-            }
-            return false;
-        };
-        /**
-         * @returns {void}
-         */
-        const alwaysFix = () => {
-            if (!tokens.start) {
-                tokens.start = indent + ' ';
-            }
-            tokens.delimiter = '*';
-            tokens.postDelimiter = tag || description ? ' ' : '';
-        };
-        /**
-         * @param {string} checkValue
-         * @returns {boolean}
-         */
-        const checkAlways = (checkValue) => {
-            if (!delimiter && (always && !tagMap.never?.includes(checkValue) ||
-                tagMap.always?.includes(checkValue))) {
-                utils.reportJSDoc('Expected JSDoc line to have the prefix.', {
-                    column: 0,
-                    line: number,
-                }, alwaysFix);
-                return true;
-            }
-            return false;
-        };
-        if (tag) {
-            // Remove at sign
-            currentTag = tag.slice(1);
-        }
-        if (
-        // If this is the end but has a tag, the delimiter will also be
-        //  populated and will be safely ignored later
-        end && !tag) {
-            return false;
-        }
-        if (!currentTag) {
-            if (tagMap.any?.includes('*description')) {
-                return false;
-            }
-            if (checkNever('*description')) {
-                return true;
-            }
-            if (checkAlways('*description')) {
-                return true;
-            }
-            return false;
-        }
-        if (tagMap.any?.includes(currentTag)) {
-            return false;
-        }
-        if (checkNever(currentTag)) {
-            return true;
-        }
-        if (checkAlways(currentTag)) {
-            return true;
-        }
-        return false;
-    });
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Requires that each JSDoc line starts with an `*`.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-asterisk-prefix.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                enum: [
-                    'always', 'never', 'any',
-                ],
-                type: 'string',
-            },
-            {
-                additionalProperties: false,
-                properties: {
-                    tags: {
-                        additionalProperties: false,
-                        properties: {
-                            always: {
-                                items: {
-                                    type: 'string',
-                                },
-                                type: 'array',
-                            },
-                            any: {
-                                items: {
-                                    type: 'string',
-                                },
-                                type: 'array',
-                            },
-                            never: {
-                                items: {
-                                    type: 'string',
-                                },
-                                type: 'array',
-                            },
-                        },
-                        type: 'object',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'layout',
-    },
-});