@sun-asterisk/sunlint 1.3.0 → 1.3.2

package/rules/common/C076_explicit_function_types/README.md

@@ -0,0 +1,30 @@
+# C076: Explicit Function Argument Types
+
+## 📋 **Rule Overview**
+
+**Rule ID**: C076  
+**Category**: Type Safety  
+**Severity**: Error  
+**Analysis**: **Semantic-Only** (requires ts-morph)
+
+## 🎯 **Description**
+
+All public functions must declare explicit types for their arguments. This rule enforces type safety at API boundaries by ensuring no `any`, `unknown`, or missing type annotations on public function parameters.
+
+## 🚨 **Why Semantic-Only?**
+
+Unlike rules C033, C035, C040 which have regex fallbacks, **C076 is semantic-only** because:
+
+1. **Type System Complexity**: Detecting `any`, `unknown`, generics, union types requires type checker
+2. **Public vs Private**: Determining function visibility needs symbol resolution  
+3. **Type Resolution**: Following imports and type aliases requires cross-file analysis
+4. **Accuracy**: Regex fallback would produce 90%+ false positives/negatives
+
+## ⚡ **Requirements**
+
+- ✅ **ts-morph** library installed
+- ✅ **TypeScript project** with tsconfig.json
+- ✅ **Semantic engine** enabled
+- ❌ **No regex fallback available**
+
+## 🔍 **What It Detects**

package/rules/common/C076_explicit_function_types/analyzer.js

@@ -0,0 +1,172 @@
+/**
+ * C076 Main Analyzer - Explicit Function Argument Types
+ * 
+ * SEMANTIC-ONLY RULE:
+ * This rule requires ts-morph and semantic analysis for accurate type checking.
+ * No regex fallback is provided because type system analysis cannot be reliably
+ * done with regex patterns.
+ * 
+ * Primary: Symbol-based analysis (100% of cases)
+ * Fallback: None - will gracefully fail if ts-morph unavailable
+ */
+
+const C076SemanticAnalyzer = require('./semantic-analyzer');
+
+class C076Analyzer {
+  constructor(semanticEngine = null) {
+    this.ruleId = 'C076';
+    this.ruleName = 'Explicit Function Argument Types';
+    this.description = 'All public functions must declare explicit types for arguments';
+    this.semanticEngine = semanticEngine;
+    this.verbose = false;
+    
+    // Initialize analyzer
+    this.semanticAnalyzer = new C076SemanticAnalyzer();
+    
+    // Configuration - semantic only
+    this.config = {
+      semanticOnly: true,        // This rule requires semantic analysis
+      fallbackToRegex: false,    // No regex fallback available
+      requiresTypeChecker: true  // Type checker is mandatory
+    };
+  }
+
+  /**
+   * Initialize with semantic engine
+   */
+  async initialize(semanticEngine = null) {
+    if (semanticEngine) {
+      this.semanticEngine = semanticEngine;
+    }
+    this.verbose = semanticEngine?.verbose || false;
+    
+    // Check if semantic engine is available
+    if (!this.semanticEngine?.project) {
+      if (this.verbose) {
+        console.log(`[DEBUG] ⚠️  C076: No semantic engine available - this rule requires ts-morph for type analysis`);
+      }
+      return false;
+    }
+    
+    // Initialize semantic analyzer
+    await this.semanticAnalyzer.initialize(semanticEngine);
+    
+    if (this.verbose) {
+      console.log(`[DEBUG] 🔧 C076: Analyzer initialized - Semantic-only mode ✅`);
+    }
+    
+    return true;
+  }
+
+  async analyze(files, language, options = {}) {
+    const violations = [];
+    
+    // Check if semantic engine is available
+    if (!this.semanticEngine?.project) {
+      if (this.verbose) {
+        console.log(`[DEBUG] ❌ C076: Skipping analysis - semantic engine required but not available`);
+        console.log(`[DEBUG] 💡 C076: Install ts-morph and ensure TypeScript project setup for type checking`);
+      }
+      return violations;
+    }
+
+    let analyzedCount = 0;
+    let skippedCount = 0;
+
+    for (const file of files) {
+      if (file.language === 'typescript' || file.language === 'javascript') {
+        try {
+          const fileViolations = await this.analyzeFile(file.path, options);
+          violations.push(...fileViolations);
+          analyzedCount++;
+        } catch (error) {
+          skippedCount++;
+          if (this.verbose) {
+            console.log(`[DEBUG] ⚠️  C076: Error analyzing ${file.path}: ${error.message}`);
+          }
+        }
+      } else {
+        skippedCount++;
+      }
+    }
+
+    // Summary
+    if (this.verbose && (analyzedCount > 0 || skippedCount > 0)) {
+      console.log(`[DEBUG] 📊 C076: Analysis summary:`);
+      console.log(`[DEBUG]    🧠 Semantic analysis: ${analyzedCount} files`);
+      console.log(`[DEBUG]    ⏭️  Skipped: ${skippedCount} files`);
+      console.log(`[DEBUG]    📈 Type-checked: ${analyzedCount}/${analyzedCount + skippedCount} files`);
+    }
+    
+    return violations;
+  }
+
+  async analyzeFile(filePath, options = {}) {
+    // Check if semantic engine and type checker are available
+    if (!this.semanticEngine?.project) {
+      if (this.verbose) {
+        console.log(`[DEBUG] ⚠️  C076: ${filePath}: No semantic engine - type analysis requires ts-morph`);
+      }
+      return [];
+    }
+
+    try {
+      const sourceFile = this.semanticEngine.project.getSourceFileByFilePath(filePath);
+      if (sourceFile) {
+        const violations = await this.semanticAnalyzer.analyzeFileBasic(filePath, options);
+        
+        if (this.verbose) {
+          console.log(`[DEBUG] 🧠 C076: ${filePath}: Found ${violations.length} violations`);
+        }
+        
+        return violations.map(v => ({ 
+          ...v, 
+          analysisStrategy: 'semantic-only',
+          requiresTypeChecker: true 
+        }));
+      } else {
+        if (this.verbose) {
+          console.log(`[DEBUG] ⚠️  C076: ${filePath}: Source file not found in ts-morph project`);
+        }
+        return [];
+      }
+    } catch (error) {
+      if (this.verbose) {
+        console.log(`[DEBUG] ❌ C076: ${filePath}: Semantic analysis failed: ${error.message}`);
+      }
+      return [];
+    }
+  }
+
+  // Compatibility method for heuristic engine
+  async analyzeFileBasic(filePath, options = {}) {
+    return await this.analyzeFile(filePath, options);
+  }
+
+  // Configuration methods
+  enableSemanticOnly() {
+    this.config.semanticOnly = true;
+    this.config.fallbackToRegex = false;
+  }
+
+  // Information methods
+  getCapabilities() {
+    return {
+      requiresSemanticEngine: true,
+      requiresTypeChecker: true,
+      supportsRegexFallback: false,
+      analysisAccuracy: 'high',
+      recommendedFor: 'TypeScript projects with strict type checking'
+    };
+  }
+
+  getRequirements() {
+    return {
+      dependencies: ['ts-morph'],
+      projectSetup: 'TypeScript project with tsconfig.json',
+      minimumAccuracy: 'semantic-only'
+    };
+  }
+}
+
+module.exports = C076Analyzer;

package/rules/common/C076_explicit_function_types/config.json

@@ -0,0 +1,15 @@
+{
+  "ruleId": "C076",
+  "name": "Explicit Function Argument Types",
+  "description": "All public functions must declare explicit types for arguments",
+  "severity": "warning",
+  "category": "type-safety",
+  "languages": ["typescript", "javascript"],
+  "disallow": ["any", "Object", "object", "{}", "unknown"],
+  "requireGenericConstraints": false,
+  "checkCollections": true,
+  "ignorePatterns": ["**/*.spec.ts", "**/__tests__/**", "**/*.test.ts"],
+  "exemptPrivateFunctions": true,
+  "allowDefaultParameters": false,
+  "strictGenericTypes": true
+}

package/rules/common/C076_explicit_function_types/semantic-analyzer.js

@@ -0,0 +1,341 @@
+/**
+ * C076 Semantic Analyzer - Explicit Function Argument Types
+ * Purpose: Use AST + Symbol Resolution to enforce explicit types on public functions
+ * 
+ * NOTE: This rule REQUIRES semantic analysis and ts-morph.
+ * Unlike C033/C035/C040, C076 does NOT have regex fallback because:
+ * 1. Type system analysis is too complex for regex patterns
+ * 2. Public vs private function detection requires symbol resolution
+ * 3. Type resolution (any, unknown, generics) needs type checker
+ * 4. Regex fallback would produce 90%+ false positives/negatives
+ */
+
+const { SyntaxKind } = require('ts-morph');
+const SemanticRuleBase = require('../../../core/semantic-rule-base');
+
+class C076SemanticAnalyzer extends SemanticRuleBase {
+  constructor() {
+    super('C076', {
+      description: 'All public functions must declare explicit types for arguments',
+      category: 'type-safety',
+      severity: 'error',
+      requiresTypeChecker: true,
+      crossFileAnalysis: false,
+      semanticOnly: true  // This rule requires semantic analysis - no regex fallback
+    });
+  }
+
+  /**
+   * Main entry point called by the semantic engine
+   */
+  async analyzeFileBasic(filePath, options = {}) {
+    return await this.analyzeFile(filePath, null, options);
+  }
+
+  /**
+   * Analyze a file for explicit function argument type violations
+   * @param {string} filePath - Path to the file
+   * @param {Object} options - Analysis options
+   */
+  async analyzeFile(filePath, sourceFile, config = {}) {
+    const verbose = this.config.verbose || false;
+    
+    if (verbose) {
+      console.log(`[DEBUG] 🔍 C076: Analyzing file ${filePath}`);
+    }
+    
+    // Get configuration with defaults
+    const {
+      disallow = ['any', 'Object', 'object', '{}', 'unknown'],
+      requireGenericConstraints = false,
+      checkCollections = true,
+      ignorePatterns = ['**/*.spec.ts', '**/__tests__/**']
+    } = config;
+
+    // Check if file should be ignored
+    if (this.shouldIgnoreFile(filePath, ignorePatterns)) {
+      if (verbose) {
+        console.log(`[DEBUG] ⏭️ C076: Ignoring file ${filePath} due to ignore patterns`);
+      }
+      return;
+    }
+
+    // Get sourceFile from semantic engine
+    if (!this.semanticEngine?.project) {
+      if (verbose) {
+        console.warn('[DEBUG] 🔍 C076: No semantic engine available, skipping analysis');
+      }
+      return;
+    }
+
+    try {
+      const tsSourceFile = this.semanticEngine.project.getSourceFile(filePath);
+      if (!tsSourceFile) {
+        if (verbose) {
+          console.warn(`[DEBUG] 🔍 C076: Could not find sourceFile for ${filePath}`);
+        }
+        return;
+      }
+
+      // Find all exported functions
+      const exportedFunctions = this.findExportedFunctions(tsSourceFile);
+      if (verbose) {
+        console.log(`[DEBUG] 🎯 C076: Found ${exportedFunctions.length} exported functions`);
+      }
+      
+      for (const func of exportedFunctions) {
+        this.analyzeFunction(func, config, filePath, verbose);
+      }
+      
+      // Find exported classes and analyze their public methods
+      const exportedClasses = this.findExportedClasses(tsSourceFile);
+      if (verbose) {
+        console.log(`[DEBUG] 📦 C076: Found ${exportedClasses.length} exported classes`);
+      }
+      
+      for (const cls of exportedClasses) {
+        this.analyzeClassMethods(cls, config, filePath, verbose);
+      }
+      
+    } catch (error) {
+      console.error(`❌ C076: Error analyzing ${filePath}:`, error.message);
+    }
+
+    if (verbose) {
+      console.log(`[DEBUG] ✅ C076: Analysis complete. Found ${this.violations.length} violations in ${filePath}`);
+    }
+  }
+
+  shouldIgnoreFile(filePath, ignorePatterns) {
+    return ignorePatterns.some(pattern => {
+      // Convert glob pattern to regex
+      const regexPattern = pattern
+        .replace(/\*\*/g, '.*')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\./g, '\\.');
+      return new RegExp(regexPattern).test(filePath);
+    });
+  }
+
+  findExportedFunctions(sourceFile) {
+    const functions = [];
+    
+    // Find all function declarations
+    const functionDecls = sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration);
+    for (const func of functionDecls) {
+      if (this.isExported(func)) {
+        functions.push({
+          type: 'function',
+          node: func,
+          name: func.getName() || 'anonymous'
+        });
+      }
+    }
+    
+    // Find variable declarations that are arrow functions
+    const variableStmts = sourceFile.getDescendantsOfKind(SyntaxKind.VariableStatement);
+    for (const stmt of variableStmts) {
+      if (this.isExported(stmt)) {
+        const declarations = stmt.getDeclarationList().getDeclarations();
+        for (const decl of declarations) {
+          const initializer = decl.getInitializer();
+          if (initializer && initializer.getKind() === SyntaxKind.ArrowFunction) {
+            functions.push({
+              type: 'arrow',
+              node: initializer,
+              name: decl.getName(),
+              declaration: decl
+            });
+          }
+        }
+      }
+    }
+    
+    return functions;
+  }
+
+  findExportedClasses(sourceFile) {
+    const classes = [];
+    
+    const classDecls = sourceFile.getDescendantsOfKind(SyntaxKind.ClassDeclaration);
+    for (const cls of classDecls) {
+      if (this.isExported(cls)) {
+        classes.push({
+          node: cls,
+          name: cls.getName() || 'anonymous'
+        });
+      }
+    }
+    
+    return classes;
+  }
+
+  isExported(node) {
+    const modifiers = node.getModifiers();
+    return modifiers.some(mod => mod.getKind() === SyntaxKind.ExportKeyword);
+  }
+
+  analyzeFunction(funcInfo, config, filePath, verbose = false) {
+    const { node, name, type } = funcInfo;
+    if (verbose) {
+      console.log(`[DEBUG] 🔎 C076: Analyzing function '${name}' (${type})`);
+    }
+    
+    const parameters = node.getParameters();
+    
+    parameters.forEach((param, index) => {
+      this.analyzeParameter(param, index, name, config, filePath, verbose);
+    });
+  }
+
+  analyzeClassMethods(classInfo, config, filePath, verbose = false) {
+    const { node, name } = classInfo;
+    if (verbose) {
+      console.log(`[DEBUG] 🔎 C076: Analyzing class '${name}'`);
+    }
+    
+    const methods = node.getMethods();
+    
+    methods.forEach(method => {
+      // Only check public methods
+      if (this.isPublicMethod(method)) {
+        const methodName = method.getName();
+        if (verbose) {
+          console.log(`[DEBUG] 🔎 C076: Analyzing method '${methodName}'`);
+        }
+        
+        const parameters = method.getParameters();
+        parameters.forEach((param, index) => {
+          this.analyzeParameter(param, index, `${name}.${methodName}`, config, filePath, verbose);
+        });
+      }
+    });
+  }
+
+  isPublicMethod(method) {
+    // Method is public if no private/protected modifier
+    const modifiers = method.getModifiers();
+    return !modifiers.some(mod => 
+      mod.getKind() === SyntaxKind.PrivateKeyword || 
+      mod.getKind() === SyntaxKind.ProtectedKeyword
+    );
+  }
+
+  analyzeParameter(param, index, functionName, config, filePath, verbose = false) {
+    const { 
+      disallow = ['any', 'Object', 'object', '{}', 'unknown'], 
+      requireGenericConstraints = false, 
+      checkCollections = true 
+    } = config;
+    const paramName = param.getName();
+    
+    if (verbose) {
+      console.log(`[DEBUG] 🔍 C076: Checking parameter '${paramName}' in '${functionName}'`);
+    }
+    
+    // Check for missing type annotation
+    const typeNode = param.getTypeNode();
+    if (!typeNode) {
+      this.violations.push(this.createViolation(
+        param,
+        `Parameter '${paramName}' at position ${index} in function '${functionName}' is missing type annotation`,
+        'missing-type',
+        filePath
+      ));
+      return;
+    }
+
+    // Get type text for analysis
+    const typeText = typeNode.getText();
+    if (verbose) {
+      console.log(`[DEBUG] 🔍 C076: Parameter '${paramName}' has type: ${typeText}`);
+    }
+    
+    // Check for disallowed types
+    if (Array.isArray(disallow) && disallow.includes(typeText)) {
+      this.violations.push(this.createViolation(
+        param,
+        `Parameter '${paramName}' in function '${functionName}' uses disallowed type '${typeText}'`,
+        'disallowed-type',
+        filePath
+      ));
+      return;
+    }
+
+    // Check for generic collections without proper typing
+    if (checkCollections && this.isUnparameterizedCollection(typeText)) {
+      this.violations.push(this.createViolation(
+        param,
+        `Parameter '${paramName}' in function '${functionName}' uses unparameterized collection type '${typeText}'`,
+        'unparameterized-collection',
+        filePath
+      ));
+      return;
+    }
+
+    // Check for generic constraints if required
+    if (requireGenericConstraints && this.isUnconstrainedGeneric(typeText)) {
+      this.violations.push(this.createViolation(
+        param,
+        `Parameter '${paramName}' in function '${functionName}' uses unconstrained generic type`,
+        'unconstrained-generic',
+        filePath
+      ));
+    }
+  }
+
+  isUnparameterizedCollection(typeText) {
+    const unparameterizedPatterns = [
+      /^Array$/,
+      /^Map$/,
+      /^Set$/,
+      /^WeakMap$/,
+      /^WeakSet$/,
+      /^Promise$/,
+      /^Observable$/
+    ];
+    
+    return unparameterizedPatterns.some(pattern => pattern.test(typeText));
+  }
+
+  isUnconstrainedGeneric(typeText) {
+    // Single letter types are often unconstrained generics
+    return /^[A-Z]$/.test(typeText);
+  }
+
+  createViolation(node, message, subtype, filePath) {
+    const startPos = node.getStart();
+    const sourceFile = node.getSourceFile();
+    const lineAndChar = sourceFile.getLineAndColumnAtPos(startPos);
+    
+    return {
+      ruleId: this.ruleId,
+      severity: 'error',
+      message,
+      source: this.ruleId,
+      file: filePath,
+      line: lineAndChar.line + 1,
+      column: lineAndChar.column + 1,
+      description: `[SEMANTIC] ${message}. Ensure all public API functions have explicit type annotations for better type safety.`,
+      suggestion: this.getSuggestion(subtype),
+      category: 'type-safety'
+    };
+  }
+
+  getSuggestion(subtype) {
+    switch (subtype) {
+      case 'missing-type':
+        return 'Add explicit type annotation: function(param: Type)';
+      case 'disallowed-type':
+        return 'Replace with specific type: string, number, UserData, etc.';
+      case 'unparameterized-collection':
+        return 'Add generic type: Array<Type>, Map<Key, Value>, Set<Type>';
+      case 'unconstrained-generic':
+        return 'Add generic constraint: <T extends BaseType>';
+      default:
+        return 'Use explicit, specific types for better type safety';
+    }
+  }
+}
+
+module.exports = C076SemanticAnalyzer;

package/rules/index.js

@@ -52,7 +52,11 @@ const commonRules = {
     C012: loadRule('common', 'C012_command_query_separation'),
     C013: loadRule('common', 'C013_no_dead_code'),
     C014: loadRule('common', 'C014_dependency_injection'),
+    C018: loadRule('common', 'C018_no_throw_generic_error'),
     C019: loadRule('common', 'C019_log_level_usage'), 
+    C030: loadRule('common', 'C030_use_custom_error_classes'),
+    C023: loadRule('common', 'C023_no_duplicate_variable'),
+    C024: loadRule('common', 'C024_no_scatter_hardcoded_constants'),
     C029: loadRule('common', 'C029_catch_block_logging'),
     C031: loadRule('common', 'C031_validation_separation'),
     C041: loadRule('common', 'C041_no_sensitive_hardcode'),
@@ -62,6 +66,7 @@ const commonRules = {
 
 // 🔒 Security Rules (S-series) - Ready for migration
 const securityRules = {
+    S006: loadRule('security', 'S006_no_plaintext_recovery_codes'),
     S015: loadRule('security', 'S015_insecure_tls_certificate'),
     S023: loadRule('security', 'S023_no_json_injection'),
     S026: loadRule('security', 'S026_json_schema_validation'),
@@ -159,4 +164,4 @@ module.exports = {
     common: commonRules,
     security: securityRules,
     typescript: typescriptRules
-};
+};

package/rules/parser/rule-parser.js

@@ -221,8 +221,12 @@ class RuleParser {
   // Process lines with keywords
   processKeywordLine(line, rule, state) {
     if (this.containsKeyword(line, "OBJECTIVE")) {
-      rule.description = this.extractValueAfterKeyword(line, "OBJECTIVE")
-      this.resetParsingState(state)
+      state.currentSection = "objective"
+      const objectiveText = this.extractValueAfterKeyword(line, "OBJECTIVE")
+      if (objectiveText) {
+        rule.description = objectiveText
+      }
+      this.resetParsingFlags(state)
     } else if (this.containsKeyword(line, "DETAILS")) {
       state.currentSection = "details"
       const detailText = this.extractValueAfterKeyword(line, "DETAILS")
@@ -279,6 +283,13 @@ class RuleParser {
       state.currentSection = null
       state.currentConfigType = this.extractConfigType(line)
       console.log(`Found config section in rule ${rule.id}: ${line} (type: ${state.currentConfigType})`)
+    } else if (state.currentSection === "objective" && line.trim() && !line.trim().startsWith("**") && !line.trim().startsWith("-")) {
+      // Continue reading objective content on next lines
+      if (rule.description) {
+        rule.description += " " + line.trim()
+      } else {
+        rule.description = line.trim()
+      }
     } else if (state.currentSection === "details" && line.trim() && !line.trim().startsWith("**")) {
       rule.details.push(line.trim())
     }