tywrap 0.7.0 → 0.9.0

package/src/core/validation.ts

@@ -1,729 +0,0 @@
-/**
- * Error Handling & Validation Framework
- *
- * Comprehensive error handling, syntax validation, and analysis reporting system
- */
-
-import type {
-  AnalysisError,
-  AnalysisWarning,
-  // AnalysisStatistics,
-  PythonFunction,
-  PythonClass,
-  PythonType,
-} from '../types/index.js';
-
-export interface ValidationConfig {
-  strictTypeChecking: boolean;
-  allowMissingTypeHints: boolean;
-  maxComplexityScore: number;
-  deprecatedPatterns: string[];
-  requiredDocstrings: boolean;
-}
-
-export interface ValidationReport {
-  errors: AnalysisError[];
-  warnings: AnalysisWarning[];
-  statistics: ValidationStatistics;
-  recommendations: ValidationRecommendation[];
-}
-
-export interface ValidationStatistics {
-  totalIssues: number;
-  errorCount: number;
-  warningCount: number;
-  typeHintCoverage: number;
-  docstringCoverage: number;
-  complexityScore: number;
-  qualityScore: number; // 0-100
-}
-
-export interface ValidationRecommendation {
-  type: 'performance' | 'maintainability' | 'type-safety' | 'documentation';
-  severity: 'low' | 'medium' | 'high' | 'critical';
-  message: string;
-  suggestion: string;
-  file?: string;
-  line?: number;
-  impact: string;
-}
-
-export class ValidationEngine {
-  private config: ValidationConfig;
-
-  constructor(config: Partial<ValidationConfig> = {}) {
-    this.config = {
-      strictTypeChecking: config.strictTypeChecking ?? true,
-      allowMissingTypeHints: config.allowMissingTypeHints ?? false,
-      maxComplexityScore: 10,
-      deprecatedPatterns: [],
-      requiredDocstrings: false,
-      ...config,
-    };
-  }
-
-  /**
-   * Validate Python functions for type safety and best practices
-   */
-  validateFunction(func: PythonFunction, filePath?: string): ValidationReport {
-    const errors: AnalysisError[] = [];
-    const warnings: AnalysisWarning[] = [];
-    const recommendations: ValidationRecommendation[] = [];
-
-    // Check type hints
-    this.validateTypeHints(func, errors, warnings);
-
-    // Check docstring
-    this.validateDocstring(func, warnings, filePath);
-
-    // Check parameter patterns
-    this.validateParameters(func, warnings, filePath);
-
-    // Check for deprecated patterns
-    this.validateDeprecatedPatterns(func, warnings, filePath);
-
-    // Check complexity
-    this.validateComplexity(func, warnings, filePath);
-
-    // Generate recommendations
-    this.generateFunctionRecommendations(func, recommendations, filePath);
-
-    const statistics = this.calculateFunctionStatistics(func, errors, warnings);
-
-    return {
-      errors,
-      warnings,
-      statistics,
-      recommendations,
-    };
-  }
-
-  /**
-   * Validate Python classes for structure and best practices
-   */
-  validateClass(cls: PythonClass, filePath?: string): ValidationReport {
-    const errors: AnalysisError[] = [];
-    const warnings: AnalysisWarning[] = [];
-    const recommendations: ValidationRecommendation[] = [];
-
-    // Validate each method
-    for (const method of cls.methods) {
-      const methodReport = this.validateFunction(method, filePath);
-      errors.push(...methodReport.errors);
-      warnings.push(...methodReport.warnings);
-      recommendations.push(...methodReport.recommendations);
-    }
-
-    // Validate class-specific patterns
-    this.validateClassStructure(cls, warnings, filePath);
-    this.validateInheritance(cls, warnings, filePath);
-
-    const statistics = this.calculateClassStatistics(cls, errors, warnings);
-
-    return {
-      errors,
-      warnings,
-      statistics,
-      recommendations,
-    };
-  }
-
-  /**
-   * Validate type annotations for correctness
-   */
-  validateTypeAnnotation(type: PythonType, context: string = ''): AnalysisError[] {
-    const errors: AnalysisError[] = [];
-
-    try {
-      this.validateTypeStructure(type, errors, context);
-    } catch (error) {
-      errors.push({
-        type: 'type',
-        message: `Type validation failed: ${error}`,
-      });
-    }
-
-    return errors;
-  }
-
-  /**
-   * Generate comprehensive analysis report
-   */
-  generateReport(
-    functions: PythonFunction[],
-    classes: PythonClass[],
-    filePath?: string
-  ): ValidationReport {
-    const errors: AnalysisError[] = [];
-    const warnings: AnalysisWarning[] = [];
-    const recommendations: ValidationRecommendation[] = [];
-
-    // Validate all functions
-    for (const func of functions) {
-      const funcReport = this.validateFunction(func, filePath);
-      errors.push(...funcReport.errors);
-      warnings.push(...funcReport.warnings);
-      recommendations.push(...funcReport.recommendations);
-    }
-
-    // Validate all classes
-    for (const cls of classes) {
-      const classReport = this.validateClass(cls, filePath);
-      errors.push(...classReport.errors);
-      warnings.push(...classReport.warnings);
-      recommendations.push(...classReport.recommendations);
-    }
-
-    // Generate module-level recommendations
-    this.generateModuleRecommendations(functions, classes, recommendations, filePath);
-
-    const statistics = this.calculateModuleStatistics(functions, classes, errors, warnings);
-
-    return {
-      errors,
-      warnings,
-      statistics,
-      recommendations,
-    };
-  }
-
-  /**
-   * Private validation methods
-   */
-  private validateTypeHints(
-    func: PythonFunction,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): void {
-    this.checkReturnTypeHint(func, errors, warnings);
-
-    // Check parameter types (skip 'self' and 'cls' parameters)
-    for (const param of func.parameters) {
-      this.checkParameterTypeHint(func, param, errors, warnings);
-      this.checkParameterTypeStructure(param, errors);
-    }
-
-    this.checkReturnTypeStructure(func, errors);
-  }
-
-  /**
-   * Emit a missing-type warning, and—in strict mode—an accompanying error.
-   * In strict mode without allowMissingTypeHints, we warn first then error.
-   */
-  private reportMissingType(
-    warningMessage: string,
-    errorMessage: string,
-    warnings: AnalysisWarning[],
-    errors: AnalysisError[]
-  ): void {
-    if (this.config.allowMissingTypeHints) {
-      warnings.push({ type: 'missing-type', message: warningMessage });
-    } else if (this.config.strictTypeChecking) {
-      warnings.push({ type: 'missing-type', message: warningMessage });
-      errors.push({ type: 'type', message: errorMessage });
-    }
-  }
-
-  /**
-   * Check the function return type annotation (skip __init__ methods as they
-   * conventionally don't need return type annotations).
-   */
-  private checkReturnTypeHint(
-    func: PythonFunction,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): void {
-    if (this.isEmptyType(func.returnType) && func.name !== '__init__') {
-      this.reportMissingType(
-        `Function '${func.name}' is missing return type annotation`,
-        `Function '${func.name}' requires return type annotation`,
-        warnings,
-        errors
-      );
-    }
-  }
-
-  /**
-   * Check a single parameter's type annotation (skip 'self' and 'cls').
-   */
-  private checkParameterTypeHint(
-    func: PythonFunction,
-    param: PythonFunction['parameters'][number],
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): void {
-    if (this.isEmptyType(param.type) && param.name !== 'self' && param.name !== 'cls') {
-      this.reportMissingType(
-        `Parameter '${param.name}' in function '${func.name}' is missing type annotation`,
-        `Parameter '${param.name}' in function '${func.name}' requires type annotation`,
-        warnings,
-        errors
-      );
-    }
-  }
-
-  /**
-   * Validate a single parameter's type structure only in strict mode
-   * (skip 'self' and 'cls' parameters).
-   */
-  private checkParameterTypeStructure(
-    param: PythonFunction['parameters'][number],
-    errors: AnalysisError[]
-  ): void {
-    if (
-      this.config.strictTypeChecking &&
-      !this.config.allowMissingTypeHints &&
-      param.name !== 'self' &&
-      param.name !== 'cls'
-    ) {
-      const typeErrors = this.validateTypeAnnotation(param.type, `parameter '${param.name}'`);
-      errors.push(...typeErrors);
-    }
-  }
-
-  /**
-   * Validate the return type structure only in strict mode.
-   */
-  private checkReturnTypeStructure(func: PythonFunction, errors: AnalysisError[]): void {
-    if (this.config.strictTypeChecking && !this.config.allowMissingTypeHints) {
-      const returnTypeErrors = this.validateTypeAnnotation(func.returnType, 'return type');
-      errors.push(...returnTypeErrors);
-    }
-  }
-
-  private validateDocstring(
-    func: PythonFunction,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    if (this.config.requiredDocstrings && !func.docstring) {
-      warnings.push({
-        type: 'missing-type',
-        message: `Function '${func.name}' is missing docstring`,
-        file: filePath,
-      });
-    }
-
-    // Check docstring quality
-    if (func.docstring && func.docstring.length < 10) {
-      warnings.push({
-        type: 'missing-type',
-        message: `Function '${func.name}' has very short docstring`,
-        file: filePath,
-      });
-    }
-  }
-
-  private validateParameters(
-    func: PythonFunction,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    // Check for too many parameters
-    if (func.parameters.length > 8) {
-      warnings.push({
-        type: 'performance',
-        message: `Function '${func.name}' has too many parameters (${func.parameters.length})`,
-        file: filePath,
-      });
-    }
-
-    // Check parameter naming
-    for (const param of func.parameters) {
-      if (param.name.length < 2 && !['x', 'y', 'z', 'i', 'j', 'k'].includes(param.name)) {
-        warnings.push({
-          type: 'missing-type',
-          message: `Parameter '${param.name}' in function '${func.name}' should have a more descriptive name`,
-          file: filePath,
-        });
-      }
-    }
-  }
-
-  private validateDeprecatedPatterns(
-    func: PythonFunction,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    for (const pattern of this.config.deprecatedPatterns) {
-      if (func.name.includes(pattern)) {
-        warnings.push({
-          type: 'deprecated',
-          message: `Function '${func.name}' uses deprecated pattern '${pattern}'`,
-          file: filePath,
-        });
-      }
-    }
-  }
-
-  private validateComplexity(
-    func: PythonFunction,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    // Simple complexity estimation based on parameters and async/generator flags
-    let complexity = func.parameters.length * 0.5;
-    if (func.isAsync) {
-      complexity += 1;
-    }
-    if (func.isGenerator) {
-      complexity += 1;
-    }
-    if (func.decorators.length > 0) {
-      complexity += func.decorators.length * 0.5;
-    }
-
-    if (complexity > this.config.maxComplexityScore) {
-      warnings.push({
-        type: 'performance',
-        message: `Function '${func.name}' has high complexity (${complexity.toFixed(1)})`,
-        file: filePath,
-      });
-    }
-  }
-
-  private validateClassStructure(
-    cls: PythonClass,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    // Check for empty classes
-    if (cls.methods.length === 0 && cls.properties.length === 0) {
-      warnings.push({
-        type: 'missing-type',
-        message: `Class '${cls.name}' appears to be empty`,
-        file: filePath,
-      });
-    }
-
-    // Check for missing __init__ method
-    const hasInit = cls.methods.some(method => method.name === '__init__');
-    if (!hasInit && cls.properties.length > 0) {
-      warnings.push({
-        type: 'missing-type',
-        message: `Class '${cls.name}' has properties but no __init__ method`,
-        file: filePath,
-      });
-    }
-  }
-
-  private validateInheritance(
-    cls: PythonClass,
-    warnings: AnalysisWarning[],
-    filePath?: string
-  ): void {
-    // Check for deep inheritance chains
-    if (cls.bases.length > 3) {
-      warnings.push({
-        type: 'compatibility',
-        message: `Class '${cls.name}' inherits from many classes (${cls.bases.length})`,
-        file: filePath,
-      });
-    }
-
-    // Check for diamond inheritance pattern
-    if (cls.bases.length > 1) {
-      warnings.push({
-        type: 'compatibility',
-        message: `Class '${cls.name}' uses multiple inheritance, consider composition`,
-        file: filePath,
-      });
-    }
-  }
-
-  private validateTypeStructure(type: PythonType, errors: AnalysisError[], context: string): void {
-    switch (type.kind) {
-      case 'union':
-        if (type.types.length < 2) {
-          errors.push({
-            type: 'type',
-            message: `Union type in ${context} should have at least 2 types`,
-          });
-        }
-        // Recursively validate union member types
-        for (const unionType of type.types) {
-          this.validateTypeStructure(unionType, errors, context);
-        }
-        break;
-
-      case 'collection':
-        if (type.itemTypes.length === 0 && ['list', 'dict', 'set'].includes(type.name)) {
-          errors.push({
-            type: 'type',
-            message: `Collection type '${type.name}' in ${context} should specify item types`,
-          });
-        }
-        // Recursively validate item types
-        for (const itemType of type.itemTypes) {
-          this.validateTypeStructure(itemType, errors, context);
-        }
-        break;
-
-      case 'optional':
-        this.validateTypeStructure(type.type, errors, context);
-        break;
-
-      case 'generic':
-        // Validate generic arguments
-        for (const arg of type.typeArgs) {
-          this.validateTypeStructure(arg, errors, context);
-        }
-        break;
-
-      case 'custom':
-        // Could add checks for known custom types
-        break;
-
-      case 'primitive':
-        // Basic types are always valid
-        break;
-    }
-  }
-
-  private isEmptyType(type: PythonType): boolean {
-    return type.kind === 'primitive' && type.name === 'None';
-  }
-
-  private generateFunctionRecommendations(
-    func: PythonFunction,
-    recommendations: ValidationRecommendation[],
-    filePath?: string
-  ): void {
-    // Recommend async for I/O operations
-    if (
-      (!func.isAsync && func.name.includes('read')) ||
-      func.name.includes('write') ||
-      func.name.includes('fetch')
-    ) {
-      recommendations.push({
-        type: 'performance',
-        severity: 'medium',
-        message: `Consider making '${func.name}' async for I/O operations`,
-        suggestion: `Add 'async def' instead of 'def' and use await for I/O operations`,
-        file: filePath,
-        impact: 'Improved performance for I/O-bound operations',
-      });
-    }
-
-    // Recommend type hints if missing
-    if (func.parameters.some(p => this.isEmptyType(p.type)) || this.isEmptyType(func.returnType)) {
-      recommendations.push({
-        type: 'type-safety',
-        severity: 'high',
-        message: `Add type hints to '${func.name}' for better IDE support`,
-        suggestion: 'Add type annotations to parameters and return type',
-        file: filePath,
-        impact: 'Better IDE support, type checking, and documentation',
-      });
-    }
-
-    // Recommend docstrings
-    if (!func.docstring) {
-      recommendations.push({
-        type: 'documentation',
-        severity: 'medium',
-        message: `Add docstring to '${func.name}'`,
-        suggestion: 'Add a docstring explaining the function purpose, parameters, and return value',
-        file: filePath,
-        impact: 'Better code documentation and IDE support',
-      });
-    }
-  }
-
-  private generateModuleRecommendations(
-    functions: PythonFunction[],
-    classes: PythonClass[],
-    recommendations: ValidationRecommendation[],
-    filePath?: string
-  ): void {
-    const totalFunctions =
-      functions.length + classes.reduce((acc, cls) => acc + cls.methods.length, 0);
-
-    // Recommend breaking up large modules
-    if (totalFunctions > 50) {
-      recommendations.push({
-        type: 'maintainability',
-        severity: 'medium',
-        message: 'Module has many functions, consider breaking it up',
-        suggestion: 'Split module into smaller, focused modules',
-        file: filePath,
-        impact: 'Improved maintainability and code organization',
-      });
-    }
-
-    // Check type hint coverage
-    const functionsWithTypes = functions.filter(
-      f => !this.isEmptyType(f.returnType) || f.parameters.some(p => !this.isEmptyType(p.type))
-    );
-
-    const typeHintCoverage =
-      totalFunctions > 0 ? (functionsWithTypes.length / totalFunctions) * 100 : 100;
-
-    if (typeHintCoverage < 50) {
-      recommendations.push({
-        type: 'type-safety',
-        severity: 'high',
-        message: `Low type hint coverage (${typeHintCoverage.toFixed(1)}%)`,
-        suggestion: 'Add type annotations to improve type safety',
-        file: filePath,
-        impact: 'Better type checking and IDE support',
-      });
-    }
-  }
-
-  private calculateFunctionStatistics(
-    func: PythonFunction,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): ValidationStatistics {
-    const hasTypeHints =
-      !this.isEmptyType(func.returnType) || func.parameters.some(p => !this.isEmptyType(p.type));
-
-    return {
-      totalIssues: errors.length + warnings.length,
-      errorCount: errors.length,
-      warningCount: warnings.length,
-      typeHintCoverage: hasTypeHints ? 100 : 0,
-      docstringCoverage: func.docstring ? 100 : 0,
-      complexityScore: this.calculateComplexity(func),
-      qualityScore: this.calculateQualityScore(func, errors, warnings),
-    };
-  }
-
-  private calculateClassStatistics(
-    cls: PythonClass,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): ValidationStatistics {
-    const methodsWithTypes = cls.methods.filter(
-      m => !this.isEmptyType(m.returnType) || m.parameters.some(p => !this.isEmptyType(p.type))
-    ).length;
-
-    const methodsWithDocstrings = cls.methods.filter(m => m.docstring).length;
-
-    const typeHintCoverage =
-      cls.methods.length > 0 ? (methodsWithTypes / cls.methods.length) * 100 : 100;
-    const docstringCoverage =
-      cls.methods.length > 0 ? (methodsWithDocstrings / cls.methods.length) * 100 : 100;
-
-    return {
-      totalIssues: errors.length + warnings.length,
-      errorCount: errors.length,
-      warningCount: warnings.length,
-      typeHintCoverage,
-      docstringCoverage,
-      complexityScore: Math.max(...cls.methods.map(m => this.calculateComplexity(m)), 0),
-      qualityScore: this.calculateClassQualityScore(cls, errors, warnings),
-    };
-  }
-
-  private calculateModuleStatistics(
-    functions: PythonFunction[],
-    classes: PythonClass[],
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): ValidationStatistics {
-    const allMethods = classes.flatMap(cls => cls.methods);
-    const allFunctions = [...functions, ...allMethods];
-
-    const functionsWithTypes = allFunctions.filter(
-      f => !this.isEmptyType(f.returnType) || f.parameters.some(p => !this.isEmptyType(p.type))
-    ).length;
-
-    const functionsWithDocstrings = allFunctions.filter(f => f.docstring).length;
-
-    const typeHintCoverage =
-      allFunctions.length > 0 ? (functionsWithTypes / allFunctions.length) * 100 : 100;
-    const docstringCoverage =
-      allFunctions.length > 0 ? (functionsWithDocstrings / allFunctions.length) * 100 : 100;
-
-    return {
-      totalIssues: errors.length + warnings.length,
-      errorCount: errors.length,
-      warningCount: warnings.length,
-      typeHintCoverage,
-      docstringCoverage,
-      complexityScore: Math.max(...allFunctions.map(f => this.calculateComplexity(f)), 0),
-      qualityScore: this.calculateModuleQualityScore(allFunctions, errors, warnings),
-    };
-  }
-
-  private calculateComplexity(func: PythonFunction): number {
-    let complexity = 1; // Base complexity
-    complexity += func.parameters.length * 0.5;
-    complexity += func.isAsync ? 1 : 0;
-    complexity += func.isGenerator ? 1 : 0;
-    complexity += func.decorators.length * 0.5;
-    return Math.round(complexity * 10) / 10;
-  }
-
-  private calculateQualityScore(
-    func: PythonFunction,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): number {
-    let score = 100;
-
-    // Deduct points for errors and warnings
-    score -= errors.length * 20;
-    score -= warnings.length * 10;
-
-    // Add points for good practices
-    if (!this.isEmptyType(func.returnType)) {
-      score += 10;
-    }
-    if (func.parameters.every(p => !this.isEmptyType(p.type))) {
-      score += 10;
-    }
-    if (func.docstring) {
-      score += 10;
-    }
-
-    return Math.max(0, Math.min(100, score));
-  }
-
-  private calculateClassQualityScore(
-    cls: PythonClass,
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): number {
-    let score = 100;
-
-    // Deduct points for errors and warnings
-    score -= errors.length * 15;
-    score -= warnings.length * 8;
-
-    // Add points for good practices
-    if (cls.docstring) {
-      score += 10;
-    }
-    if (cls.methods.some(m => m.name === '__init__')) {
-      score += 10;
-    }
-    if (cls.methods.length > 0) {
-      score += 5;
-    }
-
-    return Math.max(0, Math.min(100, score));
-  }
-
-  private calculateModuleQualityScore(
-    functions: PythonFunction[],
-    errors: AnalysisError[],
-    warnings: AnalysisWarning[]
-  ): number {
-    if (functions.length === 0) {
-      return 100;
-    }
-
-    const functionScores = functions.map(f =>
-      this.calculateQualityScore(
-        f,
-        errors.filter(e => e.message?.includes(f.name)),
-        warnings.filter(w => w.message?.includes(f.name))
-      )
-    );
-
-    return functionScores.reduce((sum, score) => sum + score, 0) / functionScores.length;
-  }
-}