eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/sortTags.js

@@ -1,392 +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 defaultTagOrder_js_1 = __importDefault(require("../defaultTagOrder.js"));
-const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
-// eslint-disable-next-line complexity -- Temporary
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
-    const 
-    /**
-     * @type {{
-     *   linesBetween: import('../iterateJsdoc.js').Integer,
-     *   tagSequence: {
-     *     tags: string[]
-     *   }[],
-     *   alphabetizeExtras: boolean,
-     *   reportTagGroupSpacing: boolean,
-     *   reportIntraTagGroupSpacing: boolean,
-     * }}
-     */ { alphabetizeExtras = false, linesBetween = 1, reportIntraTagGroupSpacing = true, reportTagGroupSpacing = true, tagSequence = defaultTagOrder_js_1.default, } = context.options[0] || {};
-    const tagList = tagSequence.flatMap((obj) => {
-        /* typeof obj === 'string' ? obj : */
-        return obj.tags;
-    });
-    const otherPos = tagList.indexOf('-other');
-    const endPos = otherPos > -1 ? otherPos : tagList.length;
-    let ongoingCount = 0;
-    for (const [idx, tag,] of 
-    /**
-     * @type {(
-     *   import('@es-joy/jsdoccomment').JsdocTagWithInline & {
-     *     originalIndex: import('../iterateJsdoc.js').Integer,
-     *     originalLine: import('../iterateJsdoc.js').Integer,
-     *   }
-     * )[]}
-     */ (jsdoc.tags).entries()) {
-        tag.originalIndex = idx;
-        ongoingCount += tag.source.length;
-        tag.originalLine = ongoingCount;
-    }
-    /** @type {import('../iterateJsdoc.js').Integer|undefined} */
-    let firstChangedTagLine;
-    /** @type {import('../iterateJsdoc.js').Integer|undefined} */
-    let firstChangedTagIndex;
-    /**
-     * @type {(import('comment-parser').Spec & {
-     *   originalIndex: import('../iterateJsdoc.js').Integer,
-     *   originalLine: import('../iterateJsdoc.js').Integer,
-     * })[]}
-     */
-    const sortedTags = JSON.parse(JSON.stringify(jsdoc.tags));
-    sortedTags.sort(({ tag: tagNew, }, { originalIndex, originalLine, tag: tagOld, }) => {
-        // Optimize: Just keep relative positions if the same tag name
-        if (tagNew === tagOld) {
-            return 0;
-        }
-        const checkOrSetFirstChanged = () => {
-            if (!firstChangedTagLine || originalLine < firstChangedTagLine) {
-                firstChangedTagLine = originalLine;
-                firstChangedTagIndex = originalIndex;
-            }
-        };
-        const newPos = tagList.indexOf(tagNew);
-        const oldPos = tagList.indexOf(tagOld);
-        const preferredNewPos = newPos === -1 ? endPos : newPos;
-        const preferredOldPos = oldPos === -1 ? endPos : oldPos;
-        if (preferredNewPos < preferredOldPos) {
-            checkOrSetFirstChanged();
-            return -1;
-        }
-        if (preferredNewPos > preferredOldPos) {
-            return 1;
-        }
-        // preferredNewPos === preferredOldPos
-        if (!alphabetizeExtras ||
-            // Optimize: If tagNew (or tagOld which is the same) was found in the
-            //   priority array, it can maintain its relative position—without need
-            //   of alphabetizing (secondary sorting)
-            newPos >= 0) {
-            return 0;
-        }
-        if (tagNew < tagOld) {
-            checkOrSetFirstChanged();
-            return -1;
-        }
-        // tagNew > tagOld
-        return 1;
-    });
-    if (firstChangedTagLine === undefined) {
-        // Should be ordered by now
-        /**
-         * @type {import('comment-parser').Spec[]}
-         */
-        const lastTagsOfGroup = [];
-        /**
-         * @type {[
-         *   import('comment-parser').Spec,
-         *   import('../iterateJsdoc.js').Integer
-         * ][]}
-         */
-        const badLastTagsOfGroup = [];
-        /**
-         * @param {import('comment-parser').Spec} tag
-         */
-        const countTagEmptyLines = (tag) => {
-            return tag.source.reduce((acc, { tokens: { description, end, name, tag: tg, type, }, }) => {
-                const empty = !tg && !type && !name && !description;
-                // Reset the count so long as there is content
-                return empty ? acc + Number(empty && !end) : 0;
-            }, 0);
-        };
-        let idx = 0;
-        for (const { tags, } of tagSequence) {
-            let innerIdx;
-            /** @type {import('comment-parser').Spec} */
-            let currentTag;
-            /** @type {import('comment-parser').Spec|undefined} */
-            let lastTag;
-            do {
-                currentTag = jsdoc.tags[idx];
-                if (!currentTag) {
-                    idx++;
-                    break;
-                }
-                innerIdx = tags.indexOf(currentTag.tag);
-                if (innerIdx === -1 &&
-                    // eslint-disable-next-line no-loop-func -- Safe
-                    (!tags.includes('-other') || tagSequence.some(({ tags: tgs, }) => {
-                        return tgs.includes(currentTag.tag);
-                    }))) {
-                    idx++;
-                    break;
-                }
-                lastTag = currentTag;
-                idx++;
-            } while (true);
-            idx--;
-            if (lastTag) {
-                lastTagsOfGroup.push(lastTag);
-                const ct = countTagEmptyLines(lastTag);
-                if (ct !== linesBetween &&
-                    // Use another rule for adding to end (should be of interest outside this rule)
-                    jsdoc.tags[idx]) {
-                    badLastTagsOfGroup.push([
-                        lastTag, ct,
-                    ]);
-                }
-            }
-        }
-        if (reportTagGroupSpacing && badLastTagsOfGroup.length) {
-            /**
-             * @param {import('comment-parser').Spec} tg
-             * @returns {() => void}
-             */
-            const fixer = (tg) => {
-                return () => {
-                    // Due to https://github.com/syavorsky/comment-parser/issues/110 ,
-                    //  we have to modify `jsdoc.source` rather than just modify tags
-                    //  directly
-                    for (const [currIdx, { tokens, },] of jsdoc.source.entries()) {
-                        if (tokens.tag !== '@' + tg.tag) {
-                            continue;
-                        }
-                        // Cannot be `tokens.end`, as dropped off last tag, so safe to
-                        //  go on
-                        let newIdx = currIdx;
-                        const emptyLine = () => {
-                            return {
-                                number: 0,
-                                source: '',
-                                tokens: utils.seedTokens({
-                                    delimiter: '*',
-                                    start: jsdoc.source[newIdx - 1].tokens.start,
-                                }),
-                            };
-                        };
-                        let existingEmptyLines = 0;
-                        while (true) {
-                            const nextTokens = jsdoc.source[++newIdx]?.tokens;
-                            /* c8 ignore next 3 -- Guard */
-                            if (!nextTokens) {
-                                return;
-                            }
-                            // Should be no `nextTokens.end` to worry about since ignored
-                            //  if not followed by tag
-                            if (nextTokens.tag) {
-                                // Haven't made it to last tag instance yet, so keep looking
-                                if (nextTokens.tag === tokens.tag) {
-                                    existingEmptyLines = 0;
-                                    continue;
-                                }
-                                const lineDiff = linesBetween - existingEmptyLines;
-                                if (lineDiff > 0) {
-                                    const lines = Array.from({
-                                        length: lineDiff,
-                                    }, () => {
-                                        return emptyLine();
-                                    });
-                                    jsdoc.source.splice(newIdx, 0, ...lines);
-                                }
-                                else {
-                                    // lineDiff < 0
-                                    jsdoc.source.splice(newIdx + lineDiff, -lineDiff);
-                                }
-                                break;
-                            }
-                            const empty = !nextTokens.type && !nextTokens.name &&
-                                !nextTokens.description;
-                            if (empty) {
-                                existingEmptyLines++;
-                            }
-                            else {
-                                // Has content again, so reset empty line count
-                                existingEmptyLines = 0;
-                            }
-                        }
-                        break;
-                    }
-                    for (const [srcIdx, src,] of jsdoc.source.entries()) {
-                        src.number = srcIdx;
-                    }
-                };
-            };
-            for (const [tg,] of badLastTagsOfGroup) {
-                utils.reportJSDoc('Tag groups do not have the expected whitespace', tg, fixer(tg));
-            }
-            return;
-        }
-        if (!reportIntraTagGroupSpacing) {
-            return;
-        }
-        for (const [tagIdx, tag,] of jsdoc.tags.entries()) {
-            if (!jsdoc.tags[tagIdx + 1] || lastTagsOfGroup.includes(tag)) {
-                continue;
-            }
-            const ct = countTagEmptyLines(tag);
-            if (ct) {
-                // eslint-disable-next-line complexity -- Temporary
-                const fixer = () => {
-                    let foundFirstTag = false;
-                    /** @type {string|undefined} */
-                    let currentTag;
-                    for (const [currIdx, { tokens: { description, end, name, tag: tg, type, }, },] of jsdoc.source.entries()) {
-                        if (tg) {
-                            foundFirstTag = true;
-                            currentTag = tg;
-                        }
-                        if (!foundFirstTag) {
-                            continue;
-                        }
-                        if (currentTag && !tg && !type && !name && !description && !end) {
-                            let nextIdx = currIdx;
-                            let ignore = true;
-                            // Even if a tag of the same name as the last tags in a group,
-                            //  could still be an earlier tag in that group
-                            // eslint-disable-next-line no-loop-func -- Safe
-                            if (lastTagsOfGroup.some((lastTagOfGroup) => {
-                                return currentTag === '@' + lastTagOfGroup.tag;
-                            })) {
-                                while (true) {
-                                    const nextTokens = jsdoc.source[++nextIdx]?.tokens;
-                                    if (!nextTokens) {
-                                        break;
-                                    }
-                                    if (!nextTokens.tag) {
-                                        continue;
-                                    }
-                                    // Followed by the same tag name, so not actually last in group,
-                                    //   and of interest
-                                    if (nextTokens.tag === currentTag) {
-                                        ignore = false;
-                                    }
-                                }
-                            }
-                            else {
-                                while (true) {
-                                    const nextTokens = jsdoc.source[++nextIdx]?.tokens;
-                                    if (!nextTokens || nextTokens.end) {
-                                        break;
-                                    }
-                                    // Not the very last tag, so don't ignore
-                                    if (nextTokens.tag) {
-                                        ignore = false;
-                                        break;
-                                    }
-                                }
-                            }
-                            if (!ignore) {
-                                jsdoc.source.splice(currIdx, 1);
-                                for (const [srcIdx, src,] of jsdoc.source.entries()) {
-                                    src.number = srcIdx;
-                                }
-                            }
-                        }
-                    }
-                };
-                utils.reportJSDoc('Intra-group tags have unexpected whitespace', tag, fixer);
-            }
-        }
-        return;
-    }
-    const firstLine = utils.getFirstLine();
-    const fix = () => {
-        const itemsToMoveRange = [
-            ...Array.from({
-                length: jsdoc.tags.length -
-                    /** @type {import('../iterateJsdoc.js').Integer} */ (firstChangedTagIndex),
-            }).keys(),
-        ];
-        const unchangedPriorTagDescriptions = jsdoc.tags.slice(0, firstChangedTagIndex).reduce((ct, { source, }) => {
-            return ct + source.length - 1;
-        }, 0);
-        // This offset includes not only the offset from where the first tag
-        //   must begin, and the additional offset of where the first changed
-        //   tag begins, but it must also account for prior descriptions
-        const initialOffset = /** @type {import('../iterateJsdoc.js').Integer} */ (firstLine) + /** @type {import('../iterateJsdoc.js').Integer} */ (firstChangedTagIndex) +
-            // May be the first tag, so don't try finding a prior one if so
-            unchangedPriorTagDescriptions;
-        // Use `firstChangedTagLine` for line number to begin reporting/splicing
-        for (const idx of itemsToMoveRange) {
-            utils.removeTag(idx +
-                /** @type {import('../iterateJsdoc.js').Integer} */ (firstChangedTagIndex));
-        }
-        const changedTags = sortedTags.slice(firstChangedTagIndex);
-        let extraTagCount = 0;
-        for (const idx of itemsToMoveRange) {
-            const changedTag = changedTags[idx];
-            utils.addTag(changedTag.tag, extraTagCount + initialOffset + idx, {
-                ...changedTag.source[0].tokens,
-                // `comment-parser` puts the `end` within the `tags` section, so
-                //   avoid adding another to jsdoc.source
-                end: '',
-            });
-            for (const { tokens, } of changedTag.source.slice(1)) {
-                if (!tokens.end) {
-                    utils.addLine(extraTagCount + initialOffset + idx + 1, {
-                        ...tokens,
-                        end: '',
-                    });
-                    extraTagCount++;
-                }
-            }
-        }
-    };
-    utils.reportJSDoc(`Tags are not in the prescribed order: ${tagList.join(', ') || '(alphabetical)'}`, jsdoc.tags[ /** @type {import('../iterateJsdoc.js').Integer} */(firstChangedTagIndex)], fix, true);
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Sorts tags by a specified sequence according to tag name.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/sort-tags.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    alphabetizeExtras: {
-                        type: 'boolean',
-                    },
-                    linesBetween: {
-                        type: 'integer',
-                    },
-                    reportIntraTagGroupSpacing: {
-                        type: 'boolean',
-                    },
-                    reportTagGroupSpacing: {
-                        type: 'boolean',
-                    },
-                    tagSequence: {
-                        items: {
-                            additionalProperties: false,
-                            properties: {
-                                tags: {
-                                    items: {
-                                        type: 'string',
-                                    },
-                                    type: 'array',
-                                },
-                            },
-                            type: 'object',
-                        },
-                        type: 'array',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/tagLines.js

@@ -1,259 +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"));
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
-    const [alwaysNever = 'never', { applyToEndTag = true, count = 1, endLines = 0, startLines = 0, tags = {}, } = {},] = context.options;
-    // eslint-disable-next-line complexity -- Temporary
-    jsdoc.tags.some((tg, tagIdx) => {
-        let lastTag;
-        /**
-         * @type {null|import('../iterateJsdoc.js').Integer}
-         */
-        let lastEmpty = null;
-        /**
-         * @type {null|import('../iterateJsdoc.js').Integer}
-         */
-        let reportIndex = null;
-        let emptyLinesCount = 0;
-        for (const [idx, { tokens: { description, end, name, tag, type, }, },] of tg.source.entries()) {
-            // May be text after a line break within a tag description
-            if (description) {
-                reportIndex = null;
-            }
-            if (lastTag && [
-                'always', 'any',
-            ].includes(tags[lastTag.slice(1)]?.lines)) {
-                continue;
-            }
-            const empty = !tag && !name && !type && !description;
-            if (empty && !end &&
-                (alwaysNever === 'never' ||
-                    lastTag && tags[lastTag.slice(1)]?.lines === 'never')) {
-                reportIndex = idx;
-                continue;
-            }
-            if (!end) {
-                if (empty) {
-                    emptyLinesCount++;
-                }
-                else {
-                    emptyLinesCount = 0;
-                }
-                lastEmpty = empty ? idx : null;
-            }
-            lastTag = tag;
-        }
-        if (typeof endLines === 'number' &&
-            lastEmpty !== null && tagIdx === jsdoc.tags.length - 1) {
-            const lineDiff = endLines - emptyLinesCount;
-            if (lineDiff < 0) {
-                const fixer = () => {
-                    utils.removeTag(tagIdx, {
-                        tagSourceOffset: /** @type {import('../iterateJsdoc.js').Integer} */ (lastEmpty) + lineDiff + 1,
-                    });
-                };
-                utils.reportJSDoc(`Expected ${endLines} trailing lines`, {
-                    line: tg.source[lastEmpty].number + lineDiff + 1,
-                }, fixer);
-            }
-            else if (lineDiff > 0) {
-                const fixer = () => {
-                    utils.addLines(tagIdx, 
-                    /** @type {import('../iterateJsdoc.js').Integer} */ (lastEmpty), endLines - emptyLinesCount);
-                };
-                utils.reportJSDoc(`Expected ${endLines} trailing lines`, {
-                    line: tg.source[lastEmpty].number,
-                }, fixer);
-            }
-            return true;
-        }
-        if (reportIndex !== null) {
-            const fixer = () => {
-                utils.removeTag(tagIdx, {
-                    tagSourceOffset: /** @type {import('../iterateJsdoc.js').Integer} */ (reportIndex),
-                });
-            };
-            utils.reportJSDoc('Expected no lines between tags', {
-                line: tg.source[0].number + 1,
-            }, fixer);
-            return true;
-        }
-        return false;
-    });
-    (applyToEndTag ? jsdoc.tags : jsdoc.tags.slice(0, -1)).some((tg, tagIdx) => {
-        /**
-         * @type {{
-         *   idx: import('../iterateJsdoc.js').Integer,
-         *   number: import('../iterateJsdoc.js').Integer
-         * }[]}
-         */
-        const lines = [];
-        let currentTag;
-        let tagSourceIdx = 0;
-        for (const [idx, { number, tokens: { description, end, name, tag, type, }, },] of tg.source.entries()) {
-            if (description) {
-                lines.splice(0);
-                tagSourceIdx = idx;
-            }
-            if (tag) {
-                currentTag = tag;
-            }
-            if (!tag && !name && !type && !description && !end) {
-                lines.push({
-                    idx,
-                    number,
-                });
-            }
-        }
-        const currentTg = currentTag && tags[currentTag.slice(1)];
-        const tagCount = currentTg?.count;
-        const defaultAlways = alwaysNever === 'always' && currentTg?.lines !== 'never' &&
-            currentTg?.lines !== 'any' && lines.length < count;
-        let overrideAlways;
-        let fixCount = count;
-        if (!defaultAlways) {
-            fixCount = typeof tagCount === 'number' ? tagCount : count;
-            overrideAlways = currentTg?.lines === 'always' &&
-                lines.length < fixCount;
-        }
-        if (defaultAlways || overrideAlways) {
-            const fixer = () => {
-                utils.addLines(tagIdx, lines[lines.length - 1]?.idx || tagSourceIdx + 1, fixCount - lines.length);
-            };
-            const line = lines[lines.length - 1]?.number || tg.source[tagSourceIdx].number;
-            utils.reportJSDoc(`Expected ${fixCount} line${fixCount === 1 ? '' : 's'} between tags but found ${lines.length}`, {
-                line,
-            }, fixer);
-            return true;
-        }
-        return false;
-    });
-    if (typeof startLines === 'number') {
-        if (!jsdoc.tags.length) {
-            return;
-        }
-        const { description, lastDescriptionLine, } = utils.getDescription();
-        if (!(/\S/v).test(description)) {
-            return;
-        }
-        const trailingLines = description.match(/\n+$/v)?.[0]?.length;
-        const trailingDiff = (trailingLines ?? 0) - startLines;
-        if (trailingDiff > 0) {
-            utils.reportJSDoc(`Expected only ${startLines} line after block description`, {
-                line: lastDescriptionLine - trailingDiff,
-            }, () => {
-                utils.setBlockDescription((info, seedTokens, descLines) => {
-                    return descLines.slice(0, -trailingDiff).map((desc) => {
-                        return {
-                            number: 0,
-                            source: '',
-                            tokens: seedTokens({
-                                ...info,
-                                description: desc,
-                                postDelimiter: desc.trim() ? info.postDelimiter : '',
-                            }),
-                        };
-                    });
-                });
-            });
-        }
-        else if (trailingDiff < 0) {
-            utils.reportJSDoc(`Expected ${startLines} lines after block description`, {
-                line: lastDescriptionLine,
-            }, () => {
-                utils.setBlockDescription((info, seedTokens, descLines) => {
-                    return [
-                        ...descLines,
-                        ...Array.from({
-                            length: -trailingDiff,
-                        }, () => {
-                            return '';
-                        }),
-                    ].map((desc) => {
-                        return {
-                            number: 0,
-                            source: '',
-                            tokens: seedTokens({
-                                ...info,
-                                description: desc,
-                                postDelimiter: desc.trim() ? info.postDelimiter : '',
-                            }),
-                        };
-                    });
-                });
-            });
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Enforces lines (or no lines) between tags.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/tag-lines.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                enum: [
-                    'always', 'any', 'never',
-                ],
-                type: 'string',
-            },
-            {
-                additionalProperties: false,
-                properties: {
-                    applyToEndTag: {
-                        type: 'boolean',
-                    },
-                    count: {
-                        type: 'integer',
-                    },
-                    endLines: {
-                        anyOf: [
-                            {
-                                type: 'integer',
-                            },
-                            {
-                                type: 'null',
-                            },
-                        ],
-                    },
-                    startLines: {
-                        anyOf: [
-                            {
-                                type: 'integer',
-                            },
-                            {
-                                type: 'null',
-                            },
-                        ],
-                    },
-                    tags: {
-                        patternProperties: {
-                            '.*': {
-                                additionalProperties: false,
-                                properties: {
-                                    count: {
-                                        type: 'integer',
-                                    },
-                                    lines: {
-                                        enum: [
-                                            'always', 'never', 'any',
-                                        ],
-                                        type: 'string',
-                                    },
-                                },
-                            },
-                        },
-                        type: 'object',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});