eslint-plugin-jsdoc 55.4.0 → 56.0.0

package/dist/cjs/rules/matchDescription.js

@@ -0,0 +1,240 @@
+"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"));
+// If supporting Node >= 10, we could loosen the default to this for the
+//   initial letter: \\p{Upper}
+const matchDescriptionDefault = '^\n?([A-Z`\\d_][\\s\\S]*[.?!`\\p{RGI_Emoji}]\\s*)?$';
+/**
+ * @param {string} value
+ * @param {string} userDefault
+ * @returns {string}
+ */
+const stringOrDefault = (value, userDefault) => {
+    return typeof value === 'string' ?
+        value :
+        userDefault || matchDescriptionDefault;
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, report, utils, }) => {
+    const { mainDescription, matchDescription, message, nonemptyTags = true, tags = {}, } = context.options[0] || {};
+    /**
+     * @param {string} desc
+     * @param {import('comment-parser').Spec} [tag]
+     * @returns {void}
+     */
+    const validateDescription = (desc, tag) => {
+        let mainDescriptionMatch = mainDescription;
+        let errorMessage = message;
+        if (typeof mainDescription === 'object') {
+            mainDescriptionMatch = mainDescription.match;
+            errorMessage = mainDescription.message;
+        }
+        if (mainDescriptionMatch === false && (!tag || !Object.hasOwn(tags, tag.tag))) {
+            return;
+        }
+        let tagValue = mainDescriptionMatch;
+        if (tag) {
+            const tagName = tag.tag;
+            if (typeof tags[tagName] === 'object') {
+                tagValue = tags[tagName].match;
+                errorMessage = tags[tagName].message;
+            }
+            else {
+                tagValue = tags[tagName];
+            }
+        }
+        const regex = utils.getRegexFromString(stringOrDefault(tagValue, matchDescription));
+        if (!regex.test(desc)) {
+            report(errorMessage || 'JSDoc description does not satisfy the regex pattern.', null, tag || {
+                // Add one as description would typically be into block
+                line: jsdoc.source[0].number + 1,
+            });
+        }
+    };
+    const { description, } = utils.getDescription();
+    if (description) {
+        validateDescription(description);
+    }
+    /**
+     * @param {string} tagName
+     * @returns {boolean}
+     */
+    const hasNoTag = (tagName) => {
+        return !tags[tagName];
+    };
+    for (const tag of [
+        'description',
+        'summary',
+        'file',
+        'classdesc',
+    ]) {
+        utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
+            const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
+            if (hasNoTag(targetTagName)) {
+                validateDescription(desc, matchingJsdocTag);
+            }
+        }, true);
+    }
+    if (nonemptyTags) {
+        for (const tag of [
+            'copyright',
+            'example',
+            'see',
+            'todo',
+        ]) {
+            utils.forEachPreferredTag(tag, (matchingJsdocTag, targetTagName) => {
+                const desc = (matchingJsdocTag.name + ' ' + utils.getTagDescription(matchingJsdocTag)).trim();
+                if (hasNoTag(targetTagName) && !(/.+/v).test(desc)) {
+                    report('JSDoc description must not be empty.', null, matchingJsdocTag);
+                }
+            });
+        }
+    }
+    if (!Object.keys(tags).length) {
+        return;
+    }
+    /**
+     * @param {string} tagName
+     * @returns {boolean}
+     */
+    const hasOptionTag = (tagName) => {
+        return Boolean(tags[tagName]);
+    };
+    const whitelistedTags = utils.filterTags(({ tag: tagName, }) => {
+        return hasOptionTag(tagName);
+    });
+    const { tagsWithNames, tagsWithoutNames, } = utils.getTagsByType(whitelistedTags);
+    tagsWithNames.some((tag) => {
+        const desc = /** @type {string} */ (utils.getTagDescription(tag)).replace(/^[\- ]*/v, '')
+            .trim();
+        return validateDescription(desc, tag);
+    });
+    tagsWithoutNames.some((tag) => {
+        const desc = (tag.name + ' ' + utils.getTagDescription(tag)).trim();
+        return validateDescription(desc, tag);
+    });
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Enforces a regular expression pattern on descriptions.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-description.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',
+                    },
+                    mainDescription: {
+                        oneOf: [
+                            {
+                                format: 'regex',
+                                type: 'string',
+                            },
+                            {
+                                type: 'boolean',
+                            },
+                            {
+                                additionalProperties: false,
+                                properties: {
+                                    match: {
+                                        oneOf: [
+                                            {
+                                                format: 'regex',
+                                                type: 'string',
+                                            },
+                                            {
+                                                type: 'boolean',
+                                            },
+                                        ],
+                                    },
+                                    message: {
+                                        type: 'string',
+                                    },
+                                },
+                                type: 'object',
+                            },
+                        ],
+                    },
+                    matchDescription: {
+                        format: 'regex',
+                        type: 'string',
+                    },
+                    message: {
+                        type: 'string',
+                    },
+                    nonemptyTags: {
+                        type: 'boolean',
+                    },
+                    tags: {
+                        patternProperties: {
+                            '.*': {
+                                oneOf: [
+                                    {
+                                        format: 'regex',
+                                        type: 'string',
+                                    },
+                                    {
+                                        enum: [
+                                            true,
+                                        ],
+                                        type: 'boolean',
+                                    },
+                                    {
+                                        additionalProperties: false,
+                                        properties: {
+                                            match: {
+                                                oneOf: [
+                                                    {
+                                                        format: 'regex',
+                                                        type: 'string',
+                                                    },
+                                                    {
+                                                        enum: [
+                                                            true,
+                                                        ],
+                                                        type: 'boolean',
+                                                    },
+                                                ],
+                                            },
+                                            message: {
+                                                type: 'string',
+                                            },
+                                        },
+                                        type: 'object',
+                                    },
+                                ],
+                            },
+                        },
+                        type: 'object',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/matchName.js

@@ -0,0 +1,122 @@
+"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"));
+// eslint-disable-next-line complexity
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, info: { lastIndex, }, jsdoc, report, utils, }) => {
+    const { match, } = context.options[0] || {};
+    if (!match) {
+        report('Rule `no-restricted-syntax` is missing a `match` option.');
+        return;
+    }
+    const { allowName, disallowName, replacement, tags = [
+        '*',
+    ], } = match[ /** @type {import('../iterateJsdoc.js').Integer} */(lastIndex)];
+    const allowNameRegex = allowName && utils.getRegexFromString(allowName);
+    const disallowNameRegex = disallowName && utils.getRegexFromString(disallowName);
+    let applicableTags = jsdoc.tags;
+    if (!tags.includes('*')) {
+        applicableTags = utils.getPresentTags(tags);
+    }
+    let reported = false;
+    for (const tag of applicableTags) {
+        const tagName = tag.name.replace(/^\[/v, '').replace(/(=.*)?\]$/v, '');
+        const allowed = !allowNameRegex || allowNameRegex.test(tagName);
+        const disallowed = disallowNameRegex && disallowNameRegex.test(tagName);
+        const hasRegex = allowNameRegex || disallowNameRegex;
+        if (hasRegex && allowed && !disallowed) {
+            continue;
+        }
+        if (!hasRegex && reported) {
+            continue;
+        }
+        const fixer = () => {
+            for (const src of tag.source) {
+                if (src.tokens.name) {
+                    src.tokens.name = src.tokens.name.replace(disallowNameRegex, replacement);
+                    break;
+                }
+            }
+        };
+        let { message, } = match[ /** @type {import('../iterateJsdoc.js').Integer} */(lastIndex)];
+        if (!message) {
+            if (hasRegex) {
+                message = disallowed ?
+                    `Only allowing names not matching \`${disallowNameRegex}\` but found "${tagName}".` :
+                    `Only allowing names matching \`${allowNameRegex}\` but found "${tagName}".`;
+            }
+            else {
+                message = `Prohibited context for "${tagName}".`;
+            }
+        }
+        utils.reportJSDoc(message, hasRegex ? tag : null, 
+        // We could match up
+        disallowNameRegex && replacement !== undefined ?
+            fixer :
+            null, false, {
+            // Could also supply `context`, `comment`, `tags`
+            allowName,
+            disallowName,
+            name: tagName,
+        });
+        if (!hasRegex) {
+            reported = true;
+        }
+    }
+}, {
+    matchContext: true,
+    meta: {
+        docs: {
+            description: 'Reports the name portion of a JSDoc tag if matching or not matching a given regular expression.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/match-name.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    match: {
+                        items: {
+                            additionalProperties: false,
+                            properties: {
+                                allowName: {
+                                    type: 'string',
+                                },
+                                comment: {
+                                    type: 'string',
+                                },
+                                context: {
+                                    type: 'string',
+                                },
+                                disallowName: {
+                                    type: 'string',
+                                },
+                                message: {
+                                    type: 'string',
+                                },
+                                replacement: {
+                                    type: 'string',
+                                },
+                                tags: {
+                                    items: {
+                                        type: 'string',
+                                    },
+                                    type: 'array',
+                                },
+                            },
+                            type: 'object',
+                        },
+                        type: 'array',
+                    },
+                },
+                required: [
+                    'match',
+                ],
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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