eslint-plugin-jsdoc 55.4.0 → 56.0.0

package/dist/cjs/rules/noMissingSyntax.js

@@ -0,0 +1,164 @@
+"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 {{
+ *   comment: string,
+ *   context: string,
+ *   message: string,
+ *   minimum: import('../iterateJsdoc.js').Integer
+ * }} ContextObject
+ */
+/**
+ * @typedef {string|ContextObject} Context
+ */
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @returns {void}
+ */
+const setDefaults = (state) => {
+    if (!state.selectorMap) {
+        state.selectorMap = {};
+    }
+};
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @param {string} selector
+ * @param {string} comment
+ * @returns {void}
+ */
+const incrementSelector = (state, selector, comment) => {
+    if (!state.selectorMap[selector]) {
+        state.selectorMap[selector] = {};
+    }
+    if (!state.selectorMap[selector][comment]) {
+        state.selectorMap[selector][comment] = 0;
+    }
+    state.selectorMap[selector][comment]++;
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, info: { comment, }, state, utils, }) => {
+    if (!context.options[0]) {
+        // Handle error later
+        return;
+    }
+    /**
+     * @type {Context[]}
+     */
+    const contexts = context.options[0].contexts;
+    const { contextStr, } = utils.findContext(contexts, comment);
+    setDefaults(state);
+    incrementSelector(state, contextStr, String(comment));
+}, {
+    contextSelected: true,
+    exit({ context, settings, state, }) {
+        if (!context.options.length && !settings.contexts) {
+            context.report({
+                loc: {
+                    end: {
+                        column: 1,
+                        line: 1,
+                    },
+                    start: {
+                        column: 1,
+                        line: 1,
+                    },
+                },
+                message: 'Rule `no-missing-syntax` is missing a `contexts` option.',
+            });
+            return;
+        }
+        setDefaults(state);
+        /**
+         * @type {Context[]}
+         */
+        const contexts = (context.options[0] ?? {}).contexts ?? settings?.contexts;
+        // Report when MISSING
+        contexts.some((cntxt) => {
+            const contextStr = typeof cntxt === 'object' ? cntxt.context ?? 'any' : cntxt;
+            const comment = typeof cntxt === 'string' ? '' : cntxt?.comment;
+            const contextKey = contextStr === 'any' ? 'undefined' : contextStr;
+            if ((!state.selectorMap[contextKey] ||
+                !state.selectorMap[contextKey][comment] ||
+                state.selectorMap[contextKey][comment] < (
+                // @ts-expect-error comment would need an object, not string
+                cntxt?.minimum ?? 1)) &&
+                (contextStr !== 'any' || Object.values(state.selectorMap).every((cmmnt) => {
+                    return !cmmnt[comment] || cmmnt[comment] < (
+                    // @ts-expect-error comment would need an object, not string
+                    cntxt?.minimum ?? 1);
+                }))) {
+                const message = typeof cntxt === 'string' ?
+                    'Syntax is required: {{context}}' :
+                    cntxt?.message ?? ('Syntax is required: {{context}}' +
+                        (comment ? ' with {{comment}}' : ''));
+                context.report({
+                    data: {
+                        comment,
+                        context: contextStr,
+                    },
+                    loc: {
+                        end: {
+                            column: 1,
+                            line: 1,
+                        },
+                        start: {
+                            column: 1,
+                            line: 1,
+                        },
+                    },
+                    message,
+                });
+                return true;
+            }
+            return false;
+        });
+    },
+    matchContext: true,
+    meta: {
+        docs: {
+            description: 'Reports when certain comment structures are always expected.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-missing-syntax.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                        message: {
+                                            type: 'string',
+                                        },
+                                        minimum: {
+                                            type: 'integer',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/noMultiAsterisks.js

@@ -0,0 +1,83 @@
+"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 middleAsterisksBlockWS = /^([\t ]|\*(?!\*))+/v;
+const middleAsterisksNoBlockWS = /^\*+/v;
+const endAsterisksSingleLineBlockWS = /\*((?:\*|(?: |\t))*)\*$/v;
+const endAsterisksMultipleLineBlockWS = /((?:\*|(?: |\t))*)\*$/v;
+const endAsterisksSingleLineNoBlockWS = /\*(\**)\*$/v;
+const endAsterisksMultipleLineNoBlockWS = /(\**)\*$/v;
+exports.default = (0, iterateJsdoc_js_1.default)(({ context, jsdoc, utils, }) => {
+    const { allowWhitespace = false, preventAtEnd = true, preventAtMiddleLines = true, } = context.options[0] || {};
+    const middleAsterisks = allowWhitespace ? middleAsterisksNoBlockWS : middleAsterisksBlockWS;
+    // eslint-disable-next-line complexity -- Todo
+    jsdoc.source.some(({ number, tokens, }) => {
+        const { delimiter, description, end, name, postDelimiter, tag, type, } = tokens;
+        if (preventAtMiddleLines &&
+            !end && !tag && !type && !name &&
+            (!allowWhitespace && middleAsterisks.test(description) ||
+                allowWhitespace && middleAsterisks.test(postDelimiter + description))) {
+            // console.log('description', JSON.stringify(description));
+            const fix = () => {
+                tokens.description = description.replace(middleAsterisks, '');
+            };
+            utils.reportJSDoc('Should be no multiple asterisks on middle lines.', {
+                line: number,
+            }, fix, true);
+            return true;
+        }
+        if (!preventAtEnd || !end) {
+            return false;
+        }
+        const isSingleLineBlock = delimiter === '/**';
+        const delim = isSingleLineBlock ? '*' : delimiter;
+        const endAsterisks = allowWhitespace ?
+            (isSingleLineBlock ? endAsterisksSingleLineNoBlockWS : endAsterisksMultipleLineNoBlockWS) :
+            (isSingleLineBlock ? endAsterisksSingleLineBlockWS : endAsterisksMultipleLineBlockWS);
+        const endingAsterisksAndSpaces = (allowWhitespace ? postDelimiter + description + delim : description + delim).match(endAsterisks);
+        if (!endingAsterisksAndSpaces ||
+            !isSingleLineBlock && endingAsterisksAndSpaces[1] && !endingAsterisksAndSpaces[1].trim()) {
+            return false;
+        }
+        const endFix = () => {
+            if (!isSingleLineBlock) {
+                tokens.delimiter = '';
+            }
+            tokens.description = (description + delim).replace(endAsterisks, '');
+        };
+        utils.reportJSDoc('Should be no multiple asterisks on end lines.', {
+            line: number,
+        }, endFix, true);
+        return true;
+    });
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Prevents use of multiple asterisks at the beginning of lines.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-multi-asterisks.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    allowWhitespace: {
+                        type: 'boolean',
+                    },
+                    preventAtEnd: {
+                        type: 'boolean',
+                    },
+                    preventAtMiddleLines: {
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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

package/dist/cjs/rules/noRestrictedSyntax.js

@@ -0,0 +1,75 @@
+"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, info: { comment, }, report, utils, }) => {
+    if (!context.options.length) {
+        report('Rule `no-restricted-syntax` is missing a `contexts` option.');
+        return;
+    }
+    const { contexts, } = context.options[0];
+    const { contextStr, foundContext, } = utils.findContext(contexts, comment);
+    // We are not on the *particular* matching context/comment, so don't assume
+    //   we need reporting
+    if (!foundContext) {
+        return;
+    }
+    const message = /** @type {import('../iterateJsdoc.js').ContextObject} */ (foundContext)?.message ??
+        'Syntax is restricted: {{context}}' +
+            (comment ? ' with {{comment}}' : '');
+    report(message, null, null, comment ? {
+        comment,
+        context: contextStr,
+    } : {
+        context: contextStr,
+    });
+}, {
+    contextSelected: true,
+    meta: {
+        docs: {
+            description: 'Reports when certain comment structures are present.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-restricted-syntax.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    contexts: {
+                        items: {
+                            anyOf: [
+                                {
+                                    type: 'string',
+                                },
+                                {
+                                    additionalProperties: false,
+                                    properties: {
+                                        comment: {
+                                            type: 'string',
+                                        },
+                                        context: {
+                                            type: 'string',
+                                        },
+                                        message: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            ],
+                        },
+                        type: 'array',
+                    },
+                },
+                required: [
+                    'contexts',
+                ],
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+    nonGlobalSettings: true,
+});

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

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

package/dist/cjs/rules/noTypes.js

@@ -0,0 +1,88 @@
+"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"));
+/**
+ * @param {import('comment-parser').Line} line
+ */
+const removeType = ({ tokens, }) => {
+    tokens.postTag = '';
+    tokens.type = '';
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ node, utils, }) => {
+    if (!utils.isIteratingFunctionOrVariable() && !utils.isVirtualFunction()) {
+        return;
+    }
+    const tags = utils.getPresentTags([
+        'param', 'arg', 'argument', 'returns', 'return',
+    ]);
+    for (const tag of tags) {
+        if (tag.type) {
+            utils.reportJSDoc(`Types are not permitted on @${tag.tag}.`, tag, () => {
+                for (const source of tag.source) {
+                    removeType(source);
+                }
+            });
+        }
+    }
+    if (node?.type === 'ClassDeclaration') {
+        const propertyTags = utils.getPresentTags([
+            'prop', 'property',
+        ]);
+        for (const tag of propertyTags) {
+            if (tag.type) {
+                utils.reportJSDoc(`Types are not permitted on @${tag.tag} in the supplied context.`, tag, () => {
+                    for (const source of tag.source) {
+                        removeType(source);
+                    }
+                });
+            }
+        }
+    }
+}, {
+    contextDefaults: [
+        'ArrowFunctionExpression', 'FunctionDeclaration', 'FunctionExpression', 'TSDeclareFunction',
+        // Add this to above defaults
+        'TSMethodSignature', 'ClassDeclaration',
+    ],
+    meta: {
+        docs: {
+            description: 'This rule reports types being used on `@param` or `@returns`.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/no-types.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',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+});

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

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