eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/textEscaping.js

@@ -0,0 +1,125 @@
+"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.d.ts

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

package/dist/cjs/rules/typeFormatting.js

@@ -0,0 +1,328 @@
+"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',
+    },
+});

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

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