eslint-plugin-maintainability 3.0.0

package/src/rules/maintainability/nested-complexity-hotspots.js

@@ -0,0 +1,190 @@
+"use strict";
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nestedComplexityHotspots = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+/**
+ * Calculate nesting depth for a node
+ * Note: Currently unused, keeping for future implementation
+ */
+/*
+function calculateNestingDepth(
+  node: TSESTree.Node,
+  sourceCode: TSESLint.SourceCode
+): number {
+  let depth = 0;
+  let current: TSESTree.Node | null = node;
+  const maxDepth = 20;
+
+  // Start from the node itself and traverse up
+  while (current && depth < maxDepth) {
+    const parent = (current as any).parent;
+
+    if (!parent) break;
+
+    // Count nested control structures
+    if (
+      parent.type === 'IfStatement' ||
+      parent.type === 'ForStatement' ||
+      parent.type === 'ForInStatement' ||
+      parent.type === 'ForOfStatement' ||
+      parent.type === 'WhileStatement' ||
+      parent.type === 'DoWhileStatement' ||
+      parent.type === 'SwitchStatement' ||
+      parent.type === 'TryStatement'
+    ) {
+      depth++;
+    }
+
+    current = parent as TSESTree.Node;
+  }
+
+  return depth;
+}
+*/
+exports.nestedComplexityHotspots = (0, eslint_devkit_2.createRule)({
+    name: 'nested-complexity-hotspots',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Identifies nested control structures that harm readability',
+        },
+        messages: {
+            nestedComplexity: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.COMPLEXITY,
+                issueName: 'Nested complexity hotspot',
+                description: 'Nesting depth {{depth}} exceeds maximum {{max}}',
+                severity: 'MEDIUM',
+                fix: 'Use early returns, guard clauses, or extract methods',
+                documentationLink: 'https://en.wikipedia.org/wiki/Cyclomatic_complexity',
+            }),
+            useEarlyReturn: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Early Return',
+                description: 'Use early return to reduce nesting',
+                severity: 'LOW',
+                fix: 'if (!condition) return; // Continue with main logic',
+                documentationLink: 'https://refactoring.guru/smells/long-method',
+            }),
+            useGuardClauses: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Guard Clauses',
+                description: 'Use guard clauses for validation',
+                severity: 'LOW',
+                fix: 'if (!isValid(input)) throw new Error()',
+                documentationLink: 'https://refactoring.guru/replace-nested-conditional-with-guard-clauses',
+            }),
+            extractMethod: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Extract Method',
+                description: 'Extract nested logic to separate method',
+                severity: 'LOW',
+                fix: 'Extract to private method',
+                documentationLink: 'https://refactoring.guru/extract-method',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    maxDepth: {
+                        type: 'number',
+                        default: 4,
+                        minimum: 1,
+                        description: 'Maximum nesting depth',
+                    },
+                    countConditionals: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Count nested conditionals',
+                    },
+                    countLoops: {
+                        type: 'boolean',
+                        default: true,
+                        description: 'Count nested loops',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            maxDepth: 4,
+            countConditionals: true,
+            countLoops: true,
+        },
+    ],
+    create(context, [options = {}]) {
+        const { maxDepth = 4, countConditionals = true, countLoops = true, } = options || {};
+        // const sourceCode = context.sourceCode || context.sourceCode; // Not used
+        /**
+         * Check control structures
+         */
+        function checkControlStructure(node) {
+            // Count how many control structures are nested above this node
+            let depth = 0;
+            let current = node;
+            const maxDepthCheck = 20;
+            // Start from the node itself and traverse up
+            while (current && depth < maxDepthCheck) {
+                const parent = current
+                    .parent;
+                if (!parent)
+                    break;
+                // Count nested control structures above this node
+                if (parent.type === 'IfStatement' ||
+                    parent.type === 'ForStatement' ||
+                    parent.type === 'ForInStatement' ||
+                    parent.type === 'ForOfStatement' ||
+                    parent.type === 'WhileStatement' ||
+                    parent.type === 'DoWhileStatement' ||
+                    parent.type === 'SwitchStatement' ||
+                    parent.type === 'TryStatement') {
+                    depth++;
+                }
+                current = parent;
+            }
+            // depth now represents how many control structures are nested above this node
+            // For 5 nested ifs, the innermost if will have depth = 4 (4 ifs above it)
+            // So we check if depth >= maxDepth (not >)
+            if (depth >= maxDepth) {
+                context.report({
+                    node,
+                    messageId: 'nestedComplexity',
+                    data: {
+                        depth: String(depth + 1), // +1 to include the current node
+                        max: String(maxDepth),
+                    },
+                    suggest: [
+                        {
+                            messageId: 'useEarlyReturn',
+                            fix: () => null,
+                        },
+                        {
+                            messageId: 'useGuardClauses',
+                            fix: () => null,
+                        },
+                        {
+                            messageId: 'extractMethod',
+                            fix: () => null,
+                        },
+                    ],
+                });
+            }
+        }
+        return {
+            IfStatement: countConditionals ? checkControlStructure : undefined,
+            ForStatement: countLoops ? checkControlStructure : undefined,
+            ForInStatement: countLoops ? checkControlStructure : undefined,
+            ForOfStatement: countLoops ? checkControlStructure : undefined,
+            WhileStatement: countLoops ? checkControlStructure : undefined,
+            SwitchStatement: countConditionals ? checkControlStructure : undefined,
+        };
+    },
+});

package/src/rules/maintainability/no-lonely-if.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * ESLint Rule: no-lonely-if
+ * Prevent lone if statements inside else blocks
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+export interface Options {
+    /** Allow lonely if in specific contexts */
+    allow?: string[];
+}
+type RuleOptions = [Options?];
+export declare const noLonelyIf: TSESLint.RuleModule<"noLonelyIf", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

package/src/rules/maintainability/no-lonely-if.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noLonelyIf = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+exports.noLonelyIf = (0, eslint_devkit_1.createRule)({
+    name: 'no-lonely-if',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prevent lone if statements inside else blocks - use else if instead',
+        },
+        hasSuggestions: true,
+        messages: {
+            noLonelyIf: (0, eslint_devkit_2.formatLLMMessage)({
+                icon: eslint_devkit_2.MessageIcons.WARNING,
+                issueName: 'Lonely If',
+                description: 'Unexpected if statement inside else block',
+                severity: 'MEDIUM',
+                fix: 'Replace with else if for better readability',
+                documentationLink: 'https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-lonely-if.md',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ allow: [] }],
+    create(context) {
+        const [options] = context.options;
+        const { allow = [] } = options || {};
+        const allowedContexts = new Set(allow);
+        function isInAllowedContext() {
+            // Check if we're in an allowed context
+            // This is a simple implementation - could be extended for more complex cases
+            for (const allowedContext of allowedContexts) {
+                // For now, just check if the context string appears anywhere in the source
+                const sourceCode = context.sourceCode;
+                const sourceText = sourceCode.getText();
+                if (sourceText.includes(allowedContext)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        function isLonelyIf(node) {
+            // Check if this if statement is inside an else block (not a proper else if)
+            const parent = node.parent;
+            // If parent is a BlockStatement, check if that block is an else block
+            if (parent?.type === 'BlockStatement') {
+                const grandParent = parent.parent;
+                // Check if the block is the alternate (else) of an if statement
+                return (grandParent?.type === 'IfStatement' &&
+                    grandParent.alternate === parent);
+            }
+            // If not in a block, it's not a lonely if (it's either a proper else if or top-level)
+            return false;
+        }
+        return {
+            IfStatement(node) {
+                if (isLonelyIf(node) && !isInAllowedContext()) {
+                    context.report({
+                        node,
+                        messageId: 'noLonelyIf',
+                        data: {
+                            current: 'if statement in else block',
+                            fix: 'else if',
+                        },
+                        suggest: [
+                            {
+                                messageId: 'noLonelyIf',
+                                fix(fixer) {
+                                    const sourceCode = context.sourceCode;
+                                    // Find the else keyword
+                                    let elseToken = null;
+                                    const tokens = sourceCode.getTokensBefore(node, 10);
+                                    for (let i = tokens.length - 1; i >= 0; i--) {
+                                        if (tokens[i].value === 'else') {
+                                            elseToken = tokens[i];
+                                            break;
+                                        }
+                                    }
+                                    if (elseToken) {
+                                        // Remove 'else' and replace 'if' with 'else if'
+                                        const ifToken = sourceCode.getTokenAfter(elseToken);
+                                        if (ifToken && ifToken.value === 'if') {
+                                            return [
+                                                fixer.removeRange([
+                                                    elseToken.range[0],
+                                                    ifToken.range[1],
+                                                ]),
+                                                fixer.insertTextBefore(ifToken, 'else '),
+                                            ];
+                                        }
+                                    }
+                                    return null;
+                                },
+                            },
+                        ],
+                    });
+                }
+            },
+        };
+    },
+});

package/src/rules/maintainability/no-nested-ternary.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * ESLint Rule: no-nested-ternary
+ * Prevent nested ternary expressions
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+export interface Options {
+    /** Allow nested ternaries in specific contexts */
+    allow?: string[];
+}
+type RuleOptions = [Options?];
+export declare const noNestedTernary: TSESLint.RuleModule<"noNestedTernary", RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

package/src/rules/maintainability/no-nested-ternary.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noNestedTernary = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+exports.noNestedTernary = (0, eslint_devkit_1.createRule)({
+    name: 'no-nested-ternary',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Prevent nested ternary expressions for better readability',
+        },
+        hasSuggestions: true,
+        messages: {
+            noNestedTernary: (0, eslint_devkit_2.formatLLMMessage)({
+                icon: eslint_devkit_2.MessageIcons.WARNING,
+                issueName: 'Nested Ternary',
+                description: 'Avoid nested ternary expressions',
+                severity: 'MEDIUM',
+                fix: 'Extract to helper variable or use if-else',
+                documentationLink: 'https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/no-nested-ternary.md',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    allow: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        default: [],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ allow: [] }],
+    create(context) {
+        const [options] = context.options;
+        const { allow = [] } = options || {};
+        /**
+         * Check if node is in an allowed context based on the allow option.
+         * Supported contexts:
+         * - 'jsx': Allow nested ternaries in JSX expressions
+         * - 'variable': Allow nested ternaries in variable declarations
+         * - 'return': Allow nested ternaries in return statements
+         * - 'argument': Allow nested ternaries in function arguments
+         */
+        function isInAllowedContext(node) {
+            if (allow.length === 0) {
+                return false;
+            }
+            let current = node.parent;
+            while (current) {
+                // Check for JSX context
+                if (allow.includes('jsx') &&
+                    (current.type === 'JSXExpressionContainer' ||
+                        current.type === 'JSXElement' ||
+                        current.type === 'JSXFragment')) {
+                    return true;
+                }
+                // Check for variable declaration context
+                if (allow.includes('variable') &&
+                    current.type === 'VariableDeclarator') {
+                    return true;
+                }
+                // Check for return statement context
+                if (allow.includes('return') && current.type === 'ReturnStatement') {
+                    return true;
+                }
+                // Check for function argument context
+                if (allow.includes('argument') && current.type === 'CallExpression') {
+                    return true;
+                }
+                current = current.parent;
+            }
+            return false;
+        }
+        function hasNestedTernary(node) {
+            // Check if the consequent or alternate contains another ternary
+            function containsTernary(expr) {
+                if (expr.type === 'ConditionalExpression') {
+                    return true;
+                }
+                // For other expression types, check their child expressions
+                switch (expr.type) {
+                    case 'ArrayExpression':
+                        return expr.elements.some((element) => element &&
+                            element.type !== 'SpreadElement' &&
+                            containsTernary(element));
+                    case 'ObjectExpression':
+                        return expr.properties.some((prop) => prop.type === 'Property' &&
+                            prop.value &&
+                            containsTernary(prop.value));
+                    case 'CallExpression':
+                        return (expr.arguments.some((arg) => arg.type !== 'SpreadElement' && containsTernary(arg)) ||
+                            (expr.callee.type !== 'Super' && containsTernary(expr.callee)));
+                    case 'MemberExpression':
+                        return (containsTernary(expr.object) ||
+                            (expr.property.type !== 'Identifier' &&
+                                expr.property.type !== 'PrivateIdentifier' &&
+                                containsTernary(expr.property)));
+                    case 'BinaryExpression':
+                    case 'LogicalExpression':
+                        return containsTernary(expr.left) || containsTernary(expr.right);
+                    case 'UnaryExpression':
+                    case 'UpdateExpression':
+                        return containsTernary(expr.argument);
+                    case 'AssignmentExpression':
+                        return containsTernary(expr.right);
+                    // For literals and identifiers, no nested expressions
+                    case 'Literal':
+                    case 'Identifier':
+                    case 'ThisExpression':
+                    case 'Super':
+                    case 'MetaProperty':
+                        return false;
+                    // For template literals, check expressions
+                    case 'TemplateLiteral':
+                        return expr.expressions.some((exp) => containsTernary(exp));
+                    // For tagged templates, check tag and expressions
+                    case 'TaggedTemplateExpression':
+                        return (containsTernary(expr.tag) ||
+                            expr.quasi.expressions.some((exp) => containsTernary(exp)));
+                    // Default: assume no nested expressions for unknown types
+                    default:
+                        return false;
+                }
+            }
+            return (containsTernary(node.consequent) || containsTernary(node.alternate));
+        }
+        return {
+            ConditionalExpression(node) {
+                if (hasNestedTernary(node) && !isInAllowedContext(node)) {
+                    context.report({
+                        node,
+                        messageId: 'noNestedTernary',
+                        data: {
+                            current: 'nested ternary expression',
+                            fix: 'extract or use if-else',
+                        },
+                        suggest: [
+                            {
+                                messageId: 'noNestedTernary',
+                                fix() {
+                                    // This is a complex fix that would require:
+                                    // 1. Extracting the nested ternary to a variable
+                                    // 2. Replacing the nested part
+                                    // For now, just provide the suggestion
+                                    return null;
+                                },
+                            },
+                        ],
+                    });
+                }
+            },
+        };
+    },
+});

package/src/rules/maintainability/no-unreadable-iife.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 Ofri Peretz
+ * Licensed under the MIT License. Use of this source code is governed by the
+ * MIT license that can be found in the LICENSE file.
+ */
+/**
+ * ESLint Rule: no-unreadable-iife
+ * Prevent unreadable Immediately Invoked Function Expressions (unicorn-inspired)
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'unreadableIIFE' | 'suggestNamedFunction' | 'suggestBlockScope' | 'complexIIFE';
+export interface Options {
+    /** Maximum number of statements allowed in IIFE */
+    maxStatements?: number;
+    /** Maximum depth of nesting allowed in IIFE */
+    maxDepth?: number;
+    /** Allow IIFEs that return values */
+    allowReturningIIFE?: boolean;
+}
+type RuleOptions = [Options?];
+export declare const noUnreadableIife: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};