SuperClaude/Framework-Hooks/hooks/shared/framework_logic.py

"""
Core SuperClaude Framework Logic

Implements the core decision-making algorithms from the SuperClaude framework,
including RULES.md, PRINCIPLES.md, and ORCHESTRATOR.md patterns.
"""

import json
import time
from typing import Dict, Any, List, Optional, Tuple, Union
from dataclasses import dataclass
from enum import Enum

from yaml_loader import config_loader


class OperationType(Enum):
    """Types of operations SuperClaude can perform."""
    READ = "read"
    WRITE = "write" 
    EDIT = "edit"
    ANALYZE = "analyze"
    BUILD = "build"
    TEST = "test"
    DEPLOY = "deploy"
    REFACTOR = "refactor"


class RiskLevel(Enum):
    """Risk levels for operations."""
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"


@dataclass
class OperationContext:
    """Context information for an operation."""
    operation_type: OperationType
    file_count: int
    directory_count: int
    has_tests: bool
    is_production: bool
    user_expertise: str  # beginner, intermediate, expert
    project_type: str   # web, api, cli, library, etc.
    complexity_score: float  # 0.0 to 1.0
    risk_level: RiskLevel


@dataclass
class ValidationResult:
    """Result of validation checks."""
    is_valid: bool
    issues: List[str]
    warnings: List[str]
    suggestions: List[str]
    quality_score: float  # 0.0 to 1.0


class FrameworkLogic:
    """
    Core SuperClaude framework logic implementation.
    
    Encapsulates decision-making algorithms from:
    - RULES.md: Operational rules and security patterns
    - PRINCIPLES.md: Development principles and quality standards
    - ORCHESTRATOR.md: Intelligent routing and coordination
    """
    
    def __init__(self):
        # Load performance targets from SuperClaude configuration
        self.performance_targets = {}
        
        # Get hook-specific performance targets
        self.performance_targets['session_start_ms'] = config_loader.get_hook_config(
            'session_start', 'performance_target_ms', 50
        )
        self.performance_targets['tool_routing_ms'] = config_loader.get_hook_config(
            'pre_tool_use', 'performance_target_ms', 200
        )
        self.performance_targets['validation_ms'] = config_loader.get_hook_config(
            'post_tool_use', 'performance_target_ms', 100
        )
        self.performance_targets['compression_ms'] = config_loader.get_hook_config(
            'pre_compact', 'performance_target_ms', 150
        )
        
        # Load additional performance settings from global configuration
        global_perf = config_loader.get_performance_targets()
        if global_perf:
            self.performance_targets.update(global_perf)
    
    def should_use_read_before_write(self, context: OperationContext) -> bool:
        """
        RULES.md: Always use Read tool before Write or Edit operations.
        """
        return context.operation_type in [OperationType.WRITE, OperationType.EDIT]
    
    def calculate_complexity_score(self, operation_data: Dict[str, Any]) -> float:
        """
        Calculate operation complexity score (0.0 to 1.0).
        
        Factors:
        - File count and types
        - Operation scope
        - Dependencies
        - Risk factors
        """
        score = 0.0
        
        # File count factor (0.0 to 0.3)
        file_count = operation_data.get('file_count', 1)
        if file_count <= 1:
            score += 0.0
        elif file_count <= 3:
            score += 0.1
        elif file_count <= 10:
            score += 0.2
        else:
            score += 0.3
        
        # Directory factor (0.0 to 0.2)
        dir_count = operation_data.get('directory_count', 1)
        if dir_count > 2:
            score += 0.2
        elif dir_count > 1:
            score += 0.1
        
        # Operation type factor (0.0 to 0.3)
        op_type = operation_data.get('operation_type', '')
        if op_type in ['refactor', 'architecture', 'system-wide']:
            score += 0.3
        elif op_type in ['build', 'implement', 'migrate']:
            score += 0.2
        elif op_type in ['fix', 'update', 'improve']:
            score += 0.1
        
        # Language/framework factor (0.0 to 0.2)
        if operation_data.get('multi_language', False):
            score += 0.2
        elif operation_data.get('framework_changes', False):
            score += 0.1
        
        return min(score, 1.0)
    
    def assess_risk_level(self, context: OperationContext) -> RiskLevel:
        """
        Assess risk level based on operation context.
        """
        if context.is_production:
            return RiskLevel.HIGH
        
        if context.complexity_score > 0.7:
            return RiskLevel.HIGH
        elif context.complexity_score > 0.4:
            return RiskLevel.MEDIUM
        elif context.file_count > 10:
            return RiskLevel.MEDIUM
        else:
            return RiskLevel.LOW
    
    def should_enable_validation(self, context: OperationContext) -> bool:
        """
        ORCHESTRATOR.md: Enable validation for production code or high-risk operations.
        """
        return (
            context.is_production or 
            context.risk_level in [RiskLevel.HIGH, RiskLevel.CRITICAL] or
            context.operation_type in [OperationType.DEPLOY, OperationType.REFACTOR]
        )
    
    def should_enable_delegation(self, context: OperationContext) -> Tuple[bool, str]:
        """
        ORCHESTRATOR.md: Enable delegation for multi-file operations.
        
        Returns:
            (should_delegate, delegation_strategy)
        """
        if context.file_count > 3:
            return True, "files"
        elif context.directory_count > 2:
            return True, "folders"
        elif context.complexity_score > 0.4:
            return True, "auto"
        else:
            return False, "none"
    
    def validate_operation(self, operation_data: Dict[str, Any]) -> ValidationResult:
        """
        PRINCIPLES.md: Validate operation against core principles.
        """
        issues = []
        warnings = []
        suggestions = []
        quality_score = 1.0
        
        # Check for evidence-based decision making
        if 'evidence' not in operation_data:
            warnings.append("No evidence provided for decision")
            quality_score -= 0.1
        
        # Check for proper error handling
        if operation_data.get('operation_type') in ['write', 'edit', 'deploy']:
            if not operation_data.get('has_error_handling', False):
                issues.append("Error handling not implemented")
                quality_score -= 0.2
        
        # Check for test coverage
        if operation_data.get('affects_logic', False):
            if not operation_data.get('has_tests', False):
                warnings.append("No tests found for logic changes")
                quality_score -= 0.1
                suggestions.append("Add unit tests for new logic")
        
        # Check for documentation
        if operation_data.get('is_public_api', False):
            if not operation_data.get('has_documentation', False):
                warnings.append("Public API lacks documentation")
                quality_score -= 0.1
                suggestions.append("Add API documentation")
        
        # Security checks
        if operation_data.get('handles_user_input', False):
            if not operation_data.get('has_input_validation', False):
                issues.append("User input handling without validation")
                quality_score -= 0.3
        
        is_valid = len(issues) == 0 and quality_score >= 0.7
        
        return ValidationResult(
            is_valid=is_valid,
            issues=issues,
            warnings=warnings,
            suggestions=suggestions,
            quality_score=max(quality_score, 0.0)
        )
    
    def determine_thinking_mode(self, context: OperationContext) -> Optional[str]:
        """
        FLAGS.md: Determine appropriate thinking mode based on complexity.
        """
        if context.complexity_score >= 0.8:
            return "--ultrathink"
        elif context.complexity_score >= 0.6:
            return "--think-hard"
        elif context.complexity_score >= 0.3:
            return "--think"
        else:
            return None
    
    def should_enable_efficiency_mode(self, session_data: Dict[str, Any]) -> bool:
        """
        MODE_Token_Efficiency.md: Enable efficiency mode based on resource usage.
        """
        resource_usage = session_data.get('resource_usage_percent', 0)
        conversation_length = session_data.get('conversation_length', 0)
        
        return (
            resource_usage > 75 or
            conversation_length > 100 or
            session_data.get('user_requests_brevity', False)
        )
    
    def get_quality_gates(self, context: OperationContext) -> List[str]:
        """
        ORCHESTRATOR.md: Get appropriate quality gates for operation.
        """
        gates = ['syntax_validation']
        
        if context.operation_type in [OperationType.WRITE, OperationType.EDIT]:
            gates.extend(['type_analysis', 'code_quality'])
        
        if self.should_enable_validation(context):
            gates.extend(['security_assessment', 'performance_analysis'])
        
        if context.has_tests:
            gates.append('test_validation')
        
        if context.operation_type == OperationType.DEPLOY:
            gates.extend(['integration_testing', 'deployment_validation'])
        
        return gates
    
    def estimate_performance_impact(self, context: OperationContext) -> Dict[str, Any]:
        """
        Estimate performance impact and suggested optimizations.
        """
        base_time = 100  # ms
        
        # Calculate estimated time based on complexity
        estimated_time = base_time * (1 + context.complexity_score * 3)
        
        # Factor in file count
        if context.file_count > 5:
            estimated_time *= 1.5
        
        # Suggest optimizations
        optimizations = []
        if context.file_count > 3:
            optimizations.append("Consider parallel processing")
        if context.complexity_score > 0.6:
            optimizations.append("Enable delegation mode")
        if context.directory_count > 2:
            optimizations.append("Use folder-based delegation")
        
        return {
            'estimated_time_ms': int(estimated_time),
            'performance_risk': 'high' if estimated_time > 1000 else 'low',
            'suggested_optimizations': optimizations,
            'efficiency_gains_possible': len(optimizations) > 0
        }
    
    def apply_superclaude_principles(self, operation_data: Dict[str, Any]) -> Dict[str, Any]:
        """
        Apply SuperClaude core principles to operation planning.
        
        Returns enhanced operation data with principle-based recommendations.
        """
        enhanced_data = operation_data.copy()
        
        # Evidence > assumptions
        if 'assumptions' in enhanced_data and not enhanced_data.get('evidence'):
            enhanced_data['recommendations'] = enhanced_data.get('recommendations', [])
            enhanced_data['recommendations'].append(
                "Gather evidence to validate assumptions"
            )
        
        # Code > documentation
        if enhanced_data.get('operation_type') == 'document' and not enhanced_data.get('has_working_code'):
            enhanced_data['warnings'] = enhanced_data.get('warnings', [])
            enhanced_data['warnings'].append(
                "Ensure working code exists before extensive documentation"
            )
        
        # Efficiency > verbosity
        if enhanced_data.get('output_length', 0) > 1000 and not enhanced_data.get('justification_for_length'):
            enhanced_data['efficiency_suggestions'] = enhanced_data.get('efficiency_suggestions', [])
            enhanced_data['efficiency_suggestions'].append(
                "Consider token efficiency techniques for long outputs"
            )
        
        return enhanced_data