eslint-plugin-jsdoc 56.0.0 → 56.0.2

package/dist/cjs/rules/checkLineAlignment.js

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

@@ -1,320 +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"));
-/**
- * @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',
-    },
-});