eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/requireParam.js

@@ -0,0 +1,480 @@
+"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"));
+/**
+ * @typedef {[string, boolean, () => RootNamerReturn]} RootNamerReturn
+ */
+/**
+ * @param {string[]} desiredRoots
+ * @param {number} currentIndex
+ * @returns {RootNamerReturn}
+ */
+const rootNamer = (desiredRoots, currentIndex) => {
+    /** @type {string} */
+    let name;
+    let idx = currentIndex;
+    const incremented = desiredRoots.length <= 1;
+    if (incremented) {
+        const base = desiredRoots[0];
+        const suffix = idx++;
+        name = `${base}${suffix}`;
+    }
+    else {
+        name = /** @type {string} */ (desiredRoots.shift());
+    }
+    return [
+        name,
+        incremented,
+        () => {
+            return rootNamer(desiredRoots, idx);
+        },
+    ];
+};
+/* eslint-disable complexity -- Temporary */
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
+    /* eslint-enable complexity -- Temporary */
+    if (utils.avoidDocs()) {
+        return;
+    }
+    // Param type is specified by type in @type
+    if (utils.hasTag('type')) {
+        return;
+    }
+    const { autoIncrementBase = 0, checkDestructured = true, checkDestructuredRoots = true, checkRestProperty = false, checkTypesPattern = '/^(?:[oO]bject|[aA]rray|PlainObject|Generic(?:Object|Array))$/', enableFixer = true, enableRestElementFixer = true, enableRootFixer = true, ignoreWhenAllParamsMissing = false, unnamedRootBase = [
+        'root',
+    ], useDefaultObjectProperties = false, } = context.options[0] || {};
+    const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
+        tagName: 'param',
+    }));
+    if (!preferredTagName) {
+        return;
+    }
+    const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties);
+    if (!functionParameterNames.length) {
+        return;
+    }
+    const jsdocParameterNames = 
+    /**
+     * @type {{
+     *   idx: import('../iterateJsdoc.js').Integer;
+     *   name: string;
+     *   type: string;
+     * }[]}
+     */ (utils.getJsdocTagsDeep(preferredTagName));
+    if (ignoreWhenAllParamsMissing && !jsdocParameterNames.length) {
+        return;
+    }
+    const shallowJsdocParameterNames = jsdocParameterNames.filter((tag) => {
+        return !tag.name.includes('.');
+    }).map((tag, idx) => {
+        return {
+            ...tag,
+            idx,
+        };
+    });
+    const checkTypesRegex = utils.getRegexFromString(checkTypesPattern);
+    /**
+     * @type {{
+     *   functionParameterIdx: import('../iterateJsdoc.js').Integer,
+     *   functionParameterName: string,
+     *   inc: boolean|undefined,
+     *   remove?: true,
+     *   type?: string|undefined
+     * }[]}
+     */
+    const missingTags = [];
+    const flattenedRoots = utils.flattenRoots(functionParameterNames).names;
+    /**
+     * @type {{
+     *   [key: string]: import('../iterateJsdoc.js').Integer
+     * }}
+     */
+    const paramIndex = {};
+    /**
+     * @param {string} cur
+     * @returns {boolean}
+     */
+    const hasParamIndex = (cur) => {
+        return utils.dropPathSegmentQuotes(String(cur)) in paramIndex;
+    };
+    /**
+     *
+     * @param {string|number|undefined} cur
+     * @returns {import('../iterateJsdoc.js').Integer}
+     */
+    const getParamIndex = (cur) => {
+        return paramIndex[utils.dropPathSegmentQuotes(String(cur))];
+    };
+    /**
+     *
+     * @param {string} cur
+     * @param {import('../iterateJsdoc.js').Integer} idx
+     * @returns {void}
+     */
+    const setParamIndex = (cur, idx) => {
+        paramIndex[utils.dropPathSegmentQuotes(String(cur))] = idx;
+    };
+    for (const [idx, cur,] of flattenedRoots.entries()) {
+        setParamIndex(cur, idx);
+    }
+    /**
+     *
+     * @param {(import('@es-joy/jsdoccomment').JsdocTagWithInline & {
+     *   newAdd?: boolean
+     * })[]} jsdocTags
+     * @param {import('../iterateJsdoc.js').Integer} indexAtFunctionParams
+     * @returns {import('../iterateJsdoc.js').Integer}
+     */
+    const findExpectedIndex = (jsdocTags, indexAtFunctionParams) => {
+        const remainingRoots = functionParameterNames.slice(indexAtFunctionParams || 0);
+        const foundIndex = jsdocTags.findIndex(({ name, newAdd, }) => {
+            return !newAdd && remainingRoots.some((remainingRoot) => {
+                if (Array.isArray(remainingRoot)) {
+                    return (
+                    /**
+                     * @type {import('../jsdocUtils.js').FlattendRootInfo & {
+                     *   annotationParamName?: string|undefined;
+                     * }}
+                     */ (remainingRoot[1]).names.includes(name));
+                }
+                if (typeof remainingRoot === 'object') {
+                    return name === remainingRoot.name;
+                }
+                return name === remainingRoot;
+            });
+        });
+        const tags = foundIndex > -1 ?
+            jsdocTags.slice(0, foundIndex) :
+            jsdocTags.filter(({ tag, }) => {
+                return tag === preferredTagName;
+            });
+        let tagLineCount = 0;
+        for (const { source, } of tags) {
+            for (const { tokens: { end, }, } of source) {
+                if (!end) {
+                    tagLineCount++;
+                }
+            }
+        }
+        return tagLineCount;
+    };
+    let [nextRootName, incremented, namer,] = rootNamer([
+        ...unnamedRootBase,
+    ], autoIncrementBase);
+    const thisOffset = functionParameterNames[0] === 'this' ? 1 : 0;
+    for (const [functionParameterIdx, functionParameterName,] of functionParameterNames.entries()) {
+        let inc;
+        if (Array.isArray(functionParameterName)) {
+            const matchedJsdoc = shallowJsdocParameterNames[functionParameterIdx - thisOffset];
+            /** @type {string} */
+            let rootName;
+            if (functionParameterName[0]) {
+                rootName = functionParameterName[0];
+            }
+            else if (matchedJsdoc && matchedJsdoc.name) {
+                rootName = matchedJsdoc.name;
+                if (matchedJsdoc.type && matchedJsdoc.type.search(checkTypesRegex) === -1) {
+                    continue;
+                }
+            }
+            else {
+                rootName = nextRootName;
+                inc = incremented;
+            }
+            [
+                nextRootName,
+                incremented,
+                namer,
+            ] = namer();
+            const { hasPropertyRest, hasRestElement, names, rests, } = /**
+                 * @type {import('../jsdocUtils.js').FlattendRootInfo & {
+                 *   annotationParamName?: string | undefined;
+                 * }}
+                 */ (functionParameterName[1]);
+            const notCheckingNames = [];
+            if (!enableRestElementFixer && hasRestElement) {
+                continue;
+            }
+            if (!checkDestructuredRoots) {
+                continue;
+            }
+            for (const [idx, paramName,] of names.entries()) {
+                // Add root if the root name is not in the docs (and is not already
+                //  in the tags to be fixed)
+                if (!jsdocParameterNames.find(({ name, }) => {
+                    return name === rootName;
+                }) && !missingTags.find(({ functionParameterName: fpn, }) => {
+                    return fpn === rootName;
+                })) {
+                    const emptyParamIdx = jsdocParameterNames.findIndex(({ name, }) => {
+                        return !name;
+                    });
+                    if (emptyParamIdx > -1) {
+                        missingTags.push({
+                            functionParameterIdx: emptyParamIdx,
+                            functionParameterName: rootName,
+                            inc,
+                            remove: true,
+                        });
+                    }
+                    else {
+                        missingTags.push({
+                            functionParameterIdx: hasParamIndex(rootName) ?
+                                getParamIndex(rootName) :
+                                getParamIndex(paramName),
+                            functionParameterName: rootName,
+                            inc,
+                        });
+                    }
+                }
+                if (!checkDestructured) {
+                    continue;
+                }
+                if (!checkRestProperty && rests[idx]) {
+                    continue;
+                }
+                const fullParamName = `${rootName}.${paramName}`;
+                const notCheckingName = jsdocParameterNames.find(({ name, type: paramType, }) => {
+                    return utils.comparePaths(name)(fullParamName) && paramType.search(checkTypesRegex) === -1 && paramType !== '';
+                });
+                if (notCheckingName !== undefined) {
+                    notCheckingNames.push(notCheckingName.name);
+                }
+                if (notCheckingNames.find((name) => {
+                    return fullParamName.startsWith(name);
+                })) {
+                    continue;
+                }
+                if (jsdocParameterNames && !jsdocParameterNames.find(({ name, }) => {
+                    return utils.comparePaths(name)(fullParamName);
+                })) {
+                    missingTags.push({
+                        functionParameterIdx: getParamIndex(functionParameterName[0] ? fullParamName : paramName),
+                        functionParameterName: fullParamName,
+                        inc,
+                        type: hasRestElement && !hasPropertyRest ? '{...any}' : undefined,
+                    });
+                }
+            }
+            continue;
+        }
+        /** @type {string} */
+        let funcParamName;
+        let type;
+        if (typeof functionParameterName === 'object') {
+            if (!enableRestElementFixer && functionParameterName.restElement) {
+                continue;
+            }
+            funcParamName = /** @type {string} */ (functionParameterName.name);
+            type = '{...any}';
+        }
+        else {
+            funcParamName = /** @type {string} */ (functionParameterName);
+        }
+        if (jsdocParameterNames && !jsdocParameterNames.find(({ name, }) => {
+            return name === funcParamName;
+        }) && funcParamName !== 'this') {
+            missingTags.push({
+                functionParameterIdx: getParamIndex(funcParamName),
+                functionParameterName: funcParamName,
+                inc,
+                type,
+            });
+        }
+    }
+    /**
+     *
+     * @param {{
+     *   functionParameterIdx: import('../iterateJsdoc.js').Integer,
+     *   functionParameterName: string,
+     *   remove?: true,
+     *   inc?: boolean,
+     *   type?: string
+     * }} cfg
+     */
+    const fix = ({ functionParameterIdx, functionParameterName, inc, remove, type, }) => {
+        if (inc && !enableRootFixer) {
+            return;
+        }
+        /**
+         *
+         * @param {import('../iterateJsdoc.js').Integer} tagIndex
+         * @param {import('../iterateJsdoc.js').Integer} sourceIndex
+         * @param {import('../iterateJsdoc.js').Integer} spliceCount
+         * @returns {void}
+         */
+        const createTokens = (tagIndex, sourceIndex, spliceCount) => {
+            // console.log(sourceIndex, tagIndex, jsdoc.tags, jsdoc.source);
+            const tokens = {
+                number: sourceIndex + 1,
+                source: '',
+                tokens: {
+                    delimiter: '*',
+                    description: '',
+                    end: '',
+                    lineEnd: '',
+                    name: functionParameterName,
+                    newAdd: true,
+                    postDelimiter: ' ',
+                    postName: '',
+                    postTag: ' ',
+                    postType: type ? ' ' : '',
+                    start: jsdoc.source[sourceIndex].tokens.start,
+                    tag: `@${preferredTagName}`,
+                    type: type ?? '',
+                },
+            };
+            /**
+             * @type {(import('@es-joy/jsdoccomment').JsdocTagWithInline & {
+             *   newAdd?: true
+             * })[]}
+             */ (jsdoc.tags).splice(tagIndex, spliceCount, {
+                description: '',
+                inlineTags: [],
+                name: functionParameterName,
+                newAdd: true,
+                optional: false,
+                problems: [],
+                source: [
+                    tokens,
+                ],
+                tag: preferredTagName,
+                type: type ?? '',
+            });
+            const firstNumber = jsdoc.source[0].number;
+            jsdoc.source.splice(sourceIndex, spliceCount, tokens);
+            for (const [idx, src,] of jsdoc.source.slice(sourceIndex).entries()) {
+                src.number = firstNumber + sourceIndex + idx;
+            }
+        };
+        const offset = jsdoc.source.findIndex(({ tokens: { end, tag, }, }) => {
+            return tag || end;
+        });
+        if (remove) {
+            createTokens(functionParameterIdx, offset + functionParameterIdx, 1);
+        }
+        else {
+            const expectedIdx = findExpectedIndex(jsdoc.tags, functionParameterIdx);
+            createTokens(expectedIdx, offset + expectedIdx, 0);
+        }
+    };
+    /**
+     * @returns {void}
+     */
+    const fixer = () => {
+        for (const missingTag of missingTags) {
+            fix(missingTag);
+        }
+    };
+    if (missingTags.length && jsdoc.source.length === 1) {
+        utils.makeMultiline();
+    }
+    for (const { functionParameterName, } of missingTags) {
+        utils.reportJSDoc(`Missing JSDoc @${preferredTagName} "${functionParameterName}" declaration.`, null, enableFixer ? fixer : null);
+    }
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that all function parameters are documented.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    autoIncrementBase: {
+                        default: 0,
+                        type: 'integer',
+                    },
+                    checkConstructors: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkDestructured: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkDestructuredRoots: {
+                        default: true,
+                        type: 'boolean',
+                    },
+                    checkGetters: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    checkRestProperty: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    checkSetters: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    checkTypesPattern: {
+                        type: 'string',
+                    },
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                    enableFixer: {
+                        type: 'boolean',
+                    },
+                    enableRestElementFixer: {
+                        type: 'boolean',
+                    },
+                    enableRootFixer: {
+                        type: 'boolean',
+                    },
+                    exemptedBy: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    ignoreWhenAllParamsMissing: {
+                        type: 'boolean',
+                    },
+                    unnamedRootBase: {
+                        items: {
+                            type: 'string',
+                        },
+                        type: 'array',
+                    },
+                    useDefaultObjectProperties: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+    // We cannot cache comment nodes as the contexts may recur with the
+    //  same comment node but a different JS node, and we may need the different
+    //  JS node to ensure we iterate its context
+    noTracking: true,
+});

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

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

package/dist/cjs/rules/requireParamDescription.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, report, settings, utils, }) => {
+    const { defaultDestructuredRootDescription = 'The root object', setDefaultDestructuredRootDescription = false, } = context.options[0] || {};
+    const functionParameterNames = utils.getFunctionParameterNames();
+    let rootCount = -1;
+    utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
+        rootCount += jsdocParameter.name.includes('.') ? 0 : 1;
+        if (!jsdocParameter.description.trim()) {
+            if (Array.isArray(functionParameterNames[rootCount])) {
+                if (settings.exemptDestructuredRootsFromChecks) {
+                    return;
+                }
+                if (setDefaultDestructuredRootDescription) {
+                    utils.reportJSDoc(`Missing root description for @${targetTagName}.`, jsdocParameter, () => {
+                        utils.changeTag(jsdocParameter, {
+                            description: defaultDestructuredRootDescription,
+                            postName: ' ',
+                        });
+                    });
+                    return;
+                }
+            }
+            report(`Missing JSDoc @${targetTagName} "${jsdocParameter.name}" description.`, null, jsdocParameter);
+        }
+    });
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that each `@param` tag has a `description` value.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-description.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                    defaultDestructuredRootDescription: {
+                        type: 'string',
+                    },
+                    setDefaultDestructuredRootDescription: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/requireParamName.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ report, utils, }) => {
+    utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
+        if (jsdocParameter.tag && jsdocParameter.name === '') {
+            report(`There must be an identifier after @${targetTagName} ${jsdocParameter.type === '' ? 'type' : 'tag'}.`, null, jsdocParameter);
+        }
+    });
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that all function parameters have names.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md#repos-sticky-header',
+        },
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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