eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/checkLineAlignment.js

@@ -0,0 +1,297 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const alignTransform_js_1 = __importDefault(require("../alignTransform.js"));
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+const comment_parser_1 = require("comment-parser");
+const { flow: commentFlow, } = comment_parser_1.transforms;
+/**
+ * @typedef {{
+ *   postDelimiter: import('../iterateJsdoc.js').Integer,
+ *   postHyphen: import('../iterateJsdoc.js').Integer,
+ *   postName: import('../iterateJsdoc.js').Integer,
+ *   postTag: import('../iterateJsdoc.js').Integer,
+ *   postType: import('../iterateJsdoc.js').Integer,
+ * }} CustomSpacings
+ */
+/**
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {import('comment-parser').Spec & {
+ *   line: import('../iterateJsdoc.js').Integer
+ * }} tag
+ * @param {CustomSpacings} customSpacings
+ */
+const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
+    /*
+    start +
+    delimiter +
+    postDelimiter +
+    tag +
+    postTag +
+    type +
+    postType +
+    name +
+    postName +
+    description +
+    end +
+    lineEnd
+     */
+    /**
+     * @typedef {"tag"|"type"|"name"|"description"} ContentProp
+     */
+    /** @type {("postDelimiter"|"postTag"|"postType"|"postName")[]} */
+    let spacerProps;
+    /** @type {ContentProp[]} */
+    let contentProps;
+    const mightHaveNamepath = utils.tagMightHaveNamepath(tag.tag);
+    if (mightHaveNamepath) {
+        spacerProps = [
+            'postDelimiter', 'postTag', 'postType', 'postName',
+        ];
+        contentProps = [
+            'tag', 'type', 'name', 'description',
+        ];
+    }
+    else {
+        spacerProps = [
+            'postDelimiter', 'postTag', 'postType',
+        ];
+        contentProps = [
+            'tag', 'type', 'description',
+        ];
+    }
+    const { tokens, } = tag.source[0];
+    /**
+     * @param {import('../iterateJsdoc.js').Integer} idx
+     * @param {(notRet: boolean, contentProp: ContentProp) => void} [callbck]
+     */
+    const followedBySpace = (idx, callbck) => {
+        const nextIndex = idx + 1;
+        return spacerProps.slice(nextIndex).some((spacerProp, innerIdx) => {
+            const contentProp = contentProps[nextIndex + innerIdx];
+            const spacePropVal = tokens[spacerProp];
+            const ret = spacePropVal;
+            if (callbck) {
+                callbck(!ret, contentProp);
+            }
+            return ret && (callbck || !contentProp);
+        });
+    };
+    const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
+    const exactHyphenSpacing = new RegExp(`^\\s*-\\s{${postHyphenSpacing},${postHyphenSpacing}}(?!\\s)`, 'v');
+    const hasNoHyphen = !(/^\s*-(?!$)(?=\s)/v).test(tokens.description);
+    const hasExactHyphenSpacing = exactHyphenSpacing.test(tokens.description);
+    // If checking alignment on multiple lines, need to check other `source`
+    //   items
+    // Go through `post*` spacing properties and exit to indicate problem if
+    //   extra spacing detected
+    const ok = !spacerProps.some((spacerProp, idx) => {
+        const contentProp = contentProps[idx];
+        const contentPropVal = tokens[contentProp];
+        const spacerPropVal = tokens[spacerProp];
+        const spacing = customSpacings?.[spacerProp] || 1;
+        // There will be extra alignment if...
+        // 1. The spaces don't match the space it should have (1 or custom spacing) OR
+        return spacerPropVal.length !== spacing && spacerPropVal.length !== 0 ||
+            // 2. There is a (single) space, no immediate content, and yet another
+            //     space is found subsequently (not separated by intervening content)
+            spacerPropVal && !contentPropVal && followedBySpace(idx);
+    }) && (hasNoHyphen || hasExactHyphenSpacing);
+    if (ok) {
+        return;
+    }
+    const fix = () => {
+        for (const [idx, spacerProp,] of spacerProps.entries()) {
+            const contentProp = contentProps[idx];
+            const contentPropVal = tokens[contentProp];
+            if (contentPropVal) {
+                const spacing = customSpacings?.[spacerProp] || 1;
+                tokens[spacerProp] = ''.padStart(spacing, ' ');
+                followedBySpace(idx, (hasSpace, contentPrp) => {
+                    if (hasSpace) {
+                        tokens[contentPrp] = '';
+                    }
+                });
+            }
+            else {
+                tokens[spacerProp] = '';
+            }
+        }
+        if (!hasExactHyphenSpacing) {
+            const hyphenSpacing = /^\s*-\s+/v;
+            tokens.description = tokens.description.replace(hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '));
+        }
+        utils.setTag(tag, tokens);
+    };
+    utils.reportJSDoc('Expected JSDoc block lines to not be aligned.', tag, fix, true);
+};
+/**
+ * @param {object} cfg
+ * @param {CustomSpacings} cfg.customSpacings
+ * @param {string} cfg.indent
+ * @param {import('comment-parser').Block} cfg.jsdoc
+ * @param {import('eslint').Rule.Node & {
+ *   range: [number, number]
+ * }} cfg.jsdocNode
+ * @param {boolean} cfg.preserveMainDescriptionPostDelimiter
+ * @param {import('../iterateJsdoc.js').Report} cfg.report
+ * @param {string[]} cfg.tags
+ * @param {import('../iterateJsdoc.js').Utils} cfg.utils
+ * @param {string} cfg.wrapIndent
+ * @param {boolean} cfg.disableWrapIndent
+ * @returns {void}
+ */
+const checkAlignment = ({ customSpacings, disableWrapIndent, indent, jsdoc, jsdocNode, preserveMainDescriptionPostDelimiter, report, tags, utils, wrapIndent, }) => {
+    const transform = commentFlow((0, alignTransform_js_1.default)({
+        customSpacings,
+        disableWrapIndent,
+        indent,
+        preserveMainDescriptionPostDelimiter,
+        tags,
+        wrapIndent,
+    }));
+    const transformedJsdoc = transform(jsdoc);
+    const comment = '/*' +
+        /**
+         * @type {import('eslint').Rule.Node & {
+         *   range: [number, number], value: string
+         * }}
+         */ (jsdocNode).value + '*/';
+    const formatted = utils.stringify(transformedJsdoc)
+        .trimStart();
+    if (comment !== formatted) {
+        report('Expected JSDoc block lines to be aligned.', 
+        /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {
+            return fixer.replaceText(jsdocNode, formatted);
+        });
+    }
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, indent, jsdoc, jsdocNode, report, utils, }) => {
+    const { customSpacings, disableWrapIndent = false, preserveMainDescriptionPostDelimiter, tags: applicableTags = [
+        'param', 'arg', 'argument', 'property', 'prop', 'returns', 'return', 'template',
+    ], wrapIndent = '', } = context.options[1] || {};
+    if (context.options[0] === 'always') {
+        // Skip if it contains only a single line.
+        if (!(
+        /**
+         * @type {import('eslint').Rule.Node & {
+         *   range: [number, number], value: string
+         * }}
+         */
+        (jsdocNode).value.includes('\n'))) {
+            return;
+        }
+        checkAlignment({
+            customSpacings,
+            disableWrapIndent,
+            indent,
+            jsdoc,
+            jsdocNode,
+            preserveMainDescriptionPostDelimiter,
+            report,
+            tags: applicableTags,
+            utils,
+            wrapIndent,
+        });
+        return;
+    }
+    const foundTags = utils.getPresentTags(applicableTags);
+    if (context.options[0] !== 'any') {
+        for (const tag of foundTags) {
+            checkNotAlignedPerTag(utils, 
+            /**
+             * @type {import('comment-parser').Spec & {
+             *   line: import('../iterateJsdoc.js').Integer
+             * }}
+             */
+            (tag), customSpacings);
+        }
+    }
+    for (const tag of foundTags) {
+        if (tag.source.length > 1) {
+            let idx = 0;
+            for (const { tokens,
+            // Avoid the tag line
+             } of tag.source.slice(1)) {
+                idx++;
+                if (!tokens.description ||
+                    // Avoid first lines after multiline type
+                    tokens.type ||
+                    tokens.name) {
+                    continue;
+                }
+                // Don't include a single separating space/tab
+                if (!disableWrapIndent && tokens.postDelimiter.slice(1) !== wrapIndent) {
+                    utils.reportJSDoc('Expected wrap indent', {
+                        line: tag.source[0].number + idx,
+                    }, () => {
+                        tokens.postDelimiter = tokens.postDelimiter.charAt(0) + wrapIndent;
+                    });
+                    return;
+                }
+            }
+        }
+    }
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Reports invalid alignment of JSDoc block lines.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-line-alignment.md#repos-sticky-header',
+        },
+        fixable: 'whitespace',
+        schema: [
+            {
+                enum: [
+                    'always', 'never', 'any',
+                ],
+                type: 'string',
+            },
+            {
+                additionalProperties: false,
+                properties: {
+                    customSpacings: {
+                        additionalProperties: false,
+                        properties: {
+                            postDelimiter: {
+                                type: 'integer',
+                            },
+                            postHyphen: {
+                                type: 'integer',
+                            },
+                            postName: {
+                                type: 'integer',
+                            },
+                            postTag: {
+                                type: 'integer',
+                            },
+                            postType: {
+                                type: 'integer',
+                            },
+                        },
+                    },
+                    disableWrapIndent: {
+                        type: 'boolean',
+                    },
+                    preserveMainDescriptionPostDelimiter: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    tags: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    wrapIndent: {
+                        type: 'string',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'layout',
+    },
+});

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

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

package/dist/cjs/rules/checkParamNames.js

@@ -0,0 +1,320 @@
+"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"));
+/**
+ * @param {string} targetTagName
+ * @param {boolean} allowExtraTrailingParamDocs
+ * @param {boolean} checkDestructured
+ * @param {boolean} checkRestProperty
+ * @param {RegExp} checkTypesRegex
+ * @param {boolean} disableExtraPropertyReporting
+ * @param {boolean} disableMissingParamChecks
+ * @param {boolean} enableFixer
+ * @param {import('../jsdocUtils.js').ParamNameInfo[]} functionParameterNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {import('../iterateJsdoc.js').Utils} utils
+ * @param {import('../iterateJsdoc.js').Report} report
+ * @returns {boolean}
+ */
+const validateParameterNames = (targetTagName, allowExtraTrailingParamDocs, checkDestructured, checkRestProperty, checkTypesRegex, disableExtraPropertyReporting, disableMissingParamChecks, enableFixer, functionParameterNames, jsdoc, utils, report) => {
+    const paramTags = Object.entries(jsdoc.tags).filter(([, tag,]) => {
+        return tag.tag === targetTagName;
+    });
+    const paramTagsNonNested = paramTags.filter(([, tag,]) => {
+        return !tag.name.includes('.');
+    });
+    let dotted = 0;
+    let thisOffset = 0;
+    // eslint-disable-next-line complexity
+    return paramTags.some(([, tag,], index) => {
+        /** @type {import('../iterateJsdoc.js').Integer} */
+        let tagsIndex;
+        const dupeTagInfo = paramTags.find(([tgsIndex, tg,], idx) => {
+            tagsIndex = Number(tgsIndex);
+            return tg.name === tag.name && idx !== index;
+        });
+        if (dupeTagInfo) {
+            utils.reportJSDoc(`Duplicate @${targetTagName} "${tag.name}"`, dupeTagInfo[1], enableFixer ? () => {
+                utils.removeTag(tagsIndex);
+            } : null);
+            return true;
+        }
+        if (tag.name.includes('.')) {
+            dotted++;
+            return false;
+        }
+        let functionParameterName = functionParameterNames[index - dotted + thisOffset];
+        if (functionParameterName === 'this' && tag.name.trim() !== 'this') {
+            ++thisOffset;
+            functionParameterName = functionParameterNames[index - dotted + thisOffset];
+        }
+        if (!functionParameterName) {
+            if (allowExtraTrailingParamDocs) {
+                return false;
+            }
+            report(`@${targetTagName} "${tag.name}" does not match an existing function parameter.`, null, tag);
+            return true;
+        }
+        if (typeof functionParameterName === 'object' &&
+            'name' in functionParameterName &&
+            Array.isArray(functionParameterName.name)) {
+            const actualName = tag.name.trim();
+            const expectedName = functionParameterName.name[index];
+            if (actualName === expectedName) {
+                thisOffset--;
+                return false;
+            }
+            report(`Expected @${targetTagName} name to be "${expectedName}". Got "${actualName}".`, null, tag);
+            return true;
+        }
+        if (Array.isArray(functionParameterName)) {
+            if (!checkDestructured) {
+                return false;
+            }
+            if (tag.type && tag.type.search(checkTypesRegex) === -1) {
+                return false;
+            }
+            const [parameterName, { annotationParamName, hasPropertyRest, names: properties, rests, },] = 
+            /**
+             * @type {[string | undefined, import('../jsdocUtils.js').FlattendRootInfo & {
+             *   annotationParamName?: string | undefined;
+              }]} */ (functionParameterName);
+            if (annotationParamName !== undefined) {
+                const name = tag.name.trim();
+                if (name !== annotationParamName) {
+                    report(`@${targetTagName} "${name}" does not match parameter name "${annotationParamName}"`, null, tag);
+                }
+            }
+            const tagName = parameterName === undefined ? tag.name.trim() : parameterName;
+            const expectedNames = properties.map((name) => {
+                return `${tagName}.${name}`;
+            });
+            const actualNames = paramTags.map(([, paramTag,]) => {
+                return paramTag.name.trim();
+            });
+            const actualTypes = paramTags.map(([, paramTag,]) => {
+                return paramTag.type;
+            });
+            const missingProperties = [];
+            /** @type {string[]} */
+            const notCheckingNames = [];
+            for (const [idx, name,] of expectedNames.entries()) {
+                if (notCheckingNames.some((notCheckingName) => {
+                    return name.startsWith(notCheckingName);
+                })) {
+                    continue;
+                }
+                const actualNameIdx = actualNames.findIndex((actualName) => {
+                    return utils.comparePaths(name)(actualName);
+                });
+                if (actualNameIdx === -1) {
+                    if (!checkRestProperty && rests[idx]) {
+                        continue;
+                    }
+                    const missingIndex = actualNames.findIndex((actualName) => {
+                        return utils.pathDoesNotBeginWith(name, actualName);
+                    });
+                    const line = tag.source[0].number - 1 + (missingIndex > -1 ? missingIndex : actualNames.length);
+                    missingProperties.push({
+                        name,
+                        tagPlacement: {
+                            line: line === 0 ? 1 : line,
+                        },
+                    });
+                }
+                else if (actualTypes[actualNameIdx].search(checkTypesRegex) === -1 && actualTypes[actualNameIdx] !== '') {
+                    notCheckingNames.push(name);
+                }
+            }
+            const hasMissing = missingProperties.length;
+            if (hasMissing) {
+                for (const { name: missingProperty, tagPlacement, } of missingProperties) {
+                    report(`Missing @${targetTagName} "${missingProperty}"`, null, tagPlacement);
+                }
+            }
+            if (!hasPropertyRest || checkRestProperty) {
+                /** @type {[string, import('comment-parser').Spec][]} */
+                const extraProperties = [];
+                for (const [idx, name,] of actualNames.entries()) {
+                    const match = name.startsWith(tag.name.trim() + '.');
+                    if (match && !expectedNames.some(utils.comparePaths(name)) && !utils.comparePaths(name)(tag.name) &&
+                        (!disableExtraPropertyReporting || properties.some((prop) => {
+                            return prop.split('.').length >= name.split('.').length - 1;
+                        }))) {
+                        extraProperties.push([
+                            name, paramTags[idx][1],
+                        ]);
+                    }
+                }
+                if (extraProperties.length) {
+                    for (const [extraProperty, tg,] of extraProperties) {
+                        report(`@${targetTagName} "${extraProperty}" does not exist on ${tag.name}`, null, tg);
+                    }
+                    return true;
+                }
+            }
+            return hasMissing;
+        }
+        let funcParamName;
+        if (typeof functionParameterName === 'object') {
+            const { name, } = functionParameterName;
+            funcParamName = name;
+        }
+        else {
+            funcParamName = functionParameterName;
+        }
+        if (funcParamName !== tag.name.trim()) {
+            // Todo: Improve for array or object child items
+            const actualNames = paramTagsNonNested.map(([, { name, },]) => {
+                return name.trim();
+            });
+            const expectedNames = functionParameterNames.map((item, idx) => {
+                if ( /**
+                     * @type {[string|undefined, (import('../jsdocUtils.js').FlattendRootInfo & {
+                     *   annotationParamName?: string,
+                      })]} */(item)?.[1]?.names) {
+                    return actualNames[idx];
+                }
+                return item;
+            }).filter((item) => {
+                return item !== 'this';
+            });
+            // When disableMissingParamChecks is true tag names can be omitted.
+            // Report when the tag names do not match the expected names or they are used out of order.
+            if (disableMissingParamChecks) {
+                const usedExpectedNames = expectedNames.map((a) => {
+                    return a?.toString();
+                }).filter((expectedName) => {
+                    return expectedName && actualNames.includes(expectedName);
+                });
+                const usedInOrder = actualNames.every((actualName, idx) => {
+                    return actualName === usedExpectedNames[idx];
+                });
+                if (usedInOrder) {
+                    return false;
+                }
+            }
+            report(`Expected @${targetTagName} names to be "${expectedNames.map((expectedName) => {
+                return typeof expectedName === 'object' &&
+                    'name' in expectedName &&
+                    expectedName.restElement ?
+                    '...' + expectedName.name :
+                    expectedName;
+            }).join(', ')}". Got "${actualNames.join(', ')}".`, null, tag);
+            return true;
+        }
+        return false;
+    });
+};
+/**
+ * @param {string} targetTagName
+ * @param {boolean} _allowExtraTrailingParamDocs
+ * @param {{
+ *   name: string,
+ *   idx: import('../iterateJsdoc.js').Integer
+ * }[]} jsdocParameterNames
+ * @param {import('comment-parser').Block} jsdoc
+ * @param {Function} report
+ * @returns {boolean}
+ */
+const validateParameterNamesDeep = (targetTagName, _allowExtraTrailingParamDocs, jsdocParameterNames, jsdoc, report) => {
+    /** @type {string} */
+    let lastRealParameter;
+    return jsdocParameterNames.some(({ idx, name: jsdocParameterName, }) => {
+        const isPropertyPath = jsdocParameterName.includes('.');
+        if (isPropertyPath) {
+            if (!lastRealParameter) {
+                report(`@${targetTagName} path declaration ("${jsdocParameterName}") appears before any real parameter.`, null, jsdoc.tags[idx]);
+                return true;
+            }
+            let pathRootNodeName = jsdocParameterName.slice(0, jsdocParameterName.indexOf('.'));
+            if (pathRootNodeName.endsWith('[]')) {
+                pathRootNodeName = pathRootNodeName.slice(0, -2);
+            }
+            if (pathRootNodeName !== lastRealParameter) {
+                report(`@${targetTagName} path declaration ("${jsdocParameterName}") root node name ("${pathRootNodeName}") ` +
+                    `does not match previous real parameter name ("${lastRealParameter}").`, null, jsdoc.tags[idx]);
+                return true;
+            }
+        }
+        else {
+            lastRealParameter = jsdocParameterName;
+        }
+        return false;
+    });
+};
+const allowedNodes = [
+    'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
+    // Add this to above defaults
+    'TSMethodSignature',
+];
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, node, report, utils, }) => {
+    const { allowExtraTrailingParamDocs, checkDestructured = true, checkRestProperty = false, checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/', disableExtraPropertyReporting = false, disableMissingParamChecks = false, enableFixer = false, useDefaultObjectProperties = false, } = context.options[0] || {};
+    // Although we might just remove global settings contexts from applying to
+    //   this rule (as they can cause problems with `getFunctionParameterNames`
+    //   checks if they are not functions but say variables), the user may
+    //   instead wish to narrow contexts in those settings, so this check
+    //   is still useful
+    if (!allowedNodes.includes(/** @type {import('estree').Node} */ (node).type)) {
+        return;
+    }
+    const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
+    const jsdocParameterNamesDeep = utils.getJsdocTagsDeep('param');
+    if (!jsdocParameterNamesDeep || !jsdocParameterNamesDeep.length) {
+        return;
+    }
+    const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties);
+    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+        tagName: 'param',
+    }));
+    const isError = validateParameterNames(targetTagName, allowExtraTrailingParamDocs, checkDestructured, checkRestProperty, checkTypesRegex, disableExtraPropertyReporting, disableMissingParamChecks, enableFixer, functionParameterNames, jsdoc, utils, report);
+    if (isError || !checkDestructured) {
+        return;
+    }
+    validateParameterNamesDeep(targetTagName, allowExtraTrailingParamDocs, jsdocParameterNamesDeep, jsdoc, report);
+}, {
+    contextDefaults: allowedNodes,
+    meta: {
+        docs: {
+            description: 'Ensures that parameter names in JSDoc match those in the function declaration.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-param-names.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    allowExtraTrailingParamDocs: {
+                        type: 'boolean',
+                    },
+                    checkDestructured: {
+                        type: 'boolean',
+                    },
+                    checkRestProperty: {
+                        type: 'boolean',
+                    },
+                    checkTypesPattern: {
+                        type: 'string',
+                    },
+                    disableExtraPropertyReporting: {
+                        type: 'boolean',
+                    },
+                    disableMissingParamChecks: {
+                        type: 'boolean',
+                    },
+                    enableFixer: {
+                        type: 'boolean',
+                    },
+                    useDefaultObjectProperties: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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