eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/checkTypes.js

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

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

package/dist/cjs/rules/checkValues.js

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