@sun-asterisk/sunlint 1.2.1 → 1.2.2

package/rules/common/C003_no_vague_abbreviations/analyzer.js

@@ -0,0 +1,418 @@
+/**
+ * C003 Heuristic Analyzer: No vague abbreviations
+ * Detects unclear variable names and abbreviations
+ */
+
+class C003NoVagueAbbreviations {
+  constructor(options = {}) {
+    this.options = {
+      allowedSingleChar: new Set(options.allowedSingleChar || [
+        'i', 'j', 'k', 'x', 'y', 'z', 'n', 'm', 't', 'v', 'r', 'e', 'p', 'w', 'h'
+      ]),
+      allowedAbbreviations: new Set(options.allowedAbbreviations || [
+        // Technical abbreviations from user feedback
+        'id', 'url', 'uri', 'api', 'ui', 'db', 'fs', 'os', 'io', 'ai', 'ml', 'qa', 'ci', 'cd', 'pr',
+        'jwt', 'uuid', 'json', 'xml', 'html', 'css', 'sql', 'http', 'https', 'ftp', 'smtp', 'tcp', 'udp',
+        'pdf', 'csv', 'tsv', 'png', 'jpg', 'gif', 'svg', 'mp4', 'mp3', 'zip', 'tar',
+        'js', 'ts', 'py', 'rb', 'go', 'rs', 'kt', 'cs', 'vb', 'sh',
+        'dom', 'xhr', 'spa', 'pwa', 'seo', 'cdn', 'ssl', 'tls',
+        'orm', 'ddl', 'dml', 'etl', 'olap', 'oltp',
+        'kpi', 'roi', 'sla', 'poc', 'mvp', 'b2b', 'b2c', 'crm', 'erp',
+        'jsx', 'tsx', 'vue', 'scss', 'less',
+        'it', 'ut', 'e2e',
+        // Common development terms
+        'config', 'env', 'app', 'btn', 'img', 'src', 'dest', 'req', 'res', 'ctx',
+        'min', 'max', 'len', 'num', 'str', 'auth', 'log', 'err', 'msg', 'key',
+        // Add the variants from user feedback cases
+        'qa1', 'ci1', 'tsx2', 'it2', 'qa2', 'ci2',
+        // Common test/function context terms
+        'value', 'result', 'response', 'request', 'data', 'item', 'element', 'object',
+        // Common programming terms
+        'async', 'length', 'ms'
+      ]),
+      minLength: options.minLength || 2,
+      strictMode: options.strictMode || false
+    };
+
+    // Patterns for suspicious abbreviations
+    this.suspiciousPatterns = [
+      /^[a-z]{1,2}[0-9]*$/, // e.g., 'u', 'usr', 'n1', 'v2' 
+      /^[a-z]*[aeiou]*[bcdfghjklmnpqrstvwxyz]{4,}$/, // too many consonants
+      /^(tmp|temp|val|var|data|info|item|elem|el|obj|arr)([A-Z0-9].*)?$/, // generic names
+    ];
+
+    // Unclear names that should be avoided in most contexts (but not in specific contexts)
+    this.unclearNames = new Set([
+      'stuff', 'thing', 'something', 'anything', 'everything',
+      'flag', 'check', 'test', 'validate', 'process', 'handle',
+      'obj', 'arg', 'val', 'fn'
+      // Removed: 'data', 'info', 'element', 'object', 'value', 'result', 'response', 'request', 'temp', 'tmp', 'variable'
+      // These are often acceptable in specific contexts
+    ]);
+
+    // Context patterns where single letters are acceptable
+    this.loopPatterns = [
+      /for\s*\(\s*(?:let|const|var)\s+([a-z])\s*[=;]/i,
+      /\.forEach\s*\(\s*(?:\([^)]*\)|\w+)\s*=>/,
+      /\.map\s*\(\s*(?:\([^)]*\)|\w+)\s*=>/,
+      /\.filter\s*\(\s*(?:\([^)]*\)|\w+)\s*=>/
+    ];
+  }
+
+  /**
+   * Check if variable is in loop context
+   */
+  isLoopContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    const prevLine = lines[line - 2] || '';
+    const nextLine = lines[line] || '';
+    
+    const contextLines = [prevLine, currentLine, nextLine].join(' ');
+    
+    // Check for for loops
+    if (/for\s*\(\s*(?:let|const|var)\s+\w+/i.test(contextLines)) {
+      return true;
+    }
+    
+    // Check for array methods
+    if (/\.(forEach|map|filter|reduce|some|every|find|findIndex)\s*\(/i.test(contextLines)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Check if variable is in math/algorithm context
+   */
+  isMathContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Math constants like a, b, c in equations
+    if (/const\s+[a-z]\s*=\s*\d+.*[a-z]\s*=\s*\d+/.test(currentLine)) {
+      return true;
+    }
+    
+    // Math operations
+    if (/[+\-*/=]\s*\w+|\w+\s*[+\-*/=]/.test(currentLine)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Check if variable is in function parameter context
+   */
+  isFunctionParameter(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Check if we're in a function parameter list
+    return /function.*\(.*\w+.*\)/.test(currentLine) || 
+           /\(.*\w+.*\)\s*=>/.test(currentLine) ||
+           /\w+\s*=>\s*/.test(currentLine);
+  }
+
+  /**
+   * Check if variable is coordinate-like
+   */
+  isCoordinate(variableName) {
+    return /^[xyz](\d+)?$/i.test(variableName) || 
+           /^(width|height|top|left|right|bottom)$/i.test(variableName) ||
+           /^[wh](\d+)?$/i.test(variableName);
+  }
+
+  /**
+   * Check if variable is in math/algorithm context
+   */
+  isMathContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Math constants like a, b, c in equations
+    if (/const\s+[a-z]\s*=\s*\d+.*[a-z]\s*=\s*\d+/.test(currentLine)) {
+      return true;
+    }
+    
+    // Math operations
+    if (/[+\-*/=]\s*\w+|\w+\s*[+\-*/=]/.test(currentLine)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Check if variable is in function parameter context
+   */
+  isFunctionParameter(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Check if we're in a function parameter list
+    return /function.*\(.*\w+.*\)/.test(currentLine) || 
+           /\(.*\w+.*\)\s*=>/.test(currentLine) ||
+           /\w+\s*=>\s*/.test(currentLine);
+  }
+
+  /**
+   * Check if variable is in callback/iteration context  
+   */
+  isCallbackContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Array methods with callback
+    return /\.(map|filter|forEach|reduce|find|some|every)\s*\(/.test(currentLine);
+  }
+
+  /**
+   * Check if variable is in comparison/sorting context
+   */
+  isComparisonContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    const prevLine = lines[line - 2] || '';
+    const nextLine = lines[line] || '';
+    
+    const contextLines = [prevLine, currentLine, nextLine].join(' ');
+    
+    // Comparison/sorting patterns
+    return /\.sort\s*\(/.test(contextLines) ||
+           /compare\s*\(/.test(contextLines) ||
+           /\w+\s*[<>=]+\s*\w+/.test(contextLines);
+  }
+
+  /**
+   * Check if variable is in event context
+   */
+  isEventContext(content, variableName, line) {
+    const lines = content.split('\n');
+    const contextLines = lines.slice(Math.max(0, line - 2), line + 1).join(' ');
+    
+    return /(?:event|evt|e)\s*[:=]|addEventListener|onClick|onSubmit|handler/i.test(contextLines);
+  }
+
+  /**
+   * Check if variable is in destructuring context
+   */
+  isDestructuring(content, variableName, line) {
+    const lines = content.split('\n');
+    const currentLine = lines[line - 1] || '';
+    
+    // Check for object destructuring
+    if (/const\s*{[^}]*}\s*=/.test(currentLine) || /{\s*\w+[^}]*}/.test(currentLine)) {
+      return true;
+    }
+    
+    // Check for array destructuring  
+    if (/const\s*\[[^\]]*\]\s*=/.test(currentLine) || /\[\s*\w+[^\]]*\]/.test(currentLine)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Analyze variable names in files
+   * @param {string[]} files - Array of file paths to analyze
+   * @param {string} language - Programming language
+   * @param {Object} options - Analysis options
+   * @returns {Object[]} Array of violations
+   */
+  async analyze(files, language, options) {
+    const violations = [];
+    
+    for (const filePath of files) {
+      try {
+        // Read file content
+        const fs = require('fs');
+        const content = fs.readFileSync(filePath, 'utf8');
+        
+        // Analyze file content
+        const fileViolations = this.analyzeContent(content, filePath);
+        violations.push(...fileViolations);
+        
+      } catch (error) {
+        console.error(`Error analyzing file ${filePath}:`, error.message);
+      }
+    }
+    
+    return violations;
+  }
+
+  /**
+   * Analyze variable names in content
+   */
+  analyzeContent(content, filePath) {
+    // Ensure content is a string
+    if (typeof content !== 'string') {
+      console.error('Content is not a string:', typeof content);
+      return [];
+    }
+
+    const violations = [];
+    const lines = content.split('\n');
+    
+    lines.forEach((line, index) => {
+      const lineNumber = index + 1;
+      
+      // Match variable declarations
+      const patterns = [
+        // const/let/var declarations
+        /(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*[=:]/g,
+        // Function parameters in function declarations
+        /function\s+\w*\s*\(\s*([^)]+)\s*\)/g,
+        // Arrow function parameters
+        /\(\s*([^)]+)\s*\)\s*=>/g,
+        // Single parameter arrow functions
+        /([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=>/g,
+      ];
+      
+      patterns.forEach(pattern => {
+        let match;
+        while ((match = pattern.exec(line)) !== null) {
+          let variableNames = [];
+          
+          if (match[1]) {
+            // Handle parameter lists
+            if (match[1].includes(',')) {
+              variableNames = match[1].split(',')
+                .map(param => param.trim().split(/[:\s=]/)[0].trim())
+                .filter(name => name && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name));
+            } else {
+              const cleanName = match[1].trim().split(/[:\s=]/)[0].trim();
+              if (cleanName && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(cleanName)) {
+                variableNames = [cleanName];
+              }
+            }
+          }
+          
+          variableNames.forEach(variableName => {
+            const violation = this.checkVariableName(variableName, content, lineNumber, match.index);
+            if (violation) {
+              violations.push({
+                rule: 'C003',
+                severity: 'warning',
+                message: violation.message,
+                line: lineNumber,
+                column: match.index + 1,
+                filePath: filePath
+              });
+            }
+          });
+        }
+      });
+    });
+    
+    return violations;
+  }
+
+  /**
+   * Check individual variable name
+   */
+  checkVariableName(variableName, content, line, column) {
+    // Skip if empty or invalid
+    if (!variableName || typeof variableName !== 'string') {
+      return null;
+    }
+
+    // Skip TypeScript/React specific names
+    if (variableName.startsWith('_') || variableName.includes('$')) {
+      return null;
+    }
+
+    // Skip common React patterns
+    if (/^(useState|useEffect|useCallback|useMemo|useRef|useContext)$/.test(variableName)) {
+      return null;
+    }
+
+    // Check single character variables
+    if (variableName.length === 1) {
+      const lowerName = variableName.toLowerCase();
+      
+      // Allow if in allowed single char list
+      if (this.options.allowedSingleChar.has(lowerName)) {
+        return null;
+      }
+      
+      // Allow if in loop context
+      if (this.isLoopContext(content, variableName, line)) {
+        return null;
+      }
+      
+      // Allow coordinates
+      if (this.isCoordinate(variableName)) {
+        return null;
+      }
+      
+      // Allow in event context
+      if (lowerName === 'e' && this.isEventContext(content, variableName, line)) {
+        return null;
+      }
+      
+      // Allow in math context (a, b, c coefficients)
+      if (['a', 'b', 'c'].includes(lowerName) && this.isMathContext(content, variableName, line)) {
+        return null;
+      }
+      
+      // Allow a, b in comparison/sorting context
+      if (['a', 'b'].includes(lowerName) && this.isComparisonContext(content, variableName, line)) {
+        return null;
+      }
+      
+      return {
+        message: `Variable '${variableName}' is only 1 character long. Use descriptive names (except for counters like i, j, k).`
+      };
+    }
+
+    const lowerName = variableName.toLowerCase();
+
+    // Check if it's an allowed abbreviation
+    if (this.options.allowedAbbreviations.has(lowerName)) {
+      return null;
+    }
+
+    // Allow in destructuring context  
+    if (this.isDestructuring(content, variableName, line)) {
+      return null;
+    }
+
+    // Allow in callback/function parameter context for common terms
+    if (['item', 'data', 'element'].includes(lowerName) && 
+        (this.isCallbackContext(content, variableName, line) || 
+         this.isFunctionParameter(content, variableName, line))) {
+      return null;
+    }
+
+    // Check for minimum length
+    if (variableName.length < this.options.minLength) {
+      return {
+        message: `Variable '${variableName}' is too short (${variableName.length} characters). Use descriptive names with at least ${this.options.minLength} characters.`
+      };
+    }
+
+    // Check for suspicious patterns
+    for (const pattern of this.suspiciousPatterns) {
+      if (pattern.test(lowerName)) {
+        return {
+          message: `Variable '${variableName}' appears to be an unclear abbreviation. Use full descriptive names.`
+        };
+      }
+    }
+
+    // Check for unclear names
+    if (this.unclearNames.has(lowerName)) {
+      return {
+        message: `Variable '${variableName}' is unclear or ambiguous. Use more specific descriptive names.`
+      };
+    }
+
+    return null;
+  }
+}
+
+module.exports = C003NoVagueAbbreviations;

package/rules/common/C003_no_vague_abbreviations/config.json

@@ -0,0 +1,35 @@
+{
+  "id": "C003",
+  "name": "no-vague-abbreviations",
+  "description": "Clear variable names, avoid arbitrary abbreviations",
+  "category": "naming",
+  "severity": "warning",
+  "language": ["typescript", "javascript"],
+  "engine": "heuristic",
+  "meta": {
+    "docs": {
+      "description": "Ensure clear, understandable variable names without arbitrary abbreviations",
+      "url": "https://github.com/sun-asterisk/engineer-excellence/blob/main/docs/rules/C003.md"
+    },
+    "schema": {
+      "type": "object",
+      "properties": {
+        "allowedSingleChar": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Single character variables that are allowed"
+        },
+        "allowedAbbreviations": {
+          "type": "array", 
+          "items": { "type": "string" },
+          "description": "Common abbreviations that are allowed"
+        },
+        "minLength": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum variable name length"
+        }
+      }
+    }
+  }
+}