eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/textEscaping.js

@@ -1,125 +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"));
-// We could disallow raw gt, quot, and apos, but allow for parity; but we do
-//  not allow hex or decimal character references
-const htmlRegex = /(<|&(?!(?:amp|lt|gt|quot|apos);))(?=\S)/v;
-const markdownRegex = /(?<!\\)(`+)([^`]+)\1(?!`)/v;
-/**
- * @param {string} desc
- * @returns {string}
- */
-const htmlReplacer = (desc) => {
-    return desc.replaceAll(new RegExp(htmlRegex, 'gv'), (_) => {
-        if (_ === '<') {
-            return '&lt;';
-        }
-        return '&amp;';
-    });
-};
-/**
- * @param {string} desc
- * @returns {string}
- */
-const markdownReplacer = (desc) => {
-    return desc.replaceAll(new RegExp(markdownRegex, 'gv'), (_, backticks, encapsed) => {
-        const bookend = '`'.repeat(backticks.length);
-        return `\\${bookend}${encapsed}${bookend}`;
-    });
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
-    const { escapeHTML, escapeMarkdown, } = context.options[0] || {};
-    if (!escapeHTML && !escapeMarkdown) {
-        context.report({
-            loc: {
-                end: {
-                    column: 1,
-                    line: 1,
-                },
-                start: {
-                    column: 1,
-                    line: 1,
-                },
-            },
-            message: 'You must include either `escapeHTML` or `escapeMarkdown`',
-        });
-        return;
-    }
-    const { descriptions, } = utils.getDescription();
-    if (escapeHTML) {
-        if (descriptions.some((desc) => {
-            return htmlRegex.test(desc);
-        })) {
-            const line = utils.setDescriptionLines(htmlRegex, htmlReplacer);
-            utils.reportJSDoc('You have unescaped HTML characters < or &', {
-                line,
-            }, () => { }, true);
-            return;
-        }
-        for (const tag of jsdoc.tags) {
-            if (tag.tag === 'example') {
-                continue;
-            }
-            if ( /** @type {string[]} */(utils.getTagDescription(tag, true)).some((desc) => {
-                return htmlRegex.test(desc);
-            })) {
-                const line = utils.setTagDescription(tag, htmlRegex, htmlReplacer) +
-                    tag.source[0].number;
-                utils.reportJSDoc('You have unescaped HTML characters < or & in a tag', {
-                    line,
-                }, () => { }, true);
-            }
-        }
-        return;
-    }
-    if (descriptions.some((desc) => {
-        return markdownRegex.test(desc);
-    })) {
-        const line = utils.setDescriptionLines(markdownRegex, markdownReplacer);
-        utils.reportJSDoc('You have unescaped Markdown backtick sequences', {
-            line,
-        }, () => { }, true);
-        return;
-    }
-    for (const tag of jsdoc.tags) {
-        if (tag.tag === 'example') {
-            continue;
-        }
-        if ( /** @type {string[]} */(utils.getTagDescription(tag, true)).some((desc) => {
-            return markdownRegex.test(desc);
-        })) {
-            const line = utils.setTagDescription(tag, markdownRegex, markdownReplacer) + tag.source[0].number;
-            utils.reportJSDoc('You have unescaped Markdown backtick sequences in a tag', {
-                line,
-            }, () => { }, true);
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Auto-escape certain characters that are input within block and tag descriptions.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/text-escaping.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    // Option properties here (or remove the object)
-                    escapeHTML: {
-                        type: 'boolean',
-                    },
-                    escapeMarkdown: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/typeFormatting.js

@@ -1,328 +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"));
-const jsdoccomment_1 = require("@es-joy/jsdoccomment");
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, indent, jsdoc, settings, utils, }) => {
-    const { arrayBrackets = 'square', enableFixer = true, genericDot = false, objectFieldIndent = '', objectFieldQuote = null, objectFieldSeparator = 'comma', objectFieldSeparatorTrailingPunctuation = false, propertyQuotes = null, separatorForSingleObjectField = false, stringQuotes = 'single', typeBracketSpacing = '', unionSpacing = ' ', } = context.options[0] || {};
-    const { mode, } = settings;
-    /**
-     * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} tag
-     */
-    const checkTypeFormats = (tag) => {
-        const potentialType = tag.type;
-        let parsedType;
-        try {
-            parsedType = mode === 'permissive' ?
-                (0, jsdoccomment_1.tryParse)(/** @type {string} */ (potentialType)) :
-                (0, jsdoccomment_1.parse)(/** @type {string} */ (potentialType), mode);
-        }
-        catch {
-            return;
-        }
-        const fix = () => {
-            const typeLines = (0, jsdoccomment_1.stringify)(parsedType).split('\n');
-            const firstTypeLine = typeLines.shift();
-            const lastTypeLine = typeLines.pop();
-            const beginNameOrDescIdx = tag.source.findIndex(({ tokens, }) => {
-                return tokens.name || tokens.description;
-            });
-            const nameAndDesc = beginNameOrDescIdx === -1 ?
-                null :
-                tag.source.slice(beginNameOrDescIdx);
-            const initialNumber = tag.source[0].number;
-            const src = [
-                // Get inevitably present tag from first `tag.source`
-                {
-                    number: initialNumber,
-                    source: '',
-                    tokens: {
-                        ...tag.source[0].tokens,
-                        ...(typeLines.length || lastTypeLine ? {
-                            end: '',
-                            name: '',
-                            postName: '',
-                            postType: '',
-                        } : {}),
-                        type: '{' + typeBracketSpacing + firstTypeLine + (!typeLines.length && lastTypeLine === undefined ? typeBracketSpacing + '}' : ''),
-                    },
-                },
-                // Get any intervening type lines
-                ...(typeLines.length ? typeLines.map((typeLine, idx) => {
-                    return {
-                        number: initialNumber + idx + 1,
-                        source: '',
-                        tokens: {
-                            // Grab any delimiter info from first item
-                            ...tag.source[0].tokens,
-                            delimiter: tag.source[0].tokens.delimiter === '/**' ? '*' : tag.source[0].tokens.delimiter,
-                            end: '',
-                            name: '',
-                            postName: '',
-                            postTag: '',
-                            postType: '',
-                            start: indent + ' ',
-                            tag: '',
-                            type: typeLine,
-                        },
-                    };
-                }) : []),
-            ];
-            // Merge any final type line and name and description
-            if (
-            // Name and description may be already included if present with the tag
-            nameAndDesc && beginNameOrDescIdx > 0) {
-                src.push({
-                    number: src.length + 1,
-                    source: '',
-                    tokens: {
-                        ...nameAndDesc[0].tokens,
-                        type: lastTypeLine + typeBracketSpacing + '}',
-                    },
-                });
-                if (
-                // Get any remaining description lines
-                nameAndDesc.length > 1) {
-                    src.push(...nameAndDesc.slice(1).map(({ source, tokens, }, idx) => {
-                        return {
-                            number: src.length + idx + 2,
-                            source,
-                            tokens,
-                        };
-                    }));
-                }
-            }
-            else if (nameAndDesc) {
-                if (lastTypeLine) {
-                    src.push({
-                        number: src.length + 1,
-                        source: '',
-                        tokens: {
-                            ...nameAndDesc[0].tokens,
-                            delimiter: nameAndDesc[0].tokens.delimiter === '/**' ? '*' : nameAndDesc[0].tokens.delimiter,
-                            postTag: '',
-                            start: indent + ' ',
-                            tag: '',
-                            type: lastTypeLine + typeBracketSpacing + '}',
-                        },
-                    });
-                }
-                if (
-                // Get any remaining description lines
-                nameAndDesc.length > 1) {
-                    src.push(...nameAndDesc.slice(1).map(({ source, tokens, }, idx) => {
-                        return {
-                            number: src.length + idx + 2,
-                            source,
-                            tokens,
-                        };
-                    }));
-                }
-            }
-            tag.source = src;
-            // Properly rewire `jsdoc.source`
-            const firstTagIdx = jsdoc.source.findIndex(({ tokens: { tag: tg, }, }) => {
-                return tg;
-            });
-            const initialEndSource = jsdoc.source.find(({ tokens: { end, }, }) => {
-                return end;
-            });
-            jsdoc.source = [
-                ...jsdoc.source.slice(0, firstTagIdx),
-                ...jsdoc.tags.flatMap(({ source, }) => {
-                    return source;
-                }),
-            ];
-            if (initialEndSource && !jsdoc.source.at(-1)?.tokens?.end) {
-                jsdoc.source.push(initialEndSource);
-            }
-        };
-        /** @type {string[]} */
-        const errorMessages = [];
-        if (typeBracketSpacing && (!tag.type.startsWith(typeBracketSpacing) || !tag.type.endsWith(typeBracketSpacing))) {
-            errorMessages.push(`Must have initial and final "${typeBracketSpacing}" spacing`);
-        }
-        else if (!typeBracketSpacing && ((/^\s/v).test(tag.type) || (/\s$/v).test(tag.type))) {
-            errorMessages.push('Must have no initial spacing');
-        }
-        // eslint-disable-next-line complexity -- Todo
-        (0, jsdoccomment_1.traverse)(parsedType, (nde) => {
-            let errorMessage = '';
-            switch (nde.type) {
-                case 'JsdocTypeGeneric': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').GenericResult} */ (nde);
-                    if ('value' in typeNode.left && typeNode.left.value === 'Array') {
-                        if (typeNode.meta.brackets !== arrayBrackets) {
-                            typeNode.meta.brackets = arrayBrackets;
-                            errorMessage = `Array bracket style should be ${arrayBrackets}`;
-                        }
-                    }
-                    else if (typeNode.meta.dot !== genericDot) {
-                        typeNode.meta.dot = genericDot;
-                        errorMessage = `Dot usage should be ${genericDot}`;
-                    }
-                    break;
-                }
-                case 'JsdocTypeObject': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectResult} */ (nde);
-                    if (
-                    /* c8 ignore next -- Guard */
-                    (typeNode.meta.separator ?? 'comma') !== objectFieldSeparator ||
-                        (typeNode.meta.separatorForSingleObjectField ?? false) !== separatorForSingleObjectField ||
-                        (typeNode.meta.propertyIndent ?? '') !== objectFieldIndent ||
-                        (typeNode.meta.trailingPunctuation ?? false) !== objectFieldSeparatorTrailingPunctuation) {
-                        typeNode.meta.separator = objectFieldSeparator;
-                        typeNode.meta.separatorForSingleObjectField = separatorForSingleObjectField;
-                        typeNode.meta.propertyIndent = objectFieldIndent;
-                        typeNode.meta.trailingPunctuation = objectFieldSeparatorTrailingPunctuation;
-                        errorMessage = `Inconsistent ${objectFieldSeparator} separator usage`;
-                    }
-                    break;
-                }
-                case 'JsdocTypeObjectField': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').ObjectFieldResult} */ (nde);
-                    if ((objectFieldQuote ||
-                        (typeof typeNode.key === 'string' && !(/\s/v).test(typeNode.key))) &&
-                        typeNode.meta.quote !== (objectFieldQuote ?? undefined)) {
-                        typeNode.meta.quote = objectFieldQuote ?? undefined;
-                        errorMessage = `Inconsistent object field quotes ${objectFieldQuote}`;
-                    }
-                    break;
-                }
-                case 'JsdocTypeProperty': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').PropertyResult} */ (nde);
-                    if ((propertyQuotes ||
-                        (typeof typeNode.value === 'string' && !(/\s/v).test(typeNode.value))) &&
-                        typeNode.meta.quote !== (propertyQuotes ?? undefined)) {
-                        typeNode.meta.quote = propertyQuotes ?? undefined;
-                        errorMessage = `Inconsistent ${propertyQuotes} property quotes usage`;
-                    }
-                    break;
-                }
-                case 'JsdocTypeStringValue': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').StringValueResult} */ (nde);
-                    if (typeNode.meta.quote !== stringQuotes) {
-                        typeNode.meta.quote = stringQuotes;
-                        errorMessage = `Inconsistent ${stringQuotes} string quotes usage`;
-                    }
-                    break;
-                }
-                case 'JsdocTypeUnion': {
-                    const typeNode = /** @type {import('jsdoc-type-pratt-parser').UnionResult} */ (nde);
-                    /* c8 ignore next -- Guard */
-                    if ((typeNode.meta?.spacing ?? ' ') !== unionSpacing) {
-                        typeNode.meta = {
-                            spacing: unionSpacing,
-                        };
-                        errorMessage = `Inconsistent "${unionSpacing}" union spacing usage`;
-                    }
-                    break;
-                }
-                default:
-                    break;
-            }
-            if (errorMessage) {
-                errorMessages.push(errorMessage);
-            }
-        });
-        const differentResult = tag.type !==
-            typeBracketSpacing + (0, jsdoccomment_1.stringify)(parsedType) + typeBracketSpacing;
-        if (errorMessages.length && differentResult) {
-            for (const errorMessage of errorMessages) {
-                utils.reportJSDoc(errorMessage, tag, enableFixer ? fix : null);
-            }
-            // Stringification may have been equal previously (and thus no error reported)
-            //   because the stringification doesn't preserve everything
-        }
-        else if (differentResult) {
-            utils.reportJSDoc('There was an error with type formatting', tag, enableFixer ? fix : null);
-        }
-    };
-    const tags = utils.getPresentTags([
-        'param',
-        'returns',
-        'type',
-        'typedef',
-    ]);
-    for (const tag of tags) {
-        if (tag.type) {
-            checkTypeFormats(tag);
-        }
-    }
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Formats JSDoc type values.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/type-formatting.md#repos-sticky-header',
-        },
-        fixable: 'code',
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    arrayBrackets: {
-                        enum: [
-                            'angle',
-                            'square',
-                        ],
-                    },
-                    enableFixer: {
-                        type: 'boolean',
-                    },
-                    genericDot: {
-                        type: 'boolean',
-                    },
-                    objectFieldIndent: {
-                        type: 'string',
-                    },
-                    objectFieldQuote: {
-                        enum: [
-                            'double',
-                            'single',
-                            null,
-                        ],
-                    },
-                    objectFieldSeparator: {
-                        enum: [
-                            'comma',
-                            'comma-and-linebreak',
-                            'linebreak',
-                            'semicolon',
-                            'semicolon-and-linebreak',
-                        ],
-                    },
-                    objectFieldSeparatorTrailingPunctuation: {
-                        type: 'boolean',
-                    },
-                    propertyQuotes: {
-                        enum: [
-                            'double',
-                            'single',
-                            null,
-                        ],
-                    },
-                    separatorForSingleObjectField: {
-                        type: 'boolean',
-                    },
-                    stringQuotes: {
-                        enum: [
-                            'double',
-                            'single',
-                        ],
-                    },
-                    typeBracketSpacing: {
-                        type: 'string',
-                    },
-                    unionSpacing: {
-                        type: 'string',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});