@prowise/eslint-config-linting-rules 2.4.7 → 3.0.1

package/rules/file-progress.js

@@ -0,0 +1,62 @@
+import nanospinner from "nanospinner";
+import path from "node:path";
+import pc from "picocolors";
+
+const spinner = nanospinner.createSpinner("", {
+    frames: ["|", "/", "-", "\\"],
+    color: "cyan",
+});
+
+let bindExit = false;
+let initialReportDone = false;
+
+const defaultSettings = {
+    hide: false,
+    hideFileName: false,
+    successMessage: "Lint done.",
+};
+
+const exitCallback = (exitCode, settings) => {
+    if (exitCode === 0 && settings.hide !== true) {
+        spinner.success({ text: settings.successMessage });
+    }
+};
+
+const create = (context) => {
+    const settings = { ...defaultSettings, ...context.settings.progress };
+
+    if (!bindExit) {
+        process.on("exit", (code) => {
+            exitCallback(code, settings);
+        });
+        bindExit = true;
+    }
+
+    if (settings.hide) {
+        return {};
+    }
+
+    if (!settings.hideFileName) {
+        const { filename } = context;
+        const relativeFilePath = path.relative(context.cwd, filename);
+        spinner.update({ text: `Processing: ${pc.green(relativeFilePath)} \n` });
+    } else if (!initialReportDone) {
+        spinner.update({ text: "Linting...\n" });
+        initialReportDone = true;
+    }
+
+    spinner.spin();
+    return {};
+};
+
+export const progress = {
+    name: import.meta.filename,
+    meta: {
+        type: "suggestion",
+        messages: [],
+        schema: [],
+    },
+    create,
+};
+
+export default { rules: { activate: progress } };

package/rules/jsdoc-newline-before-returns.js

@@ -0,0 +1,48 @@
+/**
+ * Enforce a blank JSDoc line immediately before the @returns tag.
+ */
+export default {
+    meta: {
+        type: "layout",
+        docs: {
+            description: "require a blank line before @returns in JSDoc blocks",
+        },
+        fixable: "whitespace",
+        schema: [],
+    },
+    create: (context) => {
+        const comments = context.sourceCode.getAllComments();
+        return {
+            Program: () => {
+                for (const comment of comments) {
+                    if (comment.type !== "Block" || !comment.value.startsWith("*")) continue;
+                    const lines = comment.value.split("\n");
+                    for (let i = 0; i < lines.length; i++) {
+                        if (lines[i].trim().startsWith("* @returns")) {
+                            if (i > 0 && lines[i - 1].trim() !== "*") {
+                                context.report({
+                                    loc: {
+                                        start: {
+                                            line: comment.loc.start.line + i,
+                                            column: 0,
+                                        },
+                                    },
+                                    message: "JSDoc blocks must have a blank line before `@returns`.",
+                                    fix: (fixer) => {
+                                        const prevLineEnd = comment.range[0] +
+                                            2 +
+                                            lines.slice(0, i).map((l) => l.length + 1).reduce((a, b) => a + b, 0);
+                                        return fixer.insertTextAfterRange(
+                                            [prevLineEnd - 1, prevLineEnd],
+                                            " *\n",
+                                        );
+                                    },
+                                });
+                            }
+                        }
+                    }
+                }
+            },
+        };
+    },
+};

package/rules/jsdoc-optional-param-brackets.js

@@ -0,0 +1,351 @@
+/**
+ * Enforce brackets around optional parameter names in JSDoc @param tags.
+ * When a parameter has a `?` in its TypeScript signature or has a default value,
+ * the JSDoc @param tag should use brackets: `@param [paramName]` instead of `@param paramName`.
+ */
+export default {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "require brackets around optional parameter names in JSDoc @param tags",
+        },
+        fixable: "code",
+        schema: [],
+        messages: {
+            missingBrackets: "Optional parameter '{{paramName}}' should be wrapped in brackets: @param [{{paramName}}]",
+        },
+    },
+    create: (context) => {
+        /**
+         * Extracts parameter name from JSDoc @param line (without brackets).
+         *
+         * @param line - The JSDoc line.
+         *
+         * @returns - The parameter name or null.
+         */
+        function extractParamName(line) {
+            // Match: @param {Type} paramName or @param paramName (but not [paramName])
+            // Also matches nested properties like paramName.property
+            const match = line.match(/@param\s+(?:\{[^}]+}\s+)?(\w+(?:\.\w+)*)/);
+            return match ? match[1] : null;
+        }
+
+        /**
+         * Checks if a parameter name already has correct brackets.
+         *
+         * @param line - The JSDoc line.
+         * @param paramName - The parameter name to check (including nested properties).
+         *
+         * @returns - True if brackets are correctly placed.
+         */
+        function hasBrackets(line, paramName) {
+            // Check if the entire parameter path is wrapped in brackets
+            // e.g., [paramName] or [paramName.property]
+            const escapedParamName = paramName.replace(/\./g, "\\.");
+            // eslint-disable-next-line no-useless-escape
+            const correctBracketPattern = new RegExp(`@param\s+(?:\{[^}]+}\s+)?\[${escapedParamName}\]`);
+            return correctBracketPattern.test(line);
+        }
+
+        /**
+         * Checks if a function parameter is optional.
+         *
+         * @param param - The function parameter node.
+         *
+         * @returns - True if the parameter is optional.
+         */
+        function isOptionalParam(param) {
+            // Check if the parameter has a question mark (optional: true)
+            if (param.optional) {
+                return true;
+            }
+
+            // Check if the parameter has a default value
+            if (param.type === "AssignmentPattern") {
+                return true;
+            }
+
+            // For TypeScript, check TSParameterProperty
+            if (param.type === "TSParameterProperty") {
+                return param.parameter.optional || param.parameter.type === "AssignmentPattern";
+            }
+
+            return false;
+        }
+
+        /**
+         * Gets parameter name from a parameter node.
+         *
+         * @param param - The parameter node.
+         *
+         * @returns - The parameter name or null.
+         */
+        function getParamName(param) {
+            if (param.type === "Identifier") {
+                return param.name;
+            }
+            if (param.type === "ObjectPattern") {
+                return null;
+            }
+            if (param.type === "AssignmentPattern" && param.left.type === "Identifier") {
+                return param.left.name;
+            }
+            if (param.type === "TSParameterProperty") {
+                if (param.parameter.type === "Identifier") {
+                    return param.parameter.name;
+                }
+                if (param.parameter.type === "AssignmentPattern" && param.parameter.left.type === "Identifier") {
+                    return param.parameter.left.name;
+                }
+            }
+            return null;
+        }
+
+        /**
+         * Collects optional JSDoc parameter paths from a destructured object parameter.
+         *
+         * @param pattern - The object pattern node.
+         * @param parentName - The top-level JSDoc parameter name.
+         * @param typeAnnotation - The TypeScript type annotation node.
+         * @param optionalParams - The set to mutate with optional param paths.
+         */
+        function collectOptionalObjectPatternParams(pattern, parentName, typeAnnotation, optionalParams) {
+            if (!pattern || pattern.type !== "ObjectPattern") {
+                return;
+            }
+
+            const typeNode = typeAnnotation?.typeAnnotation;
+            if (!typeNode || typeNode.type !== "TSTypeLiteral") {
+                return;
+            }
+
+            for (const property of pattern.properties) {
+                if (property.type !== "Property" || property.computed) {
+                    continue;
+                }
+
+                const keyName = property.key.type === "Identifier" ? property.key.name : null;
+
+                if (!keyName) {
+                    continue;
+                }
+
+                const matchingMember = typeNode.members.find((member) =>
+                    member.type === "TSPropertySignature" &&
+                    !member.computed &&
+                    member.key.type === "Identifier" &&
+                    member.key.name === keyName,
+                );
+
+                if (matchingMember?.optional) {
+                    optionalParams.add(`${parentName}.${keyName}`);
+                }
+            }
+        }
+
+        /**
+         * Gets a TypeScript type literal for props defined on a variable annotation like FC<{ ... }>.
+         *
+         * @param node - The function node.
+         *
+         * @returns - The type literal node or null.
+         */
+        function getVariablePropsTypeLiteral(node) {
+            if (!node.parent || node.parent.type !== "VariableDeclarator") {
+                return null;
+            }
+
+            const typeAnnotation = node.parent.id?.typeAnnotation?.typeAnnotation;
+
+            if (!typeAnnotation || typeAnnotation.type !== "TSTypeReference") {
+                return null;
+            }
+
+            const typeParams = typeAnnotation.typeArguments?.params;
+
+            if (!typeParams || typeParams.length === 0) {
+                return null;
+            }
+
+            const [firstTypeParam] = typeParams;
+
+            return firstTypeParam?.type === "TSTypeLiteral" ? firstTypeParam : null;
+        }
+
+        /**
+         * Gets the JSDoc comment associated with a node.
+         *
+         * @param node - The AST node.
+         *
+         * @returns - The JSDoc comment or null.
+         */
+        function getJSDocComment(node) {
+            // For arrow/function expressions in variable declarations, get the VariableDeclaration
+            let targetNode = node;
+            if (node.parent && node.parent.type === "VariableDeclarator") {
+                targetNode = node.parent.parent; // VariableDeclaration
+            }
+
+            // For function expressions inside class methods, get the MethodDefinition
+            if (node.parent && node.parent.type === "MethodDefinition") {
+                targetNode = node.parent;
+            }
+
+            // For exported functions, check the parent node
+            if (targetNode.parent && targetNode.parent.type === "ExportNamedDeclaration") {
+                targetNode = targetNode.parent;
+            }
+
+            const comments = context.sourceCode.getCommentsBefore(targetNode);
+            // Look for the last block comment that looks like JSDoc
+            for (let i = comments.length - 1; i >= 0; i--) {
+                const comment = comments[i];
+                if (comment.type === "Block" && comment.value.startsWith("*")) {
+                    return comment;
+                }
+            }
+            return null;
+        }
+
+        /**
+         * Checks a function node for optional parameters.
+         *
+         * @param node - The function node.
+         */
+        function checkFunction(node) {
+            if (!node.params || node.params.length === 0) return;
+
+            const jsdocComment = getJSDocComment(node);
+            if (!jsdocComment) return;
+
+            // Build a set of optional parameter names
+            const optionalParams = new Set();
+            for (const param of node.params) {
+                if (isOptionalParam(param)) {
+                    const paramName = getParamName(param);
+                    if (paramName) {
+                        optionalParams.add(paramName);
+                    }
+                }
+
+                if (param.type === "ObjectPattern") {
+                    collectOptionalObjectPatternParams(param, "props", param.typeAnnotation, optionalParams);
+
+                    const variablePropsTypeLiteral = getVariablePropsTypeLiteral(node);
+                    if (variablePropsTypeLiteral) {
+                        collectOptionalObjectPatternParams(
+                            param,
+                            "props",
+                            { typeAnnotation: variablePropsTypeLiteral },
+                            optionalParams,
+                        );
+                    }
+                }
+
+                if (param.type === "AssignmentPattern" && param.left.type === "ObjectPattern") {
+                    collectOptionalObjectPatternParams(param.left, "props", param.left.typeAnnotation, optionalParams);
+                }
+            }
+
+            if (optionalParams.size === 0) return;
+
+            // Check JSDoc @param tags
+            const lines = jsdocComment.value.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                const trimmedLine = line.trim();
+
+                if (trimmedLine.startsWith("* @param")) {
+                    const paramName = extractParamName(trimmedLine);
+
+                    if (paramName && !hasBrackets(trimmedLine, paramName)) {
+                        // Check if this is a top-level optional param or a nested property
+                        const isTopLevelOptional = optionalParams.has(paramName);
+                        const isNestedProperty = paramName.includes(".");
+                        const parentParam = isNestedProperty ? paramName.split(".")[0] : null;
+                        const isNestedOfOptional = isNestedProperty && parentParam && optionalParams.has(parentParam);
+
+                        if (isTopLevelOptional || isNestedOfOptional) {
+                            const lineNumber = jsdocComment.loc.start.line + i;
+
+                            context.report({
+                                loc: {
+                                    start: {
+                                        line: lineNumber,
+                                        column: 0,
+                                    },
+                                    end: {
+                                        line: lineNumber,
+                                        column: line.length,
+                                    },
+                                },
+                                messageId: "missingBrackets",
+                                data: {
+                                    paramName,
+                                },
+                                fix: (fixer) => {
+                                    // Calculate the position in the comment
+                                    const lineStart = jsdocComment.range[0] + 2 + // "/*"
+                                        lines.slice(0, i).reduce((sum, l) => sum + l.length + 1, 0);
+
+                                    // Find the parameter name in the line and wrap it with brackets
+                                    // Escape dots in paramName for regex
+                                    const escapedParamName = paramName.replace(/\./g, "\\.");
+                                    // Match the pattern, accounting for the * prefix and whitespace
+                                    const paramMatch = line.match(new RegExp(`(\\*\\s*@param\\s+(?:\\{[^}]+\\}\\s+)?)(${escapedParamName})(?=\\s|$)`));
+                                    if (paramMatch) {
+                                        const paramStartInLine = paramMatch.index + paramMatch[1].length;
+                                        const paramStart = lineStart + paramStartInLine;
+                                        const paramEnd = paramStart + paramName.length;
+
+                                        return [
+                                            fixer.insertTextBeforeRange([paramStart, paramEnd], "["),
+                                            fixer.insertTextAfterRange([paramStart, paramEnd], "]"),
+                                        ];
+                                    }
+                                    return null;
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+
+        /**
+         * Checks a variable declarator with function initialization.
+         *
+         * @param node - The VariableDeclarator node.
+         */
+        function checkVariableDeclarator(node) {
+            // Check if the init is a function expression or arrow function
+            if (node.init &&
+                (node.init.type === "FunctionExpression" ||
+                 node.init.type === "ArrowFunctionExpression")) {
+                checkFunction(node.init);
+            }
+        }
+
+        /**
+         * Checks a function declaration.
+         *
+         * @param node - The function declaration node.
+         */
+        function checkFunctionDeclaration(node) {
+            // Only check top-level function declarations (not nested ones)
+            // For arrow/function expressions, they'll be checked via VariableDeclarator
+            if (node.parent.type === "ExportNamedDeclaration" ||
+                node.parent.type === "Program") {
+                checkFunction(node);
+            }
+        }
+
+        return {
+            FunctionDeclaration: checkFunctionDeclaration,
+            VariableDeclarator: checkVariableDeclarator,
+            MethodDefinition: (node) => {
+                if (node.value) checkFunction(node.value);
+            },
+        };
+    },
+};

package/rules/jsdoc-single-line.js

@@ -0,0 +1,44 @@
+/**
+ * Enforce single-line JSDoc comments to use inline format.
+ */
+export default {
+    meta: {
+        type: "layout",
+        docs: {
+            description: "require single-line JSDoc comments to use /** ... */ format instead of multi-line format",
+        },
+        fixable: "whitespace",
+        schema: [],
+    },
+    create: (context) => {
+        const comments = context.sourceCode.getAllComments();
+        return {
+            Program: () => {
+                for (const comment of comments) {
+                    if (comment.type !== "Block" || !comment.value.startsWith("*")) continue;
+
+                    const lines = comment.value.split("\n");
+
+                    // Skip if it's already a single-line comment (doesn't contain newlines in the value)
+                    if (lines.length === 1) continue;
+
+                    // Check if this is a multi-line block that's actually just one line of content
+                    const contentLines = lines
+                        .map((line) => line.trim())
+                        .filter((line) => line !== "*" && line !== "");
+
+                    // If there's only one line of actual content (not counting empty * lines)
+                    if (contentLines.length === 1) {
+                        const content = contentLines[0].replace(/^\*\s*/, "").replace(/\s*$/, "");
+
+                        context.report({
+                            loc: comment.loc,
+                            message: "Single-line JSDoc comments should use inline format: /** ... */",
+                            fix: (fixer) => fixer.replaceTextRange(comment.range, `/** ${content} */`),
+                        });
+                    }
+                }
+            },
+        };
+    },
+};

package/rules/jsx-pascal-case-rule.js

@@ -31,7 +31,7 @@ export const jsxElementRule = {
         }
 
         function isPascalCase(name) {
-            return /^[A-Z][a-zA-Z0-9]*$/.test(name) &&
+            return (/^[A-Z][a-zA-Z0-9]*$/).test(name) &&
                 // allow exceptions for the following names
                 !["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT", "OPTIONS", "TRACE", "PATCH"].includes(name);
         }