dartmind 17.0.0

package/dist/v10/quality/ReadabilityAnalyzer.js

@@ -0,0 +1,673 @@
+/**
+ * FlutterAI v10 - ReadabilityAnalyzer
+ *
+ * Code readability assessment and suggestions.
+ *
+ * Features:
+ * - Naming convention analysis
+ * - Comment and documentation analysis
+ * - Line length checking
+ * - Magic number detection
+ * - Code duplication detection
+ * - Readability scoring
+ *
+ * @module v10/quality/ReadabilityAnalyzer
+ */
+// ============================================================================
+// Default Config
+// ============================================================================
+const DEFAULT_CONFIG = {
+    maxLineLength: 120,
+    minCommentRatio: 0.05,
+    maxFunctionLength: 30,
+    enforceNamingConventions: true,
+    allowedMagicNumbers: [-1, 0, 1, 2, 10, 100]
+};
+// ============================================================================
+// Patterns
+// ============================================================================
+const PATTERNS = {
+    // Naming patterns
+    camelCase: /^[a-z][a-zA-Z0-9]*$/,
+    pascalCase: /^[A-Z][a-zA-Z0-9]*$/,
+    snakeCase: /^[a-z][a-z0-9_]*$/,
+    screamingSnakeCase: /^[A-Z][A-Z0-9_]*$/,
+    singleLetter: /^[a-zA-Z]$/,
+    // Code patterns
+    variableDeclaration: /(?:const|let|var|final)\s+(\w+)\s*=/g,
+    classDeclaration: /class\s+(\w+)/g,
+    functionDeclaration: /(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>|(\w+)\s*\([^)]*\)\s*(?:async\s*)?\{)/g,
+    parameterNames: /\(([^)]+)\)/g,
+    // Comment patterns
+    singleLineComment: /\/\/.*$/gm,
+    multiLineComment: /\/\*[\s\S]*?\*\//g,
+    jsdocComment: /\/\*\*[\s\S]*?\*\//g,
+    dartDocComment: /\/\/\/.*$/gm,
+    todoComment: /\/\/.*(?:TODO|FIXME|HACK|XXX).*$/gim,
+    // Magic numbers
+    numberLiteral: /(?<![a-zA-Z_])\b(\d+\.?\d*)\b(?![a-zA-Z_\[])/g,
+    // Loop variable detection
+    forLoopIndex: /for\s*\(\s*(?:let|var|const)?\s*([a-zA-Z])\s*=/g,
+    // Commented code detection
+    commentedCode: /\/\/\s*(?:const|let|var|function|if|for|while|return|class)\s/gm
+};
+// ============================================================================
+// Non-descriptive names to flag
+// ============================================================================
+const NON_DESCRIPTIVE_NAMES = new Set([
+    'data', 'temp', 'tmp', 'result', 'res', 'value', 'val', 'item',
+    'obj', 'arr', 'list', 'str', 'num', 'fn', 'func', 'cb', 'callback',
+    'info', 'stuff', 'thing', 'things', 'foo', 'bar', 'baz'
+]);
+// ============================================================================
+// ReadabilityAnalyzer Implementation
+// ============================================================================
+export class ReadabilityAnalyzer {
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // --------------------------------------------------------------------------
+    // Config Methods
+    // --------------------------------------------------------------------------
+    getConfig() {
+        return { ...this.config };
+    }
+    // --------------------------------------------------------------------------
+    // Main Analysis Methods
+    // --------------------------------------------------------------------------
+    analyze(code, language) {
+        const issues = [];
+        const suggestions = [];
+        // Collect all issues
+        issues.push(...this.analyzeLineLength(code));
+        issues.push(...this.analyzeNaming(code, language).issues);
+        issues.push(...this.analyzeComments(code, language));
+        issues.push(...this.analyzeMagicNumbers(code));
+        issues.push(...this.analyzeFunctionLength(code, language));
+        issues.push(...this.analyzeDuplication(code));
+        // Generate suggestions
+        suggestions.push(...this.generateSuggestions(issues, code));
+        // Calculate metrics
+        const metrics = this.calculateMetrics(code, language);
+        // Calculate scores
+        const score = this.calculateScore(issues, metrics);
+        // Generate summary
+        const summary = this.generateSummary(code, language, issues, score);
+        return {
+            score,
+            metrics,
+            issues,
+            suggestions,
+            summary
+        };
+    }
+    analyzeNaming(code, language) {
+        const analysis = {
+            camelCaseCount: 0,
+            pascalCaseCount: 0,
+            snakeCaseCount: 0,
+            screamingSnakeCaseCount: 0,
+            singleLetterCount: 0,
+            issues: []
+        };
+        // Find all identifiers
+        const identifiers = this.extractIdentifiers(code, language);
+        // Check for loop indices
+        const loopIndices = new Set();
+        let match;
+        const loopPattern = new RegExp(PATTERNS.forLoopIndex.source, 'g');
+        while ((match = loopPattern.exec(code)) !== null) {
+            loopIndices.add(match[1]);
+        }
+        for (const { name, line, type } of identifiers) {
+            // Categorize by case
+            if (PATTERNS.screamingSnakeCase.test(name)) {
+                analysis.screamingSnakeCaseCount++;
+            }
+            else if (PATTERNS.pascalCase.test(name)) {
+                analysis.pascalCaseCount++;
+            }
+            else if (PATTERNS.camelCase.test(name)) {
+                analysis.camelCaseCount++;
+            }
+            else if (PATTERNS.snakeCase.test(name)) {
+                analysis.snakeCaseCount++;
+            }
+            // Check for single-letter names (except loop indices)
+            if (PATTERNS.singleLetter.test(name)) {
+                analysis.singleLetterCount++;
+                if (!loopIndices.has(name)) {
+                    analysis.issues.push({
+                        type: 'naming',
+                        severity: 'warning',
+                        line,
+                        message: `Single-letter variable name '${name}' - consider using a more descriptive name`
+                    });
+                }
+            }
+            // Check for non-descriptive names
+            if (NON_DESCRIPTIVE_NAMES.has(name.toLowerCase())) {
+                analysis.issues.push({
+                    type: 'naming',
+                    severity: 'warning',
+                    line,
+                    message: `Non-descriptive name '${name}' - consider a more meaningful name`
+                });
+            }
+            // Check naming convention based on type
+            if (type === 'class' && !PATTERNS.pascalCase.test(name)) {
+                analysis.issues.push({
+                    type: 'naming',
+                    severity: 'error',
+                    line,
+                    message: `Class '${name}' should use PascalCase`
+                });
+            }
+            if (type === 'constant' && !PATTERNS.screamingSnakeCase.test(name) && !PATTERNS.camelCase.test(name)) {
+                analysis.issues.push({
+                    type: 'naming',
+                    severity: 'info',
+                    line,
+                    message: `Constant '${name}' should use SCREAMING_SNAKE_CASE or camelCase`
+                });
+            }
+        }
+        return analysis;
+    }
+    // --------------------------------------------------------------------------
+    // Line Length Analysis
+    // --------------------------------------------------------------------------
+    analyzeLineLength(code) {
+        const issues = [];
+        const lines = code.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.length > this.config.maxLineLength) {
+                issues.push({
+                    type: 'line-length',
+                    severity: 'warning',
+                    line: i + 1,
+                    message: `Line exceeds maximum length of ${this.config.maxLineLength} characters (${line.length})`
+                });
+            }
+        }
+        return issues;
+    }
+    // --------------------------------------------------------------------------
+    // Comment Analysis
+    // --------------------------------------------------------------------------
+    analyzeComments(code, language) {
+        const issues = [];
+        const lines = code.split('\n');
+        // Check for TODO/FIXME comments
+        let match;
+        const todoPattern = new RegExp(PATTERNS.todoComment.source, 'gim');
+        while ((match = todoPattern.exec(code)) !== null) {
+            const lineNumber = code.substring(0, match.index).split('\n').length;
+            issues.push({
+                type: 'comment',
+                severity: 'info',
+                line: lineNumber,
+                message: `Found TODO/FIXME comment: ${match[0].trim()}`
+            });
+        }
+        // Check for commented-out code
+        const commentedCodePattern = new RegExp(PATTERNS.commentedCode.source, 'gm');
+        while ((match = commentedCodePattern.exec(code)) !== null) {
+            const lineNumber = code.substring(0, match.index).split('\n').length;
+            issues.push({
+                type: 'comment',
+                severity: 'warning',
+                line: lineNumber,
+                message: 'Detected commented-out code - consider removing'
+            });
+        }
+        // Check for undocumented functions
+        const functions = this.extractFunctions(code, language);
+        for (const func of functions) {
+            if (!this.hasDocumentation(code, func.line)) {
+                // Only flag complex or public functions
+                if (func.name && !func.name.startsWith('_')) {
+                    issues.push({
+                        type: 'documentation',
+                        severity: 'info',
+                        line: func.line,
+                        message: `Function '${func.name}' is not documented`
+                    });
+                }
+            }
+        }
+        return issues;
+    }
+    // --------------------------------------------------------------------------
+    // Magic Number Analysis
+    // --------------------------------------------------------------------------
+    analyzeMagicNumbers(code) {
+        const issues = [];
+        const lines = code.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Skip comments
+            if (line.trim().startsWith('//') || line.trim().startsWith('*')) {
+                continue;
+            }
+            // Find numbers
+            let match;
+            const numberPattern = new RegExp(PATTERNS.numberLiteral.source, 'g');
+            while ((match = numberPattern.exec(line)) !== null) {
+                const num = parseFloat(match[1]);
+                // Skip allowed magic numbers
+                if (this.config.allowedMagicNumbers.includes(num)) {
+                    continue;
+                }
+                // Skip numbers in array indices (simple heuristic)
+                const before = line.substring(0, match.index);
+                if (before.endsWith('[')) {
+                    continue;
+                }
+                // Skip if it's a constant definition
+                if (/const\s+[A-Z_]+\s*=/.test(line)) {
+                    continue;
+                }
+                issues.push({
+                    type: 'magic-number',
+                    severity: 'warning',
+                    line: i + 1,
+                    message: `Magic number ${num} found - consider extracting to a named constant`
+                });
+            }
+        }
+        return issues;
+    }
+    // --------------------------------------------------------------------------
+    // Function Length Analysis
+    // --------------------------------------------------------------------------
+    analyzeFunctionLength(code, language) {
+        const issues = [];
+        const functions = this.extractFunctions(code, language);
+        for (const func of functions) {
+            if (func.lineCount > this.config.maxFunctionLength) {
+                issues.push({
+                    type: 'function-length',
+                    severity: 'warning',
+                    line: func.line,
+                    message: `Function '${func.name}' is ${func.lineCount} lines (max: ${this.config.maxFunctionLength})`
+                });
+            }
+        }
+        return issues;
+    }
+    // --------------------------------------------------------------------------
+    // Duplication Analysis
+    // --------------------------------------------------------------------------
+    analyzeDuplication(code) {
+        const issues = [];
+        const lines = code.split('\n');
+        // Simple line-based duplication detection
+        const lineGroups = new Map();
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            // Skip empty lines, short lines, and comments
+            if (line.length < 10 || line.startsWith('//') || line.startsWith('*') || line === '{' || line === '}') {
+                continue;
+            }
+            if (!lineGroups.has(line)) {
+                lineGroups.set(line, []);
+            }
+            lineGroups.get(line).push(i + 1);
+        }
+        // Check for blocks of duplicated lines
+        const blockSize = 3;
+        const seenBlocks = new Map();
+        for (let i = 0; i <= lines.length - blockSize; i++) {
+            const block = lines.slice(i, i + blockSize)
+                .map(l => l.trim())
+                .filter(l => l.length > 0 && !l.startsWith('//'))
+                .join('\n');
+            if (block.length < 30)
+                continue;
+            if (seenBlocks.has(block)) {
+                const firstLine = seenBlocks.get(block);
+                issues.push({
+                    type: 'duplication',
+                    severity: 'info',
+                    line: i + 1,
+                    message: `Duplicated code block (also at line ${firstLine}) - consider extracting to a function`
+                });
+            }
+            else {
+                seenBlocks.set(block, i + 1);
+            }
+        }
+        return issues;
+    }
+    // --------------------------------------------------------------------------
+    // Metrics Calculation
+    // --------------------------------------------------------------------------
+    calculateMetrics(code, language) {
+        const lines = code.split('\n');
+        const totalLines = lines.length;
+        // Count comment lines
+        let commentLines = 0;
+        const singleComments = code.match(PATTERNS.singleLineComment) || [];
+        const multiComments = code.match(PATTERNS.multiLineComment) || [];
+        commentLines += singleComments.length;
+        for (const comment of multiComments) {
+            commentLines += comment.split('\n').length;
+        }
+        // Count code lines (non-empty, non-comment)
+        const codeLines = lines.filter(line => {
+            const trimmed = line.trim();
+            return trimmed.length > 0 &&
+                !trimmed.startsWith('//') &&
+                !trimmed.startsWith('/*') &&
+                !trimmed.startsWith('*');
+        }).length;
+        // Calculate line lengths
+        const nonEmptyLines = lines.filter(l => l.trim().length > 0);
+        const totalLength = nonEmptyLines.reduce((sum, l) => sum + l.length, 0);
+        const averageLineLength = nonEmptyLines.length > 0 ? totalLength / nonEmptyLines.length : 0;
+        const maxLineLength = Math.max(...lines.map(l => l.length));
+        // Function metrics
+        const functions = this.extractFunctions(code, language);
+        const totalFunctions = functions.length;
+        const avgFuncLength = totalFunctions > 0
+            ? functions.reduce((sum, f) => sum + f.lineCount, 0) / totalFunctions
+            : 0;
+        // Documented functions
+        let documentedFunctions = 0;
+        for (const func of functions) {
+            if (this.hasDocumentation(code, func.line)) {
+                documentedFunctions++;
+            }
+        }
+        // Duplication ratio (simplified)
+        const seenLines = new Set();
+        let duplicateCount = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length > 10 && !trimmed.startsWith('//')) {
+                if (seenLines.has(trimmed)) {
+                    duplicateCount++;
+                }
+                seenLines.add(trimmed);
+            }
+        }
+        const duplicationRatio = totalLines > 0 ? duplicateCount / totalLines : 0;
+        return {
+            totalLines,
+            codeLines,
+            commentLines,
+            commentRatio: totalLines > 0 ? commentLines / totalLines : 0,
+            averageLineLength,
+            maxLineLength,
+            averageFunctionLength: avgFuncLength,
+            documentedFunctions,
+            totalFunctions,
+            duplicationRatio
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Score Calculation
+    // --------------------------------------------------------------------------
+    calculateScore(issues, metrics) {
+        // Naming score (start at 100, deduct for issues)
+        let namingScore = 100;
+        const namingIssues = issues.filter(i => i.type === 'naming');
+        namingScore -= namingIssues.filter(i => i.severity === 'error').length * 10;
+        namingScore -= namingIssues.filter(i => i.severity === 'warning').length * 5;
+        namingScore -= namingIssues.filter(i => i.severity === 'info').length * 2;
+        namingScore = Math.max(0, namingScore);
+        // Documentation score
+        let documentationScore = 100;
+        if (metrics.totalFunctions > 0) {
+            documentationScore = (metrics.documentedFunctions / metrics.totalFunctions) * 100;
+        }
+        // Bonus for good comment ratio
+        if (metrics.commentRatio >= this.config.minCommentRatio) {
+            documentationScore = Math.min(100, documentationScore + 10);
+        }
+        // Structure score
+        let structureScore = 100;
+        const structureIssues = issues.filter(i => i.type === 'line-length' ||
+            i.type === 'function-length' ||
+            i.type === 'magic-number' ||
+            i.type === 'duplication');
+        structureScore -= structureIssues.filter(i => i.severity === 'error').length * 10;
+        structureScore -= structureIssues.filter(i => i.severity === 'warning').length * 5;
+        structureScore -= structureIssues.filter(i => i.severity === 'info').length * 2;
+        structureScore = Math.max(0, structureScore);
+        // Overall score (weighted average)
+        const overall = (namingScore * 0.3 + documentationScore * 0.3 + structureScore * 0.4);
+        return {
+            overall: Math.round(overall),
+            naming: Math.round(namingScore),
+            documentation: Math.round(documentationScore),
+            structure: Math.round(structureScore)
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Suggestion Generation
+    // --------------------------------------------------------------------------
+    generateSuggestions(issues, code) {
+        const suggestions = [];
+        const seenTypes = new Set();
+        for (const issue of issues) {
+            // Group similar suggestions
+            const key = `${issue.type}-${issue.message.split("'")[0]}`;
+            if (seenTypes.has(key))
+                continue;
+            seenTypes.add(key);
+            switch (issue.type) {
+                case 'naming':
+                    if (issue.message.includes('single-letter')) {
+                        suggestions.push({
+                            message: 'Use descriptive variable names that indicate purpose',
+                            priority: 'medium',
+                            fix: {
+                                description: 'Rename variables to describe their content or purpose'
+                            }
+                        });
+                    }
+                    else if (issue.message.includes('non-descriptive')) {
+                        suggestions.push({
+                            message: 'Replace generic names with domain-specific terminology',
+                            priority: 'medium'
+                        });
+                    }
+                    break;
+                case 'magic-number':
+                    suggestions.push({
+                        message: 'Extract magic numbers to named constants for clarity',
+                        priority: 'medium',
+                        fix: {
+                            description: 'Create a const with a descriptive name',
+                            replacement: 'const MEANINGFUL_NAME = <number>;'
+                        }
+                    });
+                    break;
+                case 'function-length':
+                    suggestions.push({
+                        message: 'Break long functions into smaller, focused functions',
+                        priority: 'high'
+                    });
+                    break;
+                case 'documentation':
+                    suggestions.push({
+                        message: 'Add JSDoc/documentation comments to public functions',
+                        priority: 'low'
+                    });
+                    break;
+                case 'duplication':
+                    suggestions.push({
+                        message: 'Extract duplicated code into a reusable function',
+                        priority: 'medium'
+                    });
+                    break;
+            }
+        }
+        // Sort by priority
+        const priorityOrder = { high: 0, medium: 1, low: 2 };
+        return suggestions.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+    }
+    // --------------------------------------------------------------------------
+    // Summary Generation
+    // --------------------------------------------------------------------------
+    generateSummary(code, language, issues, score) {
+        const lines = code.split('\n');
+        const functions = this.extractFunctions(code, language);
+        const errorCount = issues.filter(i => i.severity === 'error').length;
+        const warningCount = issues.filter(i => i.severity === 'warning').length;
+        const infoCount = issues.filter(i => i.severity === 'info').length;
+        // Calculate grade
+        let grade;
+        if (score.overall >= 90)
+            grade = 'A';
+        else if (score.overall >= 80)
+            grade = 'B';
+        else if (score.overall >= 70)
+            grade = 'C';
+        else if (score.overall >= 60)
+            grade = 'D';
+        else
+            grade = 'F';
+        return {
+            totalLines: lines.length,
+            totalFunctions: functions.length,
+            errorCount,
+            warningCount,
+            infoCount,
+            grade
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Helper Methods
+    // --------------------------------------------------------------------------
+    extractIdentifiers(code, language) {
+        const identifiers = [];
+        const lines = code.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            // Variables (JS/TS style)
+            let match;
+            const varPattern = /(?:const|let|var|final)\s+(\w+)\s*=/g;
+            while ((match = varPattern.exec(line)) !== null) {
+                const name = match[1];
+                const isConstant = line.includes('const') && /^[A-Z]/.test(name);
+                identifiers.push({
+                    name,
+                    line: i + 1,
+                    type: isConstant ? 'constant' : 'variable'
+                });
+            }
+            // Dart-style typed constants: static const int MAX_COUNT = 100;
+            if (language === 'dart') {
+                const dartConstPattern = /(?:static\s+)?const\s+(?:\w+\s+)?([A-Z][A-Z0-9_]*)\s*=/g;
+                while ((match = dartConstPattern.exec(line)) !== null) {
+                    identifiers.push({
+                        name: match[1],
+                        line: i + 1,
+                        type: 'constant'
+                    });
+                }
+                // Dart private fields: final String _privateField;
+                const dartFieldPattern = /(?:final|late)\s+(?:\w+\s+)?(_\w+)\s*[;=]/g;
+                while ((match = dartFieldPattern.exec(line)) !== null) {
+                    identifiers.push({
+                        name: match[1],
+                        line: i + 1,
+                        type: 'variable'
+                    });
+                }
+            }
+            // Classes
+            const classPattern = /class\s+(\w+)/g;
+            while ((match = classPattern.exec(line)) !== null) {
+                identifiers.push({
+                    name: match[1],
+                    line: i + 1,
+                    type: 'class'
+                });
+            }
+            // Functions
+            const funcPattern = /function\s+(\w+)/g;
+            while ((match = funcPattern.exec(line)) !== null) {
+                identifiers.push({
+                    name: match[1],
+                    line: i + 1,
+                    type: 'function'
+                });
+            }
+        }
+        return identifiers;
+    }
+    extractFunctions(code, language) {
+        const functions = [];
+        const lines = code.split('\n');
+        const funcPattern = language === 'dart'
+            ? /(?:void|int|String|bool|Future|Widget|dynamic|\w+)\s+(\w+)\s*\([^)]*\)/g
+            : /(?:function\s+(\w+)|(\w+)\s*(?:=\s*(?:async\s*)?\([^)]*\)\s*=>|\([^)]*\)\s*\{))/g;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            funcPattern.lastIndex = 0;
+            let match;
+            while ((match = funcPattern.exec(line)) !== null) {
+                const name = match[1] || match[2] || 'anonymous';
+                // Skip keywords
+                if (['if', 'for', 'while', 'switch', 'catch', 'else'].includes(name)) {
+                    continue;
+                }
+                // Find function end
+                const endLine = this.findFunctionEnd(lines, i);
+                functions.push({
+                    name,
+                    line: i + 1,
+                    lineCount: endLine - i
+                });
+            }
+        }
+        return functions;
+    }
+    findFunctionEnd(lines, startIndex) {
+        let braceCount = 0;
+        let foundStart = false;
+        for (let i = startIndex; i < lines.length; i++) {
+            const line = lines[i];
+            // Check for arrow function without braces
+            if (!foundStart && line.includes('=>') && !line.includes('{')) {
+                return i + 1;
+            }
+            const openBraces = (line.match(/\{/g) || []).length;
+            const closeBraces = (line.match(/\}/g) || []).length;
+            if (openBraces > 0)
+                foundStart = true;
+            braceCount += openBraces - closeBraces;
+            if (foundStart && braceCount === 0) {
+                return i + 1;
+            }
+        }
+        return lines.length;
+    }
+    hasDocumentation(code, functionLine) {
+        const lines = code.split('\n');
+        // Check the line(s) before the function
+        for (let i = functionLine - 2; i >= Math.max(0, functionLine - 5); i--) {
+            const line = lines[i]?.trim() || '';
+            // JSDoc or Dart doc comment
+            if (line.startsWith('/**') || line.startsWith('///') || line.startsWith('* ')) {
+                return true;
+            }
+            // If we hit code, stop looking
+            if (line.length > 0 && !line.startsWith('//') && !line.startsWith('*')) {
+                break;
+            }
+        }
+        return false;
+    }
+}
+// ============================================================================
+// Export
+// ============================================================================
+export default ReadabilityAnalyzer;
+//# sourceMappingURL=ReadabilityAnalyzer.js.map