eslint-plugin-maintainability 3.0.0

package/src/rules/maintainability/cognitive-complexity.js

@@ -0,0 +1,381 @@
+"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.cognitiveComplexity = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+const eslint_devkit_3 = require("@interlace/eslint-devkit");
+exports.cognitiveComplexity = (0, eslint_devkit_2.createRule)({
+    name: 'cognitive-complexity',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Enforces a maximum cognitive complexity threshold with refactoring guidance',
+        },
+        messages: {
+            // 🎯 Token optimization: 40% reduction (60→36 tokens) - keeps complexity metrics inline
+            highCognitiveComplexity: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.COMPLEXITY,
+                issueName: 'High cognitive complexity',
+                cwe: 'CWE-1104',
+                description: '{{functionName}}: {{complexity}}/{{max}} ({{overBy}} over)',
+                severity: 'HIGH',
+                fix: 'Extract logic to helpers',
+                documentationLink: 'https://en.wikipedia.org/wiki/Cognitive_complexity',
+            }),
+            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 "{{methodName}}" (reduces complexity by ~{{reduction}})',
+                documentationLink: 'https://refactoring.guru/extract-method',
+            }),
+            simplifyLogic: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Simplify Logic',
+                description: 'Simplify conditional logic',
+                severity: 'LOW',
+                fix: 'Use guard clauses and early returns',
+                documentationLink: 'https://refactoring.guru/replace-nested-conditional-with-guard-clauses',
+            }),
+            useStrategy: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Strategy Pattern',
+                description: 'Apply design pattern to reduce complexity',
+                severity: 'LOW',
+                fix: 'Apply {{pattern}} pattern',
+                documentationLink: 'https://refactoring.guru/design-patterns/strategy',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    maxComplexity: {
+                        type: 'number',
+                        default: 15,
+                        minimum: 1,
+                    },
+                    includeMetrics: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            maxComplexity: 15,
+            includeMetrics: true,
+        },
+    ],
+    create(context) {
+        const options = context.options[0] || {};
+        const { maxComplexity = 15 } = options || {};
+        const filename = context.filename || context.getFilename();
+        /**
+         * Calculate cognitive complexity for a function
+         * Based on SonarQube's cognitive complexity algorithm
+         */
+        function calculateCognitiveComplexity(node) {
+            let complexity = 0;
+            const breakdown = {
+                conditionals: 0,
+                loops: 0,
+                switches: 0,
+                nesting: 0,
+                logicalOperators: 0,
+                catches: 0,
+                recursion: 0,
+            };
+            const functionName = node.type === 'FunctionDeclaration' && node.id
+                ? node.id.name
+                : 'anonymous';
+            function traverse(n, currentNesting) {
+                // Increment for conditionals
+                if (n.type === 'IfStatement') {
+                    complexity += 1 + currentNesting;
+                    breakdown.conditionals++;
+                    // Traverse the test condition to count logical operators
+                    traverse(n.test, currentNesting);
+                    traverse(n.consequent, currentNesting + 1);
+                    if (n.alternate) {
+                        if (n.alternate.type === 'IfStatement') {
+                            // else if doesn't increase nesting
+                            traverse(n.alternate, currentNesting);
+                        }
+                        else {
+                            // else increases nesting
+                            complexity += 1;
+                            traverse(n.alternate, currentNesting + 1);
+                        }
+                    }
+                    return;
+                }
+                // Loops
+                if (n.type === 'ForStatement' ||
+                    n.type === 'ForInStatement' ||
+                    n.type === 'ForOfStatement' ||
+                    n.type === 'WhileStatement' ||
+                    n.type === 'DoWhileStatement') {
+                    complexity += 1 + currentNesting;
+                    breakdown.loops++;
+                    if (n.type === 'ForStatement') {
+                        if (n.init)
+                            traverse(n.init, currentNesting);
+                        if (n.test)
+                            traverse(n.test, currentNesting);
+                        if (n.update)
+                            traverse(n.update, currentNesting);
+                        traverse(n.body, currentNesting + 1);
+                    }
+                    else if (n.type === 'WhileStatement' ||
+                        n.type === 'DoWhileStatement') {
+                        traverse(n.test, currentNesting);
+                        traverse(n.body, currentNesting + 1);
+                    }
+                    else {
+                        if ('left' in n)
+                            traverse(n.left, currentNesting);
+                        if ('right' in n)
+                            traverse(n.right, currentNesting);
+                        traverse(n.body, currentNesting + 1);
+                    }
+                    return;
+                }
+                // Switch
+                if (n.type === 'SwitchStatement') {
+                    complexity += 1 + currentNesting;
+                    breakdown.switches++;
+                    traverse(n.discriminant, currentNesting);
+                    n.cases.forEach((c) => traverse(c, currentNesting + 1));
+                    return;
+                }
+                // Logical operators (short-circuiting)
+                if (n.type === 'LogicalExpression') {
+                    if (n.operator === '&&' ||
+                        n.operator === '||' ||
+                        n.operator === '??') {
+                        complexity += 1;
+                        breakdown.logicalOperators++;
+                    }
+                }
+                // Catch clauses
+                if (n.type === 'CatchClause') {
+                    complexity += 1 + currentNesting;
+                    breakdown.catches++;
+                    traverse(n.body, currentNesting + 1);
+                    return;
+                }
+                // Ternary operators
+                if (n.type === 'ConditionalExpression') {
+                    complexity += 1 + currentNesting;
+                    breakdown.conditionals++;
+                }
+                // Recursion
+                if (n.type === 'CallExpression') {
+                    if (n.callee.type === 'Identifier' &&
+                        n.callee.name === functionName) {
+                        complexity += 1;
+                        breakdown.recursion++;
+                    }
+                }
+                // Update max nesting
+                if (n.type === 'BlockStatement' ||
+                    n.type === 'FunctionDeclaration' ||
+                    n.type === 'FunctionExpression' ||
+                    n.type === 'ArrowFunctionExpression') {
+                    breakdown.nesting = Math.max(breakdown.nesting, currentNesting);
+                }
+                /**
+                 * Traverse children - use a visited set to prevent infinite recursion
+                 * Only traverse specific AST child properties, not all object properties
+                 */
+                const visited = new Set();
+                function traverseChild(child) {
+                    if (child && typeof child === 'object' && 'type' in child) {
+                        const childNode = child;
+                        if (!visited.has(childNode)) {
+                            visited.add(childNode);
+                            traverse(childNode, currentNesting);
+                        }
+                    }
+                }
+                // Known child properties based on ESTree spec
+                const childKeys = [
+                    'body',
+                    'test',
+                    'consequent',
+                    'alternate',
+                    'init',
+                    'update',
+                    'left',
+                    'right',
+                    'argument',
+                    'arguments',
+                    'callee',
+                    'object',
+                    'property',
+                    'elements',
+                    'properties',
+                    'expression',
+                    'expressions',
+                    'declarations',
+                    'declaration',
+                    'specifiers',
+                    'source',
+                    'key',
+                    'value',
+                    'handler',
+                    'block',
+                    'finalizer',
+                ]; // handler for TryStatement.catch, block/finalizer for TryStatement
+                for (const key of childKeys) {
+                    const child = n[key];
+                    if (child) {
+                        if (Array.isArray(child)) {
+                            child.forEach(traverseChild);
+                        }
+                        else {
+                            traverseChild(child);
+                        }
+                    }
+                }
+            }
+            if (node.body) {
+                traverse(node.body, 0);
+            }
+            return { total: complexity, breakdown };
+        }
+        /**
+         * Analyze function and suggest extractions
+         */
+        function suggestExtractions(node, breakdown) {
+            const suggestions = [];
+            // Suggest extracting deeply nested logic
+            if (breakdown.nesting >= 4 && node.loc) {
+                suggestions.push({
+                    name: 'extractNestedLogic',
+                    reason: `Nesting depth of ${breakdown.nesting} makes code hard to follow`,
+                    lineRange: [node.loc.start.line, node.loc.end.line],
+                    estimatedComplexityReduction: Math.floor(breakdown.nesting * 1.5),
+                });
+            }
+            // Suggest extracting switch/case logic
+            if (breakdown.switches >= 2 && node.loc) {
+                suggestions.push({
+                    name: 'refactorSwitchToStrategy',
+                    reason: `${breakdown.switches} switch statements suggest strategy pattern`,
+                    lineRange: [node.loc.start.line, node.loc.end.line],
+                    estimatedComplexityReduction: breakdown.switches * 2,
+                });
+            }
+            // Suggest extracting loop logic
+            if (breakdown.loops >= 3 && node.loc) {
+                suggestions.push({
+                    name: 'extractLoopLogic',
+                    reason: `${breakdown.loops} loops can be extracted to separate methods`,
+                    lineRange: [node.loc.start.line, node.loc.end.line],
+                    estimatedComplexityReduction: breakdown.loops * 2,
+                });
+            }
+            // Suggest simplifying conditionals
+            if (breakdown.conditionals >= 5 && node.loc) {
+                suggestions.push({
+                    name: 'simplifyConditionals',
+                    reason: `${breakdown.conditionals} conditional branches could use Guard Clauses`,
+                    lineRange: [node.loc.start.line, node.loc.end.line],
+                    estimatedComplexityReduction: Math.floor(breakdown.conditionals * 0.8),
+                });
+            }
+            return suggestions;
+        }
+        /**
+         * Suggest architectural patterns
+         */
+        function suggestPattern(breakdown) {
+            if (breakdown.switches >= 2)
+                return 'Strategy Pattern';
+            if (breakdown.conditionals >= 5)
+                return 'Guard Clauses + Early Return';
+            if (breakdown.loops >= 3)
+                return 'Extract Method + Pipeline';
+            if (breakdown.nesting >= 4)
+                return 'Extract Method + Composed Functions';
+            return 'Extract Method';
+        }
+        /**
+         * Calculate estimated refactoring time
+         */
+        function estimateRefactoringTime(complexity, breakdown) {
+            const baseTime = Math.floor((complexity - maxComplexity) * 3); // 3 minutes per point
+            const nestingPenalty = breakdown.nesting >= 4 ? 15 : 0;
+            const totalMinutes = baseTime + nestingPenalty;
+            if (totalMinutes < 30)
+                return `${totalMinutes} minutes`;
+            if (totalMinutes < 60)
+                return '30-60 minutes';
+            return `${Math.ceil(totalMinutes / 60)} hours`;
+        }
+        /**
+         * Check function complexity
+         */
+        function checkFunction(node) {
+            const { total: complexity, breakdown } = calculateCognitiveComplexity(node);
+            if (complexity <= maxComplexity)
+                return;
+            const functionSignature = (0, eslint_devkit_3.extractFunctionSignature)(node);
+            const suggestions = suggestExtractions(node, breakdown);
+            const pattern = suggestPattern(breakdown);
+            const estimatedTime = estimateRefactoringTime(complexity, breakdown);
+            context.report({
+                node,
+                messageId: 'highCognitiveComplexity',
+                data: {
+                    functionName: functionSignature,
+                    complexity: String(complexity),
+                    max: String(maxComplexity),
+                    overBy: String(complexity - maxComplexity),
+                    current: String(complexity),
+                    filePath: filename,
+                    line: String(node.loc?.start.line ?? 0),
+                    conditionals: String(breakdown.conditionals),
+                    loops: String(breakdown.loops),
+                    nesting: String(breakdown.nesting),
+                    pattern,
+                    estimatedTime,
+                },
+                suggest: suggestions.length > 0
+                    ? suggestions.map((suggestion, index) => {
+                        const messageId = index === 0
+                            ? 'extractMethod'
+                            : index === 1
+                                ? 'useStrategy'
+                                : 'simplifyLogic';
+                        return {
+                            messageId,
+                            data: {
+                                methodName: suggestion.name,
+                                pattern,
+                                reduction: String(suggestion.estimatedComplexityReduction),
+                            },
+                            fix: () => null, // Complex refactoring, cannot auto-fix
+                        };
+                    })
+                    : undefined,
+            });
+        }
+        return {
+            FunctionDeclaration: checkFunction,
+            FunctionExpression: checkFunction,
+            ArrowFunctionExpression: checkFunction,
+        };
+    },
+});

package/src/rules/maintainability/consistent-function-scoping.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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: consistent-function-scoping
+ * Disallow functions that are declared in a scope which does not capture any variables from the outer scope
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'inconsistentFunctionScoping' | 'moveToModuleScope';
+export interface Options {
+    /** Check arrow functions for scoping issues */
+    checkArrowFunctions?: boolean;
+}
+type RuleOptions = [Options?];
+export declare const consistentFunctionScoping: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

package/src/rules/maintainability/consistent-function-scoping.js

@@ -0,0 +1,226 @@
+"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.consistentFunctionScoping = void 0;
+const eslint_devkit_1 = require("@interlace/eslint-devkit");
+const eslint_devkit_2 = require("@interlace/eslint-devkit");
+exports.consistentFunctionScoping = (0, eslint_devkit_1.createRule)({
+    name: 'consistent-function-scoping',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Move function definitions to the highest possible scope to improve readability and performance',
+        },
+        hasSuggestions: true,
+        messages: {
+            inconsistentFunctionScoping: (0, eslint_devkit_2.formatLLMMessage)({
+                icon: eslint_devkit_2.MessageIcons.ARCHITECTURE,
+                issueName: 'Inconsistent Function Scoping',
+                description: 'Function can be moved to higher scope as it doesn\'t capture outer variables',
+                severity: 'MEDIUM',
+                fix: 'Move function declaration to module scope',
+                documentationLink: 'https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/consistent-function-scoping.md',
+            }),
+            moveToModuleScope: (0, eslint_devkit_2.formatLLMMessage)({
+                icon: eslint_devkit_2.MessageIcons.ARCHITECTURE,
+                issueName: 'Function Scoping Optimization',
+                description: 'Function does not use variables from its containing scope and can be moved to module level',
+                severity: 'MEDIUM',
+                fix: 'Move function outside current scope: extract `function helper() { return "value"; }` to module level before the containing function/class',
+                documentationLink: 'https://github.com/sindresorhus/eslint-plugin-unicorn/blob/main/docs/rules/consistent-function-scoping.md',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    checkArrowFunctions: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [{ checkArrowFunctions: true }],
+    create(context) {
+        const [options] = context.options;
+        const { checkArrowFunctions = true } = options || {};
+        // Track variables declared in each scope
+        const scopeStack = [new Set()];
+        function enterScope() {
+            scopeStack.push(new Set());
+        }
+        function exitScope() {
+            scopeStack.pop();
+        }
+        function addVariableToCurrentScope(name) {
+            const currentScope = scopeStack[scopeStack.length - 1];
+            if (currentScope) {
+                currentScope.add(name);
+            }
+        }
+        function getOuterScopeVariables() {
+            const outerScopes = scopeStack.slice(0, -1);
+            const outerVars = new Set();
+            for (const scope of outerScopes) {
+                for (const varName of scope) {
+                    outerVars.add(varName);
+                }
+            }
+            return outerVars;
+        }
+        function analyzeFunction(node) {
+            // Skip module-level functions (direct children of Program or ExportNamedDeclaration)
+            if (node.parent?.type === 'Program' || node.parent?.type === 'ExportNamedDeclaration' || node.parent?.type === 'ExportDefaultDeclaration') {
+                return;
+            }
+            // Get all variables referenced in the function body
+            const referencedVars = new Set();
+            function collectReferences(node, depth = 0, visited = new Set()) {
+                // Prevent infinite recursion
+                if (depth > 10 || visited.has(node)) {
+                    return;
+                }
+                visited.add(node);
+                if (node.type === 'Identifier') {
+                    referencedVars.add(node.name);
+                }
+                // Recursively check all child nodes with depth limit
+                if (depth < 10) {
+                    for (const key in node) {
+                        const child = node[key];
+                        if (child && typeof child === 'object') {
+                            if (Array.isArray(child)) {
+                                child.forEach(item => {
+                                    if (item && typeof item === 'object' && 'type' in item) {
+                                        collectReferences(item, depth + 1, visited);
+                                    }
+                                });
+                            }
+                            else if ('type' in child && typeof child === 'object' && child !== null) {
+                                collectReferences(child, depth + 1, visited);
+                            }
+                        }
+                    }
+                }
+            }
+            // Collect all references in the function body
+            if (node.body.type === 'BlockStatement') {
+                node.body.body.forEach((stmt) => collectReferences(stmt));
+            }
+            else {
+                // Arrow function with expression body
+                collectReferences(node.body);
+            }
+            // Check function parameters
+            node.params.forEach((param) => {
+                if (param.type === 'Identifier') {
+                    referencedVars.add(param.name);
+                }
+            });
+            // Get variables from outer scopes
+            const outerVars = getOuterScopeVariables();
+            // Check if function captures any outer variables
+            let capturesOuterVar = false;
+            for (const ref of referencedVars) {
+                if (outerVars.has(ref)) {
+                    capturesOuterVar = true;
+                    break;
+                }
+            }
+            // If function doesn't capture any outer variables, it can be moved up
+            if (!capturesOuterVar) {
+                // Additional check: ensure function name doesn't conflict at module scope
+                const functionName = node.type === 'FunctionDeclaration' ? node.id?.name : undefined;
+                const moduleScope = scopeStack[0];
+                if (!functionName || !moduleScope.has(functionName)) {
+                    context.report({
+                        node,
+                        messageId: 'inconsistentFunctionScoping',
+                        data: {
+                            functionName: functionName || 'anonymous function',
+                        },
+                        suggest: [
+                            {
+                                messageId: 'moveToModuleScope',
+                                fix(fixer) {
+                                    // This is a complex fix that would require:
+                                    // 1. Finding the module scope location
+                                    // 2. Moving the function declaration33 3
+                                    // 3. Updating any references
+                                    // For now, just provide a suggestion
+                                    return fixer.insertTextBefore(node, '// TODO: Move this function to module scope - it doesn\'t capture outer variables\n');
+                                },
+                            },
+                        ],
+                    });
+                }
+            }
+        }
+        return {
+            Program() {
+                enterScope();
+            },
+            'Program:exit'() {
+                exitScope();
+            },
+            FunctionDeclaration(node) {
+                enterScope();
+                // Add function parameters to the current scope
+                node.params.forEach((param) => {
+                    if (param.type === 'Identifier') {
+                        addVariableToCurrentScope(param.name);
+                    }
+                });
+                analyzeFunction(node);
+            },
+            'FunctionDeclaration:exit'() {
+                exitScope();
+            },
+            FunctionExpression(node) {
+                enterScope();
+                // Add function parameters to the current scope
+                node.params.forEach((param) => {
+                    if (param.type === 'Identifier') {
+                        addVariableToCurrentScope(param.name);
+                    }
+                });
+                // Only check function expressions if they are assigned to variables
+                // (not just used as callbacks)
+                analyzeFunction(node);
+            },
+            'FunctionExpression:exit'() {
+                exitScope();
+            },
+            ArrowFunctionExpression(node) {
+                enterScope();
+                // Add function parameters to the current scope
+                node.params.forEach((param) => {
+                    if (param.type === 'Identifier') {
+                        addVariableToCurrentScope(param.name);
+                    }
+                });
+                if (checkArrowFunctions) {
+                    analyzeFunction(node);
+                }
+            },
+            'ArrowFunctionExpression:exit'() {
+                exitScope();
+            },
+            VariableDeclaration(node) {
+                // Add variables to current scope
+                node.declarations.forEach((decl) => {
+                    if (decl.id.type === 'Identifier') {
+                        addVariableToCurrentScope(decl.id.name);
+                    }
+                });
+            },
+        };
+    },
+});

package/src/rules/maintainability/identical-functions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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: identical-functions
+ * Detects functions with identical implementations and suggests DRY refactoring
+ * Inspired by SonarQube RSPEC-4144
+ *
+ * @see https://rules.sonarsource.com/javascript/RSPEC-4144/
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'identicalFunctions' | 'extractGeneric' | 'useHigherOrder' | 'applyInheritance';
+export interface Options {
+    /** Minimum lines to consider for duplicate detection. Default: 3 */
+    minLines?: number;
+    /** Similarity percentage threshold (0-100). Default: 90 */
+    similarityThreshold?: number;
+    /** Ignore test files. Default: false */
+    ignoreTestFiles?: boolean;
+}
+type RuleOptions = [Options?];
+export declare const identicalFunctions: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};