#!/usr/bin/env python3
"""
validate_docs.py - Automated documentation validation for mathematical code

This script validates that all public functions have proper documentation
including mathematical expressions and domain tags.
"""

import ast
import re
import sys
from pathlib import Path
from typing import List, Dict, Tuple

class DocumentationValidator:
    """Validates documentation completeness for mathematical functions."""
    
    def __init__(self, file_path: Path):
        self.file_path = file_path
        self.content = file_path.read_text()
        self.tree = ast.parse(self.content)
        self.missing_docs = []
        
    def check_function_docs(self) -> List[Dict]:
        """Check all public functions for documentation."""
        missing = []
        
        for node in ast.walk(self.tree):
            if isinstance(node, ast.FunctionDef) and not node.name.startswith('_'):
                docstring = ast.get_docstring(node)
                if not docstring:
                    missing.append({
                        'function': node.name,
                        'line': node.lineno,
                        'issue': 'Missing docstring'
                    })
                else:
                    # Check for mathematical content
                    math_check = self._check_math_content(docstring, node.name)
                    if math_check:
                        missing.append(math_check)
                        
        return missing
    
    def _check_math_content(self, docstring: str, func_name: str) -> Dict:
        """Check if docstring contains mathematical expressions."""
        math_indicators = [
            r'[Σ∫∂∇λμπ]',  # Greek letters common in math
            r'[≤≥≠≈∝∈∉⊂⊃]',  # Math symbols
            r'[a-z]_[{0-9}]+',  # Subscript notation
            r'[A-Z]\^[{0-9}]+',  # Superscript notation
            r'\\frac|\\sum|\\int',  # LaTeX
        ]
        
        has_math = any(re.search(pattern, docstring) for pattern in math_indicators)
        
        if not has_math:
            return {
                'function': func_name,
                'issue': 'Missing mathematical notation in docstring'
            }
        return None

def main():
    """Main validation routine."""
    files_to_check = [
        Path("src/sluq_processor.rs"),
        Path("src/oisc_processor.rs"),
        Path("src/quandary_processor.rs"),
    ]
    
    all_missing = []
    for file_path in files_to_check:
        if file_path.exists():
            validator = DocumentationValidator(file_path)
            missing = validator.check_function_docs()
            all_missing.extend(missing)
    
    if all_missing:
        print("❌ Documentation Issues Found:")
        for issue in all_missing:
            print(f"  - {issue['function']} (line {issue.get('line', '?')}): {issue['issue']}")
        sys.exit(1)
    else:
        print("✅ All functions properly documented")
        sys.exit(0)

if __name__ == "__main__":
    main()