kailash 0.1.4__py3-none-any.whl → 0.2.0__py3-none-any.whl

kailash/workflow/validation.py

@@ -0,0 +1,693 @@
+"""
+Comprehensive Validation and Linting for Cyclic Workflows.
+
+This module provides extensive validation and linting capabilities to identify
+common issues, performance anti-patterns, security vulnerabilities, and potential
+problems in cyclic workflows before execution. It acts as a quality gate to
+ensure workflow reliability and optimal performance.
+
+Design Philosophy:
+    Provides proactive quality assurance through comprehensive static analysis
+    of workflow structures, configurations, and patterns. Identifies issues
+    early in the development cycle with specific, actionable recommendations
+    for resolution and optimization.
+
+Key Features:
+    - Multi-category validation (safety, performance, compatibility)
+    - Severity-based issue classification (error, warning, info)
+    - Specific error codes with documentation links
+    - Actionable suggestions for issue resolution
+    - Comprehensive reporting with categorization
+    - Integration with development workflows
+
+Validation Categories:
+    - Convergence: Cycle termination and convergence conditions
+    - Safety: Resource limits and infinite loop prevention
+    - Performance: Anti-patterns and optimization opportunities
+    - Parameter Mapping: Cycle parameter flow validation
+    - Node Compatibility: Cycle-aware node validation
+    - Resource Usage: Memory and file handle management
+
+Issue Severity Levels:
+    - ERROR: Critical issues that prevent execution or cause failures
+    - WARNING: Potential issues that may impact performance or reliability
+    - INFO: Suggestions for improvement and best practices
+
+Core Components:
+    - ValidationIssue: Structured issue representation with metadata
+    - IssueSeverity: Enumeration of severity levels
+    - CycleLinter: Main validation engine with comprehensive checks
+    - Reporting system with categorization and filtering
+
+Validation Algorithms:
+    - Static analysis of cycle configurations
+    - Pattern recognition for common anti-patterns
+    - Resource usage analysis and leak detection
+    - Security validation for parameter access
+    - Performance bottleneck identification
+
+Upstream Dependencies:
+    - Workflow graph structure and cycle detection
+    - Node implementations and configuration validation
+    - Cycle configuration and safety systems
+
+Downstream Consumers:
+    - Development tools and IDEs for real-time validation
+    - CI/CD pipelines for automated quality gates
+    - Performance optimization tools
+    - Security analysis and compliance systems
+    - Educational and training materials
+
+Examples:
+    Basic workflow validation:
+    
+    >>> from kailash.workflow.validation import CycleLinter, IssueSeverity
+    >>> linter = CycleLinter(workflow)
+    >>> issues = linter.check_all()
+    >>> # Filter by severity
+    >>> errors = linter.get_issues_by_severity(IssueSeverity.ERROR)
+    >>> warnings = linter.get_issues_by_severity(IssueSeverity.WARNING)
+    >>> for error in errors:
+    ...     print(f"ERROR {error.code}: {error.message}")
+    ...     if error.suggestion:
+    ...         print(f"  Suggestion: {error.suggestion}")
+    
+    Comprehensive reporting:
+    
+    >>> report = linter.generate_report()
+    >>> print(f"Total issues: {report['summary']['total_issues']}")
+    >>> print(f"Critical errors: {report['summary']['errors']}")
+    >>> print(f"Affected cycles: {report['summary']['affected_cycles']}")
+    >>> # Category-specific analysis
+    >>> for category, issues in report['by_category'].items():
+    ...     print(f"{category.upper()} ({len(issues)} issues):")
+    ...     for issue in issues:
+    ...         print(f"  {issue.code}: {issue.message}")
+    
+    Targeted validation:
+    
+    >>> # Validate specific cycle
+    >>> cycle_issues = linter.get_issues_for_cycle("optimization_cycle")
+    >>> # Validate specific node
+    >>> node_issues = linter.get_issues_for_node("processor")
+    >>> # Get recommendations
+    >>> recommendations = report['recommendations']
+    >>> for rec in recommendations:
+    ...     print(f"  {rec}")
+
+Validation Checks:
+    The linter performs comprehensive checks including:
+    
+    - **CYC001-002**: Convergence condition validation
+    - **CYC003-004**: Infinite loop prevention
+    - **CYC005-006**: Safety limit configuration
+    - **CYC007-009**: Performance anti-pattern detection
+    - **CYC010-011**: Parameter mapping validation
+    - **CYC012-013**: Node compatibility checks
+    - **CYC014-015**: Convergence condition syntax validation
+    - **CYC016-017**: Resource usage and leak detection
+
+See Also:
+    - :mod:`kailash.workflow.migration` for workflow optimization
+    - :mod:`kailash.workflow.safety` for safety mechanisms
+    - :doc:`/guides/validation` for validation best practices
+"""
+
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass
+from enum import Enum
+import re
+
+from . import Workflow
+
+
+class IssueSeverity(Enum):
+    """Severity levels for validation issues."""
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+
+
+@dataclass
+class ValidationIssue:
+    """Represents a validation issue found in a workflow."""
+    severity: IssueSeverity
+    category: str
+    code: str
+    message: str
+    node_id: Optional[str] = None
+    cycle_id: Optional[str] = None
+    suggestion: Optional[str] = None
+    documentation_link: Optional[str] = None
+
+
+class CycleLinter:
+    """
+    Comprehensive linter for cyclic workflows.
+    
+    Analyzes workflows for common issues, performance anti-patterns,
+    and potential problems specific to cyclic execution.
+    """
+    
+    def __init__(self, workflow: Workflow):
+        """
+        Initialize linter with target workflow.
+        
+        Args:
+            workflow: The workflow to analyze
+        """
+        self.workflow = workflow
+        self.graph = workflow.graph
+        self.issues: List[ValidationIssue] = []
+        
+    def check_all(self) -> List[ValidationIssue]:
+        """
+        Run all validation checks on the workflow.
+        
+        Returns:
+            List of all validation issues found
+            
+        Example:
+            >>> workflow = create_problematic_workflow()
+            >>> linter = CycleLinter(workflow)
+            >>> issues = linter.check_all()
+            >>> for issue in issues:
+            ...     print(f"{issue.severity.value}: {issue.message}")
+        """
+        self.issues = []
+        
+        # Run all checks
+        self._check_cycles_have_convergence()
+        self._check_for_infinite_loop_potential()
+        self._check_safety_limits()
+        self._check_performance_anti_patterns()
+        self._check_parameter_mapping()
+        self._check_node_compatibility()
+        self._check_convergence_conditions()
+        self._check_resource_usage()
+        
+        return self.issues
+    
+    def _check_cycles_have_convergence(self):
+        """Check that all cycles have appropriate convergence conditions."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                for source, target, edge_data in cycle_edges:
+                    if not edge_data.get('convergence_check') and not edge_data.get('max_iterations'):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.ERROR,
+                            category="convergence",
+                            code="CYC001",
+                            message=f"Cycle {cycle_id} lacks convergence condition and max_iterations",
+                            cycle_id=cycle_id,
+                            suggestion="Add convergence_check parameter or set max_iterations",
+                            documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                        ))
+                    
+                    elif not edge_data.get('convergence_check'):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="convergence",
+                            code="CYC002",
+                            message=f"Cycle {cycle_id} relies only on max_iterations without convergence check",
+                            cycle_id=cycle_id,
+                            suggestion="Consider adding convergence_check for early termination",
+                            documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                        ))
+    
+    def _check_for_infinite_loop_potential(self):
+        """Check for patterns that could lead to infinite loops."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                for source, target, edge_data in cycle_edges:
+                    max_iter = edge_data.get('max_iterations')
+                    convergence = edge_data.get('convergence_check')
+                    
+                    # Check for very high or missing max_iterations
+                    if max_iter is None or max_iter > 10000:
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="safety",
+                            code="CYC003",
+                            message=f"Cycle {cycle_id} has very high or no max_iterations limit",
+                            cycle_id=cycle_id,
+                            suggestion="Set reasonable max_iterations (e.g., 100-1000) as safety limit",
+                            documentation_link="guide/mistakes/066-infinite-cycles.md"
+                        ))
+                    
+                    # Check for potentially unreachable convergence conditions
+                    if convergence:
+                        if self._is_potentially_unreachable_condition(convergence):
+                            self.issues.append(ValidationIssue(
+                                severity=IssueSeverity.WARNING,
+                                category="convergence",
+                                code="CYC004",
+                                message=f"Convergence condition '{convergence}' may be unreachable",
+                                cycle_id=cycle_id,
+                                suggestion="Verify convergence condition is achievable",
+                                documentation_link="guide/mistakes/066-infinite-cycles.md"
+                            ))
+    
+    def _check_safety_limits(self):
+        """Check for appropriate safety limits on cycles."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                for source, target, edge_data in cycle_edges:
+                    # Check timeout
+                    if not edge_data.get('timeout'):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.INFO,
+                            category="safety",
+                            code="CYC005",
+                            message=f"Cycle {cycle_id} has no timeout limit",
+                            cycle_id=cycle_id,
+                            suggestion="Consider adding timeout parameter for safety",
+                            documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                        ))
+                    
+                    # Check memory limit
+                    if not edge_data.get('memory_limit'):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.INFO,
+                            category="safety",
+                            code="CYC006",
+                            message=f"Cycle {cycle_id} has no memory limit",
+                            cycle_id=cycle_id,
+                            suggestion="Consider adding memory_limit parameter for safety",
+                            documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                        ))
+    
+    def _check_performance_anti_patterns(self):
+        """Check for performance anti-patterns."""
+        # Use the workflow's cycle detection
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                # Get unique nodes in the cycle
+                cycle_nodes = set()
+                for source, target, _ in cycle_edges:
+                    cycle_nodes.add(source)
+                    cycle_nodes.add(target)
+                cycle_nodes = list(cycle_nodes)
+                
+                # Check for very small cycles (may have high overhead)
+                if len(cycle_nodes) == 1:
+                    node_id = cycle_nodes[0]
+                    self.issues.append(ValidationIssue(
+                        severity=IssueSeverity.INFO,
+                        category="performance",
+                        code="CYC007",
+                        message=f"Single-node cycle {cycle_id} may have high overhead",
+                        node_id=node_id,
+                        cycle_id=cycle_id,
+                        suggestion="Consider if cycle is necessary or if logic can be internal to node",
+                        documentation_link="guide/reference/pattern-library/06-performance-patterns.md"
+                    ))
+                
+                # Check for very large cycles (may be hard to debug)
+                elif len(cycle_nodes) > 10:
+                    self.issues.append(ValidationIssue(
+                        severity=IssueSeverity.WARNING,
+                        category="complexity",
+                        code="CYC008",
+                        message=f"Large cycle {cycle_id} with {len(cycle_nodes)} nodes may be hard to debug",
+                        cycle_id=cycle_id,
+                        suggestion="Consider breaking into smaller cycles or using nested workflows",
+                        documentation_link="guide/reference/pattern-library/04-complex-patterns.md"
+                    ))
+            
+                # Check for cycles with expensive operations
+                for node_id in cycle_nodes:
+                    if self._is_expensive_operation(node_id):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="performance",
+                            code="CYC009",
+                            message=f"Expensive operation '{node_id}' in cycle {cycle_id}",
+                            node_id=node_id,
+                            cycle_id=cycle_id,
+                            suggestion="Consider caching, optimization, or moving outside cycle",
+                            documentation_link="guide/reference/pattern-library/06-performance-patterns.md"
+                        ))
+    
+    def _check_parameter_mapping(self):
+        """Check for parameter mapping issues in cycles."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                # Get cycle nodes for checking
+                cycle_nodes = set()
+                for s, t, _ in cycle_edges:
+                    cycle_nodes.add(s)
+                    cycle_nodes.add(t)
+                
+                # Check each edge for issues
+                for source, target, edge_data in cycle_edges:
+                    mapping = edge_data.get('mapping', {})
+                    
+                    # Check for identity mappings (common mistake)
+                    for source_param, target_param in mapping.items():
+                        if source_param == target_param:
+                            self.issues.append(ValidationIssue(
+                                severity=IssueSeverity.WARNING,
+                                category="parameter_mapping",
+                                code="CYC010",
+                                message=f"Identity mapping '{source_param}' -> '{target_param}' in cycle {cycle_id}",
+                                cycle_id=cycle_id,
+                                suggestion="Use 'result.field' -> 'field' pattern for cycle parameter propagation",
+                                documentation_link="guide/mistakes/063-cyclic-parameter-propagation-multi-fix.md"
+                            ))
+                    
+                    # Check for missing parameter propagation
+                    if not mapping and len(cycle_nodes) > 1:
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.INFO,
+                            category="parameter_mapping",
+                            code="CYC011",
+                            message=f"Cycle {cycle_id} has no parameter mapping",
+                            cycle_id=cycle_id,
+                            suggestion="Consider if parameters need to propagate between iterations",
+                            documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                        ))
+    
+    def _check_node_compatibility(self):
+        """Check for node compatibility issues with cycles."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                # Get unique nodes in the cycle
+                cycle_nodes = set()
+                for source, target, _ in cycle_edges:
+                    cycle_nodes.add(source)
+                    cycle_nodes.add(target)
+                
+                for node_id in cycle_nodes:
+                    node = self.workflow.nodes.get(node_id)
+                    if not node:
+                        continue
+                
+                # Check if node supports cycle context
+                if hasattr(node, 'run'):
+                    # Check if node accesses cycle context safely
+                    if self._uses_unsafe_cycle_access(node):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.ERROR,
+                            category="node_compatibility",
+                            code="CYC012",
+                            message=f"Node '{node_id}' uses unsafe cycle context access",
+                            node_id=node_id,
+                            cycle_id=cycle_id,
+                            suggestion="Use context.get('cycle', {}) instead of direct access",
+                            documentation_link="guide/reference/cheatsheet/022-cycle-debugging-troubleshooting.md"
+                        ))
+                
+                # Check for PythonCodeNode parameter access
+                if hasattr(node, 'code') and node.code:
+                    if self._has_unsafe_parameter_access(node.code):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="node_compatibility",
+                            code="CYC013",
+                            message=f"PythonCodeNode '{node_id}' may have unsafe parameter access",
+                            node_id=node_id,
+                            cycle_id=cycle_id,
+                            suggestion="Use try/except pattern for cycle parameter access",
+                            documentation_link="guide/mistakes/064-pythoncodenode-none-input-validation-error.md"
+                        ))
+    
+    def _check_convergence_conditions(self):
+        """Check convergence conditions for validity."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                for source, target, edge_data in cycle_edges:
+                    convergence = edge_data.get('convergence_check')
+                    
+                    if convergence:
+                        # Check for valid Python syntax
+                        if not self._is_valid_condition_syntax(convergence):
+                            self.issues.append(ValidationIssue(
+                                severity=IssueSeverity.ERROR,
+                                category="convergence",
+                                code="CYC014",
+                                message=f"Invalid convergence condition syntax: '{convergence}'",
+                                cycle_id=cycle_id,
+                                suggestion="Ensure condition is valid Python expression",
+                                documentation_link="guide/reference/cheatsheet/019-cyclic-workflows-basics.md"
+                            ))
+                        
+                        # Check for common mistakes
+                        if self._has_convergence_condition_issues(convergence):
+                            self.issues.append(ValidationIssue(
+                                severity=IssueSeverity.WARNING,
+                                category="convergence",
+                                code="CYC015",
+                                message=f"Potential issue in convergence condition: '{convergence}'",
+                                cycle_id=cycle_id,
+                                suggestion="Verify field names and comparison operators",
+                                documentation_link="guide/mistakes/066-infinite-cycles.md"
+                            ))
+    
+    def _check_resource_usage(self):
+        """Check for potential resource usage issues."""
+        if hasattr(self.workflow, 'get_cycle_groups'):
+            cycle_groups = self.workflow.get_cycle_groups()
+            
+            for cycle_id, cycle_edges in cycle_groups.items():
+                # Get unique nodes in the cycle
+                cycle_nodes = set()
+                for source, target, _ in cycle_edges:
+                    cycle_nodes.add(source)
+                    cycle_nodes.add(target)
+                
+                # Check for potential memory leaks
+                for node_id in cycle_nodes:
+                    if self._may_have_memory_leak(node_id):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="resource_usage",
+                            code="CYC016",
+                            message=f"Node '{node_id}' may have memory leak in cycle",
+                            node_id=node_id,
+                            cycle_id=cycle_id,
+                            suggestion="Ensure proper cleanup of resources in cyclic execution",
+                            documentation_link="guide/mistakes/016-memory-leaks-in-long-running-processes.md"
+                        ))
+                
+                # Check for file handle management
+                for node_id in cycle_nodes:
+                    if self._may_leak_file_handles(node_id):
+                        self.issues.append(ValidationIssue(
+                            severity=IssueSeverity.WARNING,
+                            category="resource_usage",
+                            code="CYC017",
+                            message=f"Node '{node_id}' may leak file handles in cycle",
+                            node_id=node_id,
+                            cycle_id=cycle_id,
+                            suggestion="Use context managers (with statements) for file operations",
+                            documentation_link="guide/mistakes/022-resource-cleanup-issues.md"
+                        ))
+    
+    def _get_cycle_id(self, cycle_nodes: List[str]) -> str:
+        """Generate a cycle identifier from cycle nodes."""
+        return f"cycle_{'-'.join(sorted(cycle_nodes))}"
+    
+    def _is_potentially_unreachable_condition(self, condition: str) -> bool:
+        """Check if convergence condition might be unreachable."""
+        # Simple heuristics for potentially problematic conditions
+        problematic_patterns = [
+            r'.*==\s*True\s*$',  # exact boolean match
+            r'.*==\s*1\.0\s*$',  # exact float match
+            r'.*>\s*1\.0\s*$',   # probability > 1.0
+            r'.*<\s*0\.0\s*$',   # probability < 0.0
+        ]
+        
+        for pattern in problematic_patterns:
+            if re.search(pattern, condition):
+                return True
+        
+        return False
+    
+    def _is_expensive_operation(self, node_id: str) -> bool:
+        """Check if node represents an expensive operation."""
+        expensive_keywords = [
+            'train', 'model', 'neural', 'deep', 'learning',
+            'api', 'request', 'http', 'download', 'upload',
+            'database', 'query', 'sql',
+            'file', 'io', 'read', 'write'
+        ]
+        
+        node_id_lower = node_id.lower()
+        return any(keyword in node_id_lower for keyword in expensive_keywords)
+    
+    def _uses_unsafe_cycle_access(self, node) -> bool:
+        """Check if node uses unsafe cycle context access."""
+        # This would require more sophisticated code analysis
+        # For now, return False as a placeholder
+        return False
+    
+    def _has_unsafe_parameter_access(self, code: str) -> bool:
+        """Check if PythonCodeNode has unsafe parameter access."""
+        # Look for direct parameter access without try/except
+        lines = code.split('\n')
+        
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith('#'):
+                # Check for variable access that might be parameters
+                if re.match(r'^[a-zA-Z_]\w*\s*=', line):
+                    var_name = line.split('=')[0].strip()
+                    # If variable is used before definition, might be parameter
+                    if not self._is_defined_before_use(var_name, code):
+                        return True
+        
+        return False
+    
+    def _is_defined_before_use(self, var_name: str, code: str) -> bool:
+        """Check if variable is defined before use in code."""
+        lines = code.split('\n')
+        defined = False
+        
+        for line in lines:
+            line = line.strip()
+            if line.startswith(f'{var_name} =') or line.startswith(f'{var_name}='):
+                defined = True
+            elif var_name in line and not defined:
+                # Used before definition
+                return False
+        
+        return True
+    
+    def _is_valid_condition_syntax(self, condition: str) -> bool:
+        """Check if convergence condition has valid Python syntax."""
+        try:
+            compile(condition, '<string>', 'eval')
+            return True
+        except SyntaxError:
+            return False
+    
+    def _has_convergence_condition_issues(self, condition: str) -> bool:
+        """Check for common issues in convergence conditions."""
+        # Check for undefined variables (common field names)
+        undefined_vars = ['done', 'converged', 'finished', 'complete', 'quality', 'error']
+        
+        for var in undefined_vars:
+            if var in condition:
+                # Might be using undefined variable
+                return True
+        
+        return False
+    
+    def _may_have_memory_leak(self, node_id: str) -> bool:
+        """Check if node might have memory leaks."""
+        leak_keywords = ['accumulate', 'collect', 'gather', 'cache', 'store']
+        node_id_lower = node_id.lower()
+        return any(keyword in node_id_lower for keyword in leak_keywords)
+    
+    def _may_leak_file_handles(self, node_id: str) -> bool:
+        """Check if node might leak file handles."""
+        file_keywords = ['file', 'read', 'write', 'open', 'csv', 'json', 'log']
+        node_id_lower = node_id.lower()
+        return any(keyword in node_id_lower for keyword in file_keywords)
+    
+    def get_issues_by_severity(self, severity: IssueSeverity) -> List[ValidationIssue]:
+        """Get all issues of a specific severity level."""
+        return [issue for issue in self.issues if issue.severity == severity]
+    
+    def get_issues_by_category(self, category: str) -> List[ValidationIssue]:
+        """Get all issues of a specific category."""
+        return [issue for issue in self.issues if issue.category == category]
+    
+    def get_issues_for_cycle(self, cycle_id: str) -> List[ValidationIssue]:
+        """Get all issues for a specific cycle."""
+        return [issue for issue in self.issues if issue.cycle_id == cycle_id]
+    
+    def get_issues_for_node(self, node_id: str) -> List[ValidationIssue]:
+        """Get all issues for a specific node."""
+        return [issue for issue in self.issues if issue.node_id == node_id]
+    
+    def generate_report(self) -> Dict[str, Any]:
+        """
+        Generate comprehensive validation report.
+        
+        Returns:
+            Dict containing validation report with summary and details
+            
+        Example:
+            >>> from kailash import Workflow
+            >>> workflow = Workflow("test", "Test Workflow")
+            >>> linter = CycleLinter(workflow)
+            >>> linter.check_all()
+            >>> report = linter.generate_report()
+            >>> print(f"Found {report['summary']['total_issues']} issues")
+        """
+        errors = self.get_issues_by_severity(IssueSeverity.ERROR)
+        warnings = self.get_issues_by_severity(IssueSeverity.WARNING)
+        info = self.get_issues_by_severity(IssueSeverity.INFO)
+        
+        # Group by category
+        by_category = {}
+        for issue in self.issues:
+            if issue.category not in by_category:
+                by_category[issue.category] = []
+            by_category[issue.category].append(issue)
+        
+        # Group by cycle
+        by_cycle = {}
+        for issue in self.issues:
+            if issue.cycle_id:
+                if issue.cycle_id not in by_cycle:
+                    by_cycle[issue.cycle_id] = []
+                by_cycle[issue.cycle_id].append(issue)
+        
+        return {
+            'summary': {
+                'total_issues': len(self.issues),
+                'errors': len(errors),
+                'warnings': len(warnings),
+                'info': len(info),
+                'categories': list(by_category.keys()),
+                'affected_cycles': len(by_cycle)
+            },
+            'issues': self.issues,
+            'by_severity': {
+                'errors': errors,
+                'warnings': warnings,
+                'info': info
+            },
+            'by_category': by_category,
+            'by_cycle': by_cycle,
+            'recommendations': self._generate_recommendations()
+        }
+    
+    def _generate_recommendations(self) -> List[str]:
+        """Generate high-level recommendations based on found issues."""
+        recommendations = []
+        
+        errors = self.get_issues_by_severity(IssueSeverity.ERROR)
+        if errors:
+            recommendations.append(f"Fix {len(errors)} critical errors before deployment")
+        
+        convergence_issues = self.get_issues_by_category("convergence")
+        if convergence_issues:
+            recommendations.append("Review convergence conditions for all cycles")
+        
+        performance_issues = self.get_issues_by_category("performance")
+        if performance_issues:
+            recommendations.append("Optimize cycles to improve performance")
+        
+        safety_issues = self.get_issues_by_category("safety")
+        if safety_issues:
+            recommendations.append("Add safety limits (timeout, max_iterations) to cycles")
+        
+        return recommendations