eslint-plugin-maintainability 3.0.0

package/src/rules/maintainability/identical-functions.js

@@ -0,0 +1,310 @@
+"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.identicalFunctions = 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.identicalFunctions = (0, eslint_devkit_2.createRule)({
+    name: 'identical-functions',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Detects duplicate function implementations with DRY refactoring suggestions',
+        },
+        messages: {
+            // 🎯 Token optimization: 43% reduction (56→32 tokens) - DRY principle violation detected
+            identicalFunctions: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.DUPLICATION,
+                issueName: 'Code duplication',
+                description: '{{count}} duplicates ({{similarity}}% similar)',
+                severity: 'MEDIUM',
+                fix: 'Extract to reusable function',
+                documentationLink: 'https://en.wikipedia.org/wiki/Don%27t_repeat_yourself',
+            }),
+            extractGeneric: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Extract Generic',
+                description: 'Extract to generic function',
+                severity: 'LOW',
+                fix: 'Create shared function with parameters',
+                documentationLink: 'https://en.wikipedia.org/wiki/Don%27t_repeat_yourself',
+            }),
+            useHigherOrder: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Higher-Order',
+                description: 'Use higher-order function pattern',
+                severity: 'LOW',
+                fix: 'Create factory function that returns specialized functions',
+                documentationLink: 'https://developer.mozilla.org/en-US/docs/Glossary/Higher-order_function',
+            }),
+            applyInheritance: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Composition',
+                description: 'Use inheritance/composition',
+                severity: 'LOW',
+                fix: 'Extract common behavior to base class or mixin',
+                documentationLink: 'https://en.wikipedia.org/wiki/Composition_over_inheritance',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    minLines: {
+                        type: 'number',
+                        default: 3,
+                        minimum: 1,
+                        description: 'Minimum lines to consider for duplication',
+                    },
+                    similarityThreshold: {
+                        type: 'number',
+                        default: 0.9,
+                        minimum: 0.5,
+                        maximum: 1,
+                        description: 'Similarity threshold (0.5-1.0)',
+                    },
+                    ignoreTestFiles: {
+                        type: 'boolean',
+                        default: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            minLines: 3,
+            similarityThreshold: 0.9,
+            ignoreTestFiles: true,
+        },
+    ],
+    create(context) {
+        const options = context.options[0] || {};
+        const { minLines = 3, similarityThreshold = 0.9, ignoreTestFiles = true, } = options || {};
+        const sourceCode = context.sourceCode || context.sourceCode;
+        const filename = context.filename || context.getFilename();
+        // Skip test files if configured
+        if (ignoreTestFiles && /\.(test|spec)\.[jt]sx?$/.test(filename)) {
+            return {};
+        }
+        const functions = [];
+        /**
+         * Normalize function body for comparison
+         * Remove variable names, keep structure
+         */
+        function normalizeBody(body) {
+            return (body
+                // Remove whitespace
+                .replace(/\s+/g, ' ')
+                // Normalize string quotes
+                .replace(/["'`]/g, '"')
+                // Normalize variable names to generic identifiers
+                .replace(/\b[a-z_$][a-zA-Z0-9_$]*\b/g, 'VAR')
+                // Remove comments
+                .replace(/\/\*[\s\S]*?\*\//g, '')
+                .replace(/\/\/.*/g, '')
+                .trim());
+        }
+        /**
+         * Calculate similarity between two normalized strings
+         * Using Levenshtein distance ratio
+         */
+        function calculateSimilarity(str1, str2) {
+            if (str1 === str2)
+                return 1.0;
+            const longer = str1.length > str2.length ? str1 : str2;
+            const shorter = str1.length > str2.length ? str2 : str1;
+            if (longer.length === 0)
+                return 1.0;
+            const editDistance = levenshteinDistance(longer, shorter);
+            return (longer.length - editDistance) / longer.length;
+        }
+        /**
+         * Levenshtein distance algorithm
+         */
+        function levenshteinDistance(str1, str2) {
+            const matrix = [];
+            for (let i = 0; i <= str2.length; i++) {
+                matrix[i] = [i];
+            }
+            for (let j = 0; j <= str1.length; j++) {
+                matrix[0][j] = j;
+            }
+            for (let i = 1; i <= str2.length; i++) {
+                for (let j = 1; j <= str1.length; j++) {
+                    if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
+                        matrix[i][j] = matrix[i - 1][j - 1];
+                    }
+                    else {
+                        matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j] + 1);
+                    }
+                }
+            }
+            return matrix[str2.length][str1.length];
+        }
+        /**
+         * Find groups of similar functions
+         */
+        function findDuplicationGroups() {
+            const groups = [];
+            const processed = new Set();
+            for (let i = 0; i < functions.length; i++) {
+                if (processed.has(i))
+                    continue;
+                const group = [functions[i]];
+                processed.add(i);
+                for (let j = i + 1; j < functions.length; j++) {
+                    if (processed.has(j))
+                        continue;
+                    const similarity = calculateSimilarity(functions[i].normalizedBody, functions[j].normalizedBody);
+                    if (similarity >= similarityThreshold) {
+                        group.push(functions[j]);
+                        processed.add(j);
+                    }
+                }
+                if (group.length >= 2) {
+                    const avgSimilarity = group.reduce((sum, func, idx) => {
+                        if (idx === 0)
+                            return 0;
+                        return (sum +
+                            calculateSimilarity(group[0].normalizedBody, func.normalizedBody));
+                    }, 0) /
+                        (group.length - 1);
+                    groups.push({
+                        functions: group,
+                        similarityScore: avgSimilarity,
+                        commonPattern: functions[i].normalizedBody,
+                    });
+                }
+            }
+            return groups;
+        }
+        /**
+         * Generate unified function suggestion
+         */
+        function generateUnifiedFunction(group) {
+            const firstFunc = group.functions[0];
+            // Analyze parameter differences
+            const allParams = new Set();
+            group.functions.forEach((func) => func.params.forEach((p) => allParams.add(p)));
+            // Generate generic function name
+            const baseName = firstFunc.name.replace(/^(handle|process|get|set|create|update|delete)/, '');
+            const genericName = `handle${baseName || 'Generic'}`;
+            // If functions differ only in constant values, extract as parameter
+            const paramList = Array.from(allParams);
+            if (paramList.length > firstFunc.params.length) {
+                paramList.push('options');
+            }
+            return `function ${genericName}(${paramList.join(', ')}) {\n  ${firstFunc.body.trim()}\n}`;
+        }
+        /**
+         * Suggest refactoring approach
+         */
+        function suggestRefactoringApproach(group) {
+            const funcNames = group.functions.map((f) => f.name);
+            const hasRolePattern = funcNames.some((name) => /user|admin|guest|customer/i.test(name));
+            const hasTypePattern = funcNames.some((name) => /payment|shipping|billing|email|sms/i.test(name));
+            if (hasRolePattern || hasTypePattern) {
+                return {
+                    approach: 'Parameter Object + Strategy Pattern',
+                    pattern: 'Extract discriminator as parameter',
+                    complexity: 'moderate',
+                };
+            }
+            if (group.functions[0].params.length > 0) {
+                return {
+                    approach: 'Higher-Order Function',
+                    pattern: 'Extract common logic, inject differences',
+                    complexity: 'simple',
+                };
+            }
+            return {
+                approach: 'Extract Method',
+                pattern: 'DRY - Single source of truth',
+                complexity: 'simple',
+            };
+        }
+        /**
+         * Store function information
+         */
+        function storeFunctionInfo(node) {
+            const body = node.body ? sourceCode.getText(node.body) : '';
+            const lines = body.split('\n').length;
+            if (lines < minLines)
+                return;
+            const name = (0, eslint_devkit_3.extractFunctionSignature)(node)
+                .split('(')[0]
+                .replace('function ', '');
+            const params = node.params.map((p) => p.type === 'Identifier' ? p.name : sourceCode.getText(p));
+            functions.push({
+                node,
+                name: name || 'anonymous',
+                body,
+                normalizedBody: normalizeBody(body),
+                lines,
+                location: `${filename}:${node.loc?.start.line}`,
+                params,
+            });
+        }
+        /**
+         * Report duplications after analyzing all functions
+         */
+        function reportDuplications() {
+            const groups = findDuplicationGroups();
+            groups.forEach((group) => {
+                const refactoringApproach = suggestRefactoringApproach(group);
+                const unifiedFunction = generateUnifiedFunction(group);
+                const primaryFunction = group.functions[0];
+                const similarityPercent = Math.round(group.similarityScore * 100);
+                context.report({
+                    node: primaryFunction.node,
+                    messageId: 'identicalFunctions',
+                    data: {
+                        count: String(group.functions.length),
+                        similarity: String(similarityPercent),
+                        filePath: filename,
+                        line: String(primaryFunction.node.loc?.start.line ?? 0),
+                    },
+                    suggest: [
+                        {
+                            messageId: 'extractGeneric',
+                            data: {
+                                functionName: unifiedFunction.match(/function (\w+)/)?.[1] ||
+                                    'handleGeneric',
+                            },
+                            fix: () => null,
+                        },
+                        ...(refactoringApproach.approach.includes('Higher-Order')
+                            ? [
+                                {
+                                    messageId: 'useHigherOrder',
+                                    fix: () => null,
+                                },
+                            ]
+                            : []),
+                        ...(refactoringApproach.approach.includes('Strategy')
+                            ? [
+                                {
+                                    messageId: 'applyInheritance',
+                                    fix: () => null,
+                                },
+                            ]
+                            : []),
+                    ],
+                });
+            });
+        }
+        return {
+            FunctionDeclaration: storeFunctionInfo,
+            FunctionExpression: storeFunctionInfo,
+            ArrowFunctionExpression: storeFunctionInfo,
+            'Program:exit': reportDuplications,
+        };
+    },
+});

package/src/rules/maintainability/max-parameters.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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: max-parameters
+ * Detects functions with too many parameters
+ *
+ * Note: ESLint has max-params, but this rule provides LLM-optimized messages
+ * and additional context about refactoring to object parameters
+ *
+ * @see https://rules.sonarsource.com/javascript/RSPEC-107/
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'tooManyParameters' | 'useObjectParameter' | 'extractToClass' | 'splitFunction';
+export interface Options {
+    /** Maximum allowed parameters. Default: 4 */
+    max?: number;
+    /** Ignore constructors. Default: false */
+    ignoreConstructors?: boolean;
+    /** Ignore overridden methods. Default: false */
+    ignoreOverriddenMethods?: boolean;
+}
+type RuleOptions = [Options?];
+export declare const maxParameters: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};

package/src/rules/maintainability/max-parameters.js

@@ -0,0 +1,143 @@
+"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.maxParameters = 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");
+/**
+ * Count function parameters
+ */
+function countParameters(node) {
+    return node.params.length;
+}
+exports.maxParameters = (0, eslint_devkit_2.createRule)({
+    name: 'max-parameters',
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Detects functions with too many parameters',
+        },
+        messages: {
+            tooManyParameters: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.COMPLEXITY,
+                issueName: 'Too many parameters',
+                description: '{{functionName}}: {{count}} parameters (max: {{max}})',
+                severity: 'MEDIUM',
+                fix: 'Refactor to use object parameter or split function',
+                documentationLink: 'https://rules.sonarsource.com/javascript/RSPEC-107/',
+            }),
+            useObjectParameter: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Use Object Parameter',
+                description: 'Use object parameter pattern',
+                severity: 'LOW',
+                fix: 'function({ param1, param2, param3 })',
+                documentationLink: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment',
+            }),
+            extractToClass: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Extract to Class',
+                description: 'Extract to class with properties',
+                severity: 'LOW',
+                fix: 'Create class to hold related parameters',
+                documentationLink: 'https://refactoring.guru/introduce-parameter-object',
+            }),
+            splitFunction: (0, eslint_devkit_1.formatLLMMessage)({
+                icon: eslint_devkit_1.MessageIcons.INFO,
+                issueName: 'Split Function',
+                description: 'Split into smaller functions',
+                severity: 'LOW',
+                fix: 'Extract logic into separate focused functions',
+                documentationLink: 'https://refactoring.guru/smells/long-parameter-list',
+            }),
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    max: {
+                        type: 'number',
+                        default: 4,
+                        minimum: 1,
+                    },
+                    ignoreConstructors: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                    ignoreOverriddenMethods: {
+                        type: 'boolean',
+                        default: false,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+    },
+    defaultOptions: [
+        {
+            max: 4,
+            ignoreConstructors: false,
+            ignoreOverriddenMethods: false,
+        },
+    ],
+    create(context, [options = {}]) {
+        const { max = 4, ignoreConstructors = false,
+        // ignoreOverriddenMethods = false, // Not used
+         } = options || {};
+        /**
+         * Check function parameters
+         */
+        function checkFunction(node) {
+            // Check if it's a constructor
+            if (ignoreConstructors) {
+                if (node.type === 'FunctionDeclaration' &&
+                    node.id &&
+                    node.id.name &&
+                    /^[A-Z]/.test(node.id.name)) {
+                    // Likely a constructor
+                    return;
+                }
+            }
+            const paramCount = countParameters(node);
+            if (paramCount <= max) {
+                return;
+            }
+            const functionSignature = (0, eslint_devkit_3.extractFunctionSignature)(node);
+            const overBy = paramCount - max;
+            context.report({
+                node,
+                messageId: 'tooManyParameters',
+                data: {
+                    functionName: functionSignature,
+                    count: String(paramCount),
+                    max: String(max),
+                    overBy: String(overBy),
+                },
+                suggest: [
+                    {
+                        messageId: 'useObjectParameter',
+                        fix: () => null, // Complex refactoring, cannot auto-fix
+                    },
+                    {
+                        messageId: 'extractToClass',
+                        fix: () => null,
+                    },
+                    {
+                        messageId: 'splitFunction',
+                        fix: () => null,
+                    },
+                ],
+            });
+        }
+        return {
+            FunctionDeclaration: checkFunction,
+            FunctionExpression: checkFunction,
+            ArrowFunctionExpression: checkFunction,
+        };
+    },
+});

package/src/rules/maintainability/nested-complexity-hotspots.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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: nested-complexity-hotspots
+ * Identifies nested control structures that harm readability
+ * Priority 3: Enhanced Complexity Analysis
+ *
+ * @see https://en.wikipedia.org/wiki/Cyclomatic_complexity
+ */
+import type { TSESLint } from '@interlace/eslint-devkit';
+type MessageIds = 'nestedComplexity' | 'useEarlyReturn' | 'useGuardClauses' | 'extractMethod';
+export interface Options {
+    /** Maximum nesting depth. Default: 4 */
+    maxDepth?: number;
+    /** Count nested conditionals. Default: true */
+    countConditionals?: boolean;
+    /** Count nested loops. Default: true */
+    countLoops?: boolean;
+}
+type RuleOptions = [Options?];
+/**
+ * Calculate nesting depth for a node
+ * Note: Currently unused, keeping for future implementation
+ */
+export declare const nestedComplexityHotspots: TSESLint.RuleModule<MessageIds, RuleOptions, unknown, TSESLint.RuleListener> & {
+    name: string;
+};
+export {};