@voodocs/cli 0.1.0

package/lib/darkarts/plugins/voodocs/annotation_validator.py

@@ -0,0 +1,280 @@
+"""
+VooDocs Annotation Validator
+
+Validates @voodocs annotations for correctness and quality.
+"""
+
+from typing import List, Dict, Any, Optional
+from darkarts.annotations.types import ParsedAnnotations, FunctionAnnotation, ClassAnnotation
+import re
+
+
+class ValidationIssue:
+    """Represents a validation issue."""
+    
+    def __init__(self, severity: str, message: str, location: str, suggestion: Optional[str] = None):
+        self.severity = severity  # "error", "warning", "info"
+        self.message = message
+        self.location = location
+        self.suggestion = suggestion
+    
+    def __str__(self):
+        icon = "❌" if self.severity == "error" else "⚠️" if self.severity == "warning" else "ℹ️"
+        result = f"{icon} [{self.severity.upper()}] {self.location}: {self.message}"
+        if self.suggestion:
+            result += f"\n   💡 Suggestion: {self.suggestion}"
+        return result
+
+
+class AnnotationValidator:
+    """Validates VooDocs annotations."""
+    
+    VALID_FIELDS = {
+        "module_purpose", "dependencies", "assumptions", "security_model",
+        "preconditions", "postconditions", "invariants", "complexity",
+        "error_cases", "security_implications", "solve", "optimize",
+        "class_invariants", "state_transitions", "thread_safety"
+    }
+    
+    REQUIRED_FUNCTION_FIELDS = {"preconditions", "postconditions"}
+    REQUIRED_CLASS_FIELDS = {"class_invariants"}
+    
+    def __init__(self):
+        self.issues = []
+    
+    def validate(self, parsed: ParsedAnnotations) -> List[ValidationIssue]:
+        """Validate all annotations in a parsed file."""
+        self.issues = []
+        
+        # Validate module annotations
+        self._validate_module(parsed.module)
+        
+        # Validate function annotations
+        for func in parsed.get_all_functions():
+            self._validate_function(func)
+        
+        # Validate class annotations
+        for cls in parsed.module.classes:
+            self._validate_class(cls)
+        
+        return self.issues
+    
+    def _validate_module(self, module):
+        """Validate module-level annotations."""
+        location = f"Module '{module.name}'"
+        
+        # Check for module_purpose
+        if not module.module_purpose:
+            self.issues.append(ValidationIssue(
+                "info",
+                "No module_purpose defined",
+                location,
+                "Add a module_purpose to describe what this module does"
+            ))
+        
+        # Check dependencies format
+        if module.dependencies:
+            for dep in module.dependencies:
+                if not isinstance(dep, str):
+                    self.issues.append(ValidationIssue(
+                        "error",
+                        f"Invalid dependency format: {dep}",
+                        location,
+                        "Dependencies should be strings"
+                    ))
+    
+    def _validate_function(self, func: FunctionAnnotation):
+        """Validate function annotations."""
+        location = f"Function '{func.name}'"
+        
+        # Check for required fields
+        if not func.preconditions:
+            self.issues.append(ValidationIssue(
+                "warning",
+                "No preconditions defined",
+                location,
+                "Add preconditions to specify input requirements"
+            ))
+        
+        if not func.postconditions:
+            self.issues.append(ValidationIssue(
+                "warning",
+                "No postconditions defined",
+                location,
+                "Add postconditions to specify output guarantees"
+            ))
+        
+        # Validate preconditions
+        if func.preconditions:
+            for pre in func.preconditions:
+                self._validate_condition(pre, location, "precondition")
+        
+        # Validate postconditions
+        if func.postconditions:
+            for post in func.postconditions:
+                self._validate_condition(post, location, "postcondition")
+        
+        # Check for complexity annotation
+        if not func.complexity:
+            self.issues.append(ValidationIssue(
+                "info",
+                "No complexity annotation",
+                location,
+                "Add complexity annotation for performance-critical functions"
+            ))
+        else:
+            # Validate complexity format
+            if func.complexity.time:
+                if not self._is_valid_complexity(func.complexity.time):
+                    self.issues.append(ValidationIssue(
+                        "warning",
+                        f"Invalid time complexity format: {func.complexity.time}",
+                        location,
+                        "Use Big-O notation like O(n), O(log n), O(1)"
+                    ))
+            
+            if func.complexity.space:
+                if not self._is_valid_complexity(func.complexity.space):
+                    self.issues.append(ValidationIssue(
+                        "warning",
+                        f"Invalid space complexity format: {func.complexity.space}",
+                        location,
+                        "Use Big-O notation like O(n), O(log n), O(1)"
+                    ))
+        
+        # Check for error_cases
+        if not func.error_cases:
+            self.issues.append(ValidationIssue(
+                "info",
+                "No error_cases defined",
+                location,
+                "Add error_cases to document failure modes"
+            ))
+        
+        # Validate consistency between pre and post conditions
+        self._validate_consistency(func, location)
+    
+    def _validate_class(self, cls: ClassAnnotation):
+        """Validate class annotations."""
+        location = f"Class '{cls.name}'"
+        
+        # Check for class invariants
+        if not cls.class_invariants:
+            self.issues.append(ValidationIssue(
+                "warning",
+                "No class_invariants defined",
+                location,
+                "Add class_invariants to specify object state constraints"
+            ))
+        
+        # Check for state transitions
+        if not cls.state_transitions:
+            self.issues.append(ValidationIssue(
+                "info",
+                "No state_transitions defined",
+                location,
+                "Add state_transitions if this class has state changes"
+            ))
+        
+        # Validate methods
+        if cls.methods:
+            for method in cls.methods:
+                self._validate_function(method)
+    
+    def _validate_condition(self, condition: str, location: str, cond_type: str):
+        """Validate a single condition (precondition or postcondition)."""
+        # Check for empty conditions
+        if not condition or not condition.strip():
+            self.issues.append(ValidationIssue(
+                "error",
+                f"Empty {cond_type}",
+                location,
+                f"Remove empty {cond_type} or add meaningful constraint"
+            ))
+            return
+        
+        # Check for common typos in mathematical notation
+        if '∈' in condition:
+            # Valid: x ∈ ℝ, x ∈ ℤ, x ∈ ℕ
+            if not re.search(r'\w+\s*∈\s*[ℝℤℕ]', condition):
+                self.issues.append(ValidationIssue(
+                    "warning",
+                    f"Possibly malformed set membership: {condition}",
+                    location,
+                    "Use ∈ with standard sets: ℝ (reals), ℤ (integers), ℕ (naturals)"
+                ))
+        
+        # Check for inconsistent operators
+        if '⇒' in condition or '⇔' in condition:
+            # These should be used correctly
+            if condition.count('⇒') > 1 and '∧' not in condition and '∨' not in condition:
+                self.issues.append(ValidationIssue(
+                    "info",
+                    f"Complex implication: {condition}",
+                    location,
+                    "Consider breaking into multiple conditions for clarity"
+                ))
+        
+        # Check for undefined variables
+        # This is a simple heuristic - in practice, you'd need proper parsing
+        if cond_type == "postcondition" and "result" not in condition.lower():
+            # Postconditions should usually reference the result
+            self.issues.append(ValidationIssue(
+                "info",
+                f"Postcondition doesn't reference 'result': {condition}",
+                location,
+                "Postconditions typically specify properties of the result"
+            ))
+    
+    def _is_valid_complexity(self, complexity: str) -> bool:
+        """Check if complexity notation is valid."""
+        # Valid patterns: O(1), O(n), O(log n), O(n log n), O(n^2), etc.
+        pattern = r'^O\([^)]+\)$'
+        return bool(re.match(pattern, complexity))
+    
+    def _validate_consistency(self, func: FunctionAnnotation, location: str):
+        """Validate consistency between preconditions and postconditions."""
+        if not func.preconditions or not func.postconditions:
+            return
+        
+        # Extract variable names from preconditions
+        pre_vars = set()
+        for pre in func.preconditions:
+            # Simple heuristic: extract words that look like variable names
+            matches = re.findall(r'\b([a-z_][a-z0-9_]*)\b', pre.lower())
+            pre_vars.update(matches)
+        
+        # Extract variable names from postconditions
+        post_vars = set()
+        for post in func.postconditions:
+            matches = re.findall(r'\b([a-z_][a-z0-9_]*)\b', post.lower())
+            post_vars.update(matches)
+        
+        # Remove common keywords
+        keywords = {'and', 'or', 'not', 'in', 'is', 'must', 'be', 'the', 'a', 'an', 'for', 'all', 'exists'}
+        pre_vars -= keywords
+        post_vars -= keywords
+        
+        # Check if postconditions reference precondition variables
+        # (This is a weak check but can catch some issues)
+        if pre_vars and not (pre_vars & post_vars or 'result' in post_vars):
+            self.issues.append(ValidationIssue(
+                "info",
+                "Postconditions don't reference precondition variables",
+                location,
+                "Consider relating output to input in postconditions"
+            ))
+    
+    def get_summary(self) -> Dict[str, int]:
+        """Get summary of validation issues."""
+        summary = {
+            "errors": sum(1 for issue in self.issues if issue.severity == "error"),
+            "warnings": sum(1 for issue in self.issues if issue.severity == "warning"),
+            "info": sum(1 for issue in self.issues if issue.severity == "info"),
+            "total": len(self.issues)
+        }
+        return summary
+    
+    def has_errors(self) -> bool:
+        """Check if there are any errors."""
+        return any(issue.severity == "error" for issue in self.issues)