eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/checkTypes.js

@@ -1,421 +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 strictNativeTypes = [
-    'undefined',
-    'null',
-    'boolean',
-    'number',
-    'bigint',
-    'string',
-    'symbol',
-    'object',
-    'Array',
-    'Function',
-    'Date',
-    'RegExp',
-];
-/**
- * Adjusts the parent type node `meta` for generic matches (or type node
- * `type` for `JsdocTypeAny`) and sets the type node `value`.
- * @param {string} type The actual type
- * @param {string} preferred The preferred type
- * @param {boolean} isGenericMatch
- * @param {string} typeNodeName
- * @param {import('jsdoc-type-pratt-parser').NonRootResult} node
- * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
- * @returns {void}
- */
-const adjustNames = (type, preferred, isGenericMatch, typeNodeName, node, parentNode) => {
-    let ret = preferred;
-    if (isGenericMatch) {
-        const parentMeta = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (parentNode).meta;
-        if (preferred === '[]') {
-            parentMeta.brackets = 'square';
-            parentMeta.dot = false;
-            ret = 'Array';
-        }
-        else {
-            const dotBracketEnd = preferred.match(/\.(?:<>)?$/v);
-            if (dotBracketEnd) {
-                parentMeta.brackets = 'angle';
-                parentMeta.dot = true;
-                ret = preferred.slice(0, -dotBracketEnd[0].length);
-            }
-            else {
-                const bracketEnd = preferred.endsWith('<>');
-                if (bracketEnd) {
-                    parentMeta.brackets = 'angle';
-                    parentMeta.dot = false;
-                    ret = preferred.slice(0, -2);
-                }
-                else if (parentMeta?.brackets === 'square' &&
-                    (typeNodeName === '[]' || typeNodeName === 'Array')) {
-                    parentMeta.brackets = 'angle';
-                    parentMeta.dot = false;
-                }
-            }
-        }
-    }
-    else if (type === 'JsdocTypeAny') {
-        node.type = 'JsdocTypeName';
-    }
-    /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (node).value = ret.replace(/(?:\.|<>|\.<>|\[\])$/v, '');
-    // For bare pseudo-types like `<>`
-    if (!ret) {
-        /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (node).value = typeNodeName;
-    }
-};
-/**
- * @param {boolean} [upperCase]
- * @returns {string}
- */
-const getMessage = (upperCase) => {
-    return 'Use object shorthand or index signatures instead of ' +
-        '`' + (upperCase ? 'O' : 'o') + 'bject`, e.g., `{[key: string]: string}`';
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdocNode, report, settings, sourceCode, utils, }) => {
-    const jsdocTagsWithPossibleType = utils.filterTags((tag) => {
-        return Boolean(utils.tagMightHaveTypePosition(tag.tag));
-    });
-    const 
-    /**
-     * @type {{
-     *   preferredTypes: import('../iterateJsdoc.js').PreferredTypes,
-     *   structuredTags: import('../iterateJsdoc.js').StructuredTags,
-     *   mode: import('../jsdocUtils.js').ParserMode
-     * }}
-     */
-    { mode, preferredTypes: preferredTypesOriginal, structuredTags, } = settings;
-    const injectObjectPreferredTypes = !('Object' in preferredTypesOriginal ||
-        'object' in preferredTypesOriginal ||
-        'object.<>' in preferredTypesOriginal ||
-        'Object.<>' in preferredTypesOriginal ||
-        'object<>' in preferredTypesOriginal);
-    /**
-     * @type {{
-     *   message: string,
-     *   replacement: false
-     * }}
-     */
-    const info = {
-        message: getMessage(),
-        replacement: false,
-    };
-    /**
-     * @type {{
-     *   message: string,
-     *   replacement: false
-     * }}
-     */
-    const infoUC = {
-        message: getMessage(true),
-        replacement: false,
-    };
-    /** @type {import('../iterateJsdoc.js').PreferredTypes} */
-    const typeToInject = mode === 'typescript' ?
-        {
-            Object: 'object',
-            'object.<>': info,
-            'Object.<>': infoUC,
-            'object<>': info,
-            'Object<>': infoUC,
-        } :
-        {
-            Object: 'object',
-            'object.<>': 'Object<>',
-            'Object.<>': 'Object<>',
-            'object<>': 'Object<>',
-        };
-    /** @type {import('../iterateJsdoc.js').PreferredTypes} */
-    const preferredTypes = {
-        ...injectObjectPreferredTypes ?
-            typeToInject :
-            {},
-        ...preferredTypesOriginal,
-    };
-    const 
-    /**
-     * @type {{
-     *   noDefaults: boolean,
-     *   unifyParentAndChildTypeChecks: boolean,
-     *   exemptTagContexts: ({
-     *     tag: string,
-     *     types: true|string[]
-     *   })[]
-     * }}
-     */ { exemptTagContexts = [], noDefaults, unifyParentAndChildTypeChecks, } = context.options[0] || {};
-    /**
-     * Gets information about the preferred type: whether there is a matching
-     * preferred type, what the type is, and whether it is a match to a generic.
-     * @param {string} _type Not currently in use
-     * @param {string} typeNodeName
-     * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
-     * @param {string|undefined} property
-     * @returns {[hasMatchingPreferredType: boolean, typeName: string, isGenericMatch: boolean]}
-     */
-    const getPreferredTypeInfo = (_type, typeNodeName, parentNode, property) => {
-        let hasMatchingPreferredType = false;
-        let isGenericMatch = false;
-        let typeName = typeNodeName;
-        const isNameOfGeneric = parentNode !== undefined && parentNode.type === 'JsdocTypeGeneric' && property === 'left';
-        if (unifyParentAndChildTypeChecks || isNameOfGeneric) {
-            const brackets = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (parentNode)?.meta?.brackets;
-            const dot = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (parentNode)?.meta?.dot;
-            if (brackets === 'angle') {
-                const checkPostFixes = dot ? [
-                    '.', '.<>',
-                ] : [
-                    '<>',
-                ];
-                isGenericMatch = checkPostFixes.some((checkPostFix) => {
-                    if (preferredTypes?.[typeNodeName + checkPostFix] !== undefined) {
-                        typeName += checkPostFix;
-                        return true;
-                    }
-                    return false;
-                });
-            }
-            if (!isGenericMatch && property &&
-                /** @type {import('jsdoc-type-pratt-parser').NonRootResult} */ (parentNode).type === 'JsdocTypeGeneric') {
-                const checkPostFixes = dot ? [
-                    '.', '.<>',
-                ] : [
-                    brackets === 'angle' ? '<>' : '[]',
-                ];
-                isGenericMatch = checkPostFixes.some((checkPostFix) => {
-                    if (preferredTypes?.[checkPostFix] !== undefined) {
-                        typeName = checkPostFix;
-                        return true;
-                    }
-                    return false;
-                });
-            }
-        }
-        const directNameMatch = preferredTypes?.[typeNodeName] !== undefined &&
-            !Object.values(preferredTypes).includes(typeNodeName);
-        const unifiedSyntaxParentMatch = property && directNameMatch && unifyParentAndChildTypeChecks;
-        isGenericMatch = isGenericMatch || Boolean(unifiedSyntaxParentMatch);
-        hasMatchingPreferredType = isGenericMatch ||
-            directNameMatch && !property;
-        return [
-            hasMatchingPreferredType, typeName, isGenericMatch,
-        ];
-    };
-    /**
-     * Iterates strict types to see if any should be added to `invalidTypes` (and
-     * the the relevant strict type returned as the new preferred type).
-     * @param {string} typeNodeName
-     * @param {string|undefined} preferred
-     * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
-     * @param {(string|false|undefined)[][]} invalidTypes
-     * @returns {string|undefined} The `preferred` type string, optionally changed
-     */
-    const checkNativeTypes = (typeNodeName, preferred, parentNode, invalidTypes) => {
-        let changedPreferred = preferred;
-        for (const strictNativeType of strictNativeTypes) {
-            if (strictNativeType === 'object' &&
-                (
-                // This is not set to remap with exact type match (e.g.,
-                //   `object: 'Object'`), so can ignore (including if circular)
-                !preferredTypes?.[typeNodeName] ||
-                    // Although present on `preferredTypes` for remapping, this is a
-                    //   parent object without a parent match (and not
-                    //   `unifyParentAndChildTypeChecks`) and we don't want
-                    //   `object<>` given TypeScript issue https://github.com/microsoft/TypeScript/issues/20555
-                    /**
-                     * @type {import('jsdoc-type-pratt-parser').GenericResult}
-                     */
-                    (parentNode)?.elements?.length && (
-                    /**
-                     * @type {import('jsdoc-type-pratt-parser').GenericResult}
-                     */
-                    (parentNode)?.left?.type === 'JsdocTypeName' &&
-                        /**
-                         * @type {import('jsdoc-type-pratt-parser').GenericResult}
-                         */
-                        (parentNode)?.left?.value === 'Object'))) {
-                continue;
-            }
-            if (strictNativeType !== typeNodeName &&
-                strictNativeType.toLowerCase() === typeNodeName.toLowerCase() &&
-                // Don't report if user has own map for a strict native type
-                (!preferredTypes || preferredTypes?.[strictNativeType] === undefined)) {
-                changedPreferred = strictNativeType;
-                invalidTypes.push([
-                    typeNodeName, changedPreferred,
-                ]);
-                break;
-            }
-        }
-        return changedPreferred;
-    };
-    /**
-     * Collect invalid type info.
-     * @param {string} type
-     * @param {string} value
-     * @param {string} tagName
-     * @param {string} nameInTag
-     * @param {number} idx
-     * @param {string|undefined} property
-     * @param {import('jsdoc-type-pratt-parser').NonRootResult} node
-     * @param {import('jsdoc-type-pratt-parser').NonRootResult|undefined} parentNode
-     * @param {(string|false|undefined)[][]} invalidTypes
-     * @returns {void}
-     */
-    const getInvalidTypes = (type, value, tagName, nameInTag, idx, property, node, parentNode, invalidTypes) => {
-        let typeNodeName = type === 'JsdocTypeAny' ? '*' : value;
-        const [hasMatchingPreferredType, typeName, isGenericMatch,] = getPreferredTypeInfo(type, typeNodeName, parentNode, property);
-        let preferred;
-        let types;
-        if (hasMatchingPreferredType) {
-            const preferredSetting = preferredTypes[typeName];
-            typeNodeName = typeName === '[]' ? typeName : typeNodeName;
-            if (!preferredSetting) {
-                invalidTypes.push([
-                    typeNodeName,
-                ]);
-            }
-            else if (typeof preferredSetting === 'string') {
-                preferred = preferredSetting;
-                invalidTypes.push([
-                    typeNodeName, preferred,
-                ]);
-            }
-            else if (preferredSetting && typeof preferredSetting === 'object') {
-                const nextItem = preferredSetting.skipRootChecking && jsdocTagsWithPossibleType[idx + 1];
-                if (!nextItem || !nextItem.name.startsWith(`${nameInTag}.`)) {
-                    preferred = preferredSetting.replacement;
-                    invalidTypes.push([
-                        typeNodeName,
-                        preferred,
-                        preferredSetting.message,
-                    ]);
-                }
-            }
-            else {
-                utils.reportSettings('Invalid `settings.jsdoc.preferredTypes`. Values must be falsy, a string, or an object.');
-                return;
-            }
-        }
-        else if (Object.entries(structuredTags).some(([tag, { type: typs, },]) => {
-            types = typs;
-            return tag === tagName &&
-                Array.isArray(types) &&
-                !types.includes(typeNodeName);
-        })) {
-            invalidTypes.push([
-                typeNodeName, types,
-            ]);
-        }
-        else if (!noDefaults && type === 'JsdocTypeName') {
-            preferred = checkNativeTypes(typeNodeName, preferred, parentNode, invalidTypes);
-        }
-        // For fixer
-        if (preferred) {
-            adjustNames(type, preferred, isGenericMatch, typeNodeName, node, parentNode);
-        }
-    };
-    for (const [idx, jsdocTag,] of jsdocTagsWithPossibleType.entries()) {
-        /** @type {(string|false|undefined)[][]} */
-        const invalidTypes = [];
-        let typeAst;
-        try {
-            typeAst = mode === 'permissive' ? (0, jsdoccomment_1.tryParse)(jsdocTag.type) : (0, jsdoccomment_1.parse)(jsdocTag.type, mode);
-        }
-        catch {
-            continue;
-        }
-        const { name: nameInTag, tag: tagName, } = jsdocTag;
-        (0, jsdoccomment_1.traverse)(typeAst, (node, parentNode, property) => {
-            const { type, value, } = 
-            /**
-             * @type {import('jsdoc-type-pratt-parser').NameResult}
-             */ (node);
-            if (![
-                'JsdocTypeAny', 'JsdocTypeName',
-            ].includes(type)) {
-                return;
-            }
-            getInvalidTypes(type, value, tagName, nameInTag, idx, property, node, parentNode, invalidTypes);
-        });
-        if (invalidTypes.length) {
-            const fixedType = (0, jsdoccomment_1.stringify)(typeAst);
-            /**
-             * @type {import('eslint').Rule.ReportFixer}
-             */
-            const fix = (fixer) => {
-                return fixer.replaceText(jsdocNode, sourceCode.getText(jsdocNode).replace(`{${jsdocTag.type}}`, `{${fixedType}}`));
-            };
-            for (const [badType, preferredType = '', msg,] of invalidTypes) {
-                const tagValue = jsdocTag.name ? ` "${jsdocTag.name}"` : '';
-                if (exemptTagContexts.some(({ tag, types, }) => {
-                    return tag === tagName &&
-                        (types === true || types.includes(jsdocTag.type));
-                })) {
-                    continue;
-                }
-                report(msg ||
-                    `Invalid JSDoc @${tagName}${tagValue} type "${badType}"` +
-                        (preferredType ? '; ' : '.') +
-                        (preferredType ? `prefer: ${JSON.stringify(preferredType)}.` : ''), preferredType ? fix : null, jsdocTag, msg ? {
-                    tagName,
-                    tagValue,
-                } : undefined);
-            }
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Reports invalid types.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-types.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    exemptTagContexts: {
-                        items: {
-                            additionalProperties: false,
-                            properties: {
-                                tag: {
-                                    type: 'string',
-                                },
-                                types: {
-                                    oneOf: [
-                                        {
-                                            type: 'boolean',
-                                        },
-                                        {
-                                            items: {
-                                                type: 'string',
-                                            },
-                                            type: 'array',
-                                        },
-                                    ],
-                                },
-                            },
-                            type: 'object',
-                        },
-                        type: 'array',
-                    },
-                    noDefaults: {
-                        type: 'boolean',
-                    },
-                    unifyParentAndChildTypeChecks: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/checkValues.js

@@ -1,163 +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 parse_imports_exports_1 = require("parse-imports-exports");
-const semver_1 = __importDefault(require("semver"));
-const spdx_expression_parse_1 = __importDefault(require("spdx-expression-parse"));
-const allowedKinds = new Set([
-    'class',
-    'constant',
-    'event',
-    'external',
-    'file',
-    'function',
-    'member',
-    'mixin',
-    'module',
-    'namespace',
-    'typedef',
-]);
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, report, settings, utils, }) => {
-    const options = context.options[0] || {};
-    const { allowedAuthors = null, allowedLicenses = null, licensePattern = '/([^\n\r]*)/gv', numericOnlyVariation = false, } = options;
-    utils.forEachPreferredTag('version', (jsdocParameter, targetTagName) => {
-        const version = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).trim();
-        if (!version) {
-            report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-        }
-        else if (!semver_1.default.valid(version)) {
-            report(`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`, null, jsdocParameter);
-        }
-    });
-    utils.forEachPreferredTag('kind', (jsdocParameter, targetTagName) => {
-        const kind = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).trim();
-        if (!kind) {
-            report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-        }
-        else if (!allowedKinds.has(kind)) {
-            report(`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; ` +
-                `must be one of: ${[
-                    ...allowedKinds,
-                ].join(', ')}.`, null, jsdocParameter);
-        }
-    });
-    if (numericOnlyVariation) {
-        utils.forEachPreferredTag('variation', (jsdocParameter, targetTagName) => {
-            const variation = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).trim();
-            if (!variation) {
-                report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-            }
-            else if (!Number.isInteger(Number(variation)) ||
-                Number(variation) <= 0) {
-                report(`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`, null, jsdocParameter);
-            }
-        });
-    }
-    utils.forEachPreferredTag('since', (jsdocParameter, targetTagName) => {
-        const version = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).trim();
-        if (!version) {
-            report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-        }
-        else if (!semver_1.default.valid(version)) {
-            report(`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}".`, null, jsdocParameter);
-        }
-    });
-    utils.forEachPreferredTag('license', (jsdocParameter, targetTagName) => {
-        const licenseRegex = utils.getRegexFromString(licensePattern, 'g');
-        const matches = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).matchAll(licenseRegex);
-        let positiveMatch = false;
-        for (const match of matches) {
-            const license = match[1] || match[0];
-            if (license) {
-                positiveMatch = true;
-            }
-            if (!license.trim()) {
-                // Avoid reporting again as empty match
-                if (positiveMatch) {
-                    return;
-                }
-                report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-            }
-            else if (allowedLicenses) {
-                if (allowedLicenses !== true && !allowedLicenses.includes(license)) {
-                    report(`Invalid JSDoc @${targetTagName}: "${license}"; expected one of ${allowedLicenses.join(', ')}.`, null, jsdocParameter);
-                }
-            }
-            else {
-                try {
-                    (0, spdx_expression_parse_1.default)(license);
-                }
-                catch {
-                    report(`Invalid JSDoc @${targetTagName}: "${license}"; expected SPDX expression: https://spdx.org/licenses/.`, null, jsdocParameter);
-                }
-            }
-        }
-    });
-    if (settings.mode === 'typescript') {
-        utils.forEachPreferredTag('import', (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());
-            if (importsExports.errors) {
-                report('Bad @import tag', null, tag);
-            }
-        });
-    }
-    utils.forEachPreferredTag('author', (jsdocParameter, targetTagName) => {
-        const author = /** @type {string} */ (utils.getTagDescription(jsdocParameter)).trim();
-        if (!author) {
-            report(`Missing JSDoc @${targetTagName} value.`, null, jsdocParameter);
-        }
-        else if (allowedAuthors && !allowedAuthors.includes(author)) {
-            report(`Invalid JSDoc @${targetTagName}: "${utils.getTagDescription(jsdocParameter)}"; expected one of ${allowedAuthors.join(', ')}.`, null, jsdocParameter);
-        }
-    });
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'This rule checks the values for a handful of tags: `@version`, `@since`, `@license` and `@author`.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-values.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    allowedAuthors: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    allowedLicenses: {
-                        anyOf: [
-                            {
-                                items: {
-                                    type: 'string',
-                                },
-                                type: 'array',
-                            },
-                            {
-                                type: 'boolean',
-                            },
-                        ],
-                    },
-                    licensePattern: {
-                        type: 'string',
-                    },
-                    numericOnlyVariation: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});