@voodocs/cli 0.1.0

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

@@ -0,0 +1,486 @@
+"""
+DarkArts API Specification Generator
+
+Generates OpenAPI/Swagger specifications from DarkArts annotations.
+"""
+
+from typing import List, Optional, Dict, Any
+from pathlib import Path
+import json
+import yaml
+
+from darkarts.annotations.types import (
+    ParsedAnnotations,
+    FunctionAnnotation,
+    ClassAnnotation,
+)
+
+
+class APISpecGenerator:
+    """Generates API specifications from DarkArts annotations."""
+    
+    def __init__(self, format: str = "openapi"):
+        """
+        Initialize API spec generator.
+        
+        Args:
+            format: Specification format ("openapi", "swagger", "graphql")
+        """
+        self.format = format
+    
+    def generate(self, parsed: ParsedAnnotations, output_file: Optional[str] = None) -> str:
+        """Generate API specification from parsed annotations."""
+        if self.format == "openapi":
+            return self._generate_openapi(parsed, output_file)
+        elif self.format == "swagger":
+            return self._generate_openapi(parsed, output_file)  # Same as OpenAPI
+        elif self.format == "graphql":
+            return self._generate_graphql(parsed, output_file)
+        else:
+            raise ValueError(f"Unsupported format: {self.format}")
+    
+    def _generate_openapi(self, parsed: ParsedAnnotations, output_file: Optional[str] = None) -> str:
+        """Generate OpenAPI 3.0 specification."""
+        spec = {
+            "openapi": "3.0.0",
+            "info": {
+                "title": parsed.module.name.replace("_", " ").title() + " API",
+                "version": "1.0.0",
+                "description": parsed.module.module_purpose or "API generated from DarkArts annotations"
+            },
+            "paths": {},
+            "components": {
+                "schemas": {}
+            }
+        }
+        
+        # Add dependencies as external docs
+        if parsed.module.dependencies:
+            spec["externalDocs"] = {
+                "description": "Dependencies",
+                "url": "#"
+            }
+        
+        # Generate paths from functions
+        all_functions = parsed.get_all_functions()
+        for func in all_functions:
+            path = f"/{func.name}"
+            spec["paths"][path] = self._generate_openapi_path(func)
+        
+        # Generate schemas from classes
+        for cls in parsed.module.classes:
+            spec["components"]["schemas"][cls.name] = self._generate_openapi_schema(cls)
+        
+        # Convert to YAML (more readable than JSON for API specs)
+        spec_yaml = yaml.dump(spec, default_flow_style=False, sort_keys=False)
+        
+        if output_file:
+            output_path = Path(output_file)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            
+            if output_file.endswith('.json'):
+                output_path.write_text(json.dumps(spec, indent=2), encoding='utf-8')
+            else:
+                output_path.write_text(spec_yaml, encoding='utf-8')
+        
+        return spec_yaml
+    
+    def _generate_openapi_path(self, func: FunctionAnnotation) -> Dict[str, Any]:
+        """Generate OpenAPI path item for a function."""
+        operation = {
+            "post": {
+                "summary": func.solve or f"Execute {func.name}",
+                "description": self._build_function_description(func),
+                "requestBody": {
+                    "required": True,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "type": "object",
+                                "properties": self._extract_parameters_from_preconditions(func)
+                            },
+                            "examples": {
+                                "example1": {
+                                    "summary": "Example request",
+                                    "value": self._generate_request_example(func)
+                                }
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "Successful operation",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": self._extract_response_from_postconditions(func)
+                                },
+                                "examples": {
+                                    "example1": {
+                                        "summary": "Example response",
+                                        "value": self._generate_response_example(func)
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        
+        # Add error responses
+        if func.error_cases:
+            for error in func.error_cases:
+                error_str = str(error)
+                if '→' in error_str:
+                    condition, error_type = error_str.split('→')
+                    error_type = error_type.strip()
+                    
+                    # Map error types to HTTP status codes
+                    status_code = self._map_error_to_status_code(error_type)
+                    operation["post"]["responses"][str(status_code)] = {
+                        "description": error_type,
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "properties": {
+                                        "error": {"type": "string"},
+                                        "message": {"type": "string"}
+                                    }
+                                }
+                            }
+                        }
+                    }
+        
+        # Add performance info
+        if func.complexity:
+            operation["post"]["x-complexity"] = {
+                "time": func.complexity.time,
+                "space": func.complexity.space
+            }
+        
+        if func.optimize:
+            operation["post"]["x-optimization"] = func.optimize
+        
+        return operation
+    
+    def _generate_openapi_schema(self, cls: ClassAnnotation) -> Dict[str, Any]:
+        """Generate OpenAPI schema for a class."""
+        schema = {
+            "type": "object",
+            "description": f"{cls.name} class",
+            "properties": {},
+            "x-invariants": cls.class_invariants or []
+        }
+        
+        if cls.state_transitions:
+            schema["x-state-transitions"] = [str(st) for st in cls.state_transitions]
+        
+        # Add methods as operations
+        if cls.methods:
+            schema["x-methods"] = [
+                {
+                    "name": method.name,
+                    "description": method.solve or "",
+                    "preconditions": method.preconditions or [],
+                    "postconditions": method.postconditions or []
+                }
+                for method in cls.methods
+            ]
+        
+        return schema
+    
+    def _build_function_description(self, func: FunctionAnnotation) -> str:
+        """Build detailed description for a function."""
+        parts = []
+        
+        if func.solve:
+            parts.append(func.solve)
+        
+        if func.preconditions:
+            parts.append("\n\n**Preconditions:**")
+            for pre in func.preconditions:
+                parts.append(f"- {pre}")
+        
+        if func.postconditions:
+            parts.append("\n\n**Postconditions:**")
+            for post in func.postconditions:
+                parts.append(f"- {post}")
+        
+        if func.invariants:
+            parts.append("\n\n**Invariants:**")
+            for inv in func.invariants:
+                parts.append(f"- {inv}")
+        
+        return "\n".join(parts)
+    
+    def _extract_parameters_from_preconditions(self, func: FunctionAnnotation) -> Dict[str, Any]:
+        """Extract parameter definitions from preconditions with enhanced type inference."""
+        import re
+        params = {}
+        
+        if func.preconditions:
+            for pre in func.preconditions:
+                # Extract parameter name and infer type
+                param_info = self._infer_param_from_condition(pre)
+                if param_info:
+                    param_name, param_schema = param_info
+                    if param_name not in params:
+                        params[param_name] = param_schema
+                    else:
+                        # Merge constraints
+                        if 'minimum' in param_schema and 'minimum' not in params[param_name]:
+                            params[param_name]['minimum'] = param_schema['minimum']
+                        if 'maximum' in param_schema and 'maximum' not in params[param_name]:
+                            params[param_name]['maximum'] = param_schema['maximum']
+                        if 'enum' in param_schema:
+                            params[param_name]['enum'] = param_schema['enum']
+        
+        # If no parameters extracted, add a generic one
+        if not params:
+            params["input"] = {
+                "type": "object",
+                "description": "Input parameters"
+            }
+        
+        return params
+    
+    def _infer_param_from_condition(self, condition: str) -> Optional[tuple]:
+        """Infer parameter name and schema from a single condition."""
+        import re
+        
+        # Pattern: "x > 0" or "x >= 0"
+        if match := re.match(r'(\w+)\s*>=?\s*(\d+)', condition):
+            param_name = match.group(1)
+            min_val = int(match.group(2))
+            return (param_name, {
+                "type": "integer",
+                "minimum": min_val if '>=' in condition else min_val + 1,
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "x < 100" or "x <= 100"
+        if match := re.match(r'(\w+)\s*<=?\s*(\d+)', condition):
+            param_name = match.group(1)
+            max_val = int(match.group(2))
+            return (param_name, {
+                "type": "integer",
+                "maximum": max_val if '<=' in condition else max_val - 1,
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "x in [1, 2, 3]"
+        if match := re.match(r'(\w+)\s+in\s+\[(.+?)\]', condition):
+            param_name = match.group(1)
+            values = [v.strip().strip('"\"') for v in match.group(2).split(',')]
+            # Try to infer if values are integers
+            try:
+                enum_values = [int(v) for v in values]
+                param_type = "integer"
+            except ValueError:
+                enum_values = values
+                param_type = "string"
+            
+            return (param_name, {
+                "type": param_type,
+                "enum": enum_values,
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "x is string" or "x must be string"
+        if match := re.search(r'(\w+).*(?:is|must be).*string', condition, re.IGNORECASE):
+            param_name = match.group(1)
+            return (param_name, {
+                "type": "string",
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "x is list" or "x is array"
+        if match := re.search(r'(\w+).*(?:is|must be).*(list|array)', condition, re.IGNORECASE):
+            param_name = match.group(1)
+            return (param_name, {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "x is boolean"
+        if match := re.search(r'(\w+).*(?:is|must be).*bool', condition, re.IGNORECASE):
+            param_name = match.group(1)
+            return (param_name, {
+                "type": "boolean",
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Pattern: "len(x) > 0" or "length(x) > 0"
+        if match := re.search(r'len(?:gth)?\((\w+)\)\s*>\s*(\d+)', condition):
+            param_name = match.group(1)
+            min_length = int(match.group(2)) + 1
+            return (param_name, {
+                "type": "string",
+                "minLength": min_length,
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Mathematical set notation: "x ∈ ℝ" or "x ∈ ℤ"
+        if match := re.search(r'(\w+)\s*∈\s*([ℝℤℕ])', condition):
+            param_name = match.group(1)
+            set_symbol = match.group(2)
+            param_type = "number" if set_symbol == 'ℝ' else "integer"
+            return (param_name, {
+                "type": param_type,
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        # Default: try to extract parameter name
+        if match := re.match(r'(\w+)', condition):
+            param_name = match.group(1)
+            return (param_name, {
+                "type": "string",
+                "description": f"Must satisfy: {condition}"
+            })
+        
+        return None
+    
+    def _extract_response_from_postconditions(self, func: FunctionAnnotation) -> Dict[str, Any]:
+        """Extract response schema from postconditions."""
+        response = {
+            "result": {
+                "type": "object",
+                "description": "Operation result"
+            }
+        }
+        
+        if func.postconditions:
+            response["result"]["x-postconditions"] = func.postconditions
+        
+        return response
+    
+    def _map_error_to_status_code(self, error_type: str) -> int:
+        """Map error type to HTTP status code."""
+        error_mapping = {
+            "ValueError": 400,
+            "ValidationError": 400,
+            "InvalidInputError": 400,
+            "InsufficientFundsError": 400,
+            "AccountInactiveError": 403,
+            "UnauthorizedError": 401,
+            "ForbiddenError": 403,
+            "NotFoundError": 404,
+            "ConflictError": 409,
+            "InternalError": 500,
+            "TimeoutError": 504,
+        }
+        
+        return error_mapping.get(error_type, 400)
+    
+    def _generate_graphql(self, parsed: ParsedAnnotations, output_file: Optional[str] = None) -> str:
+        """Generate GraphQL schema."""
+        lines = []
+        
+        # Schema header
+        lines.append('"""')
+        lines.append(f"{parsed.module.name.replace('_', ' ').title()} API")
+        lines.append("Generated from DarkArts annotations")
+        lines.append('"""')
+        lines.append("")
+        
+        # Generate types from classes
+        for cls in parsed.module.classes:
+            lines.append(f"type {cls.name} {{")
+            lines.append(f'  """')
+            if cls.class_invariants:
+                lines.append("  Invariants:")
+                for inv in cls.class_invariants:
+                    lines.append(f"  - {inv}")
+            lines.append('  """')
+            lines.append("  id: ID!")
+            lines.append("  # TODO: Add fields based on class definition")
+            lines.append("}")
+            lines.append("")
+        
+        # Generate queries and mutations from functions
+        lines.append("type Query {")
+        all_functions = parsed.get_all_functions()
+        for func in all_functions:
+            if func.name.startswith("get_") or func.name.startswith("list_"):
+                lines.append(f'  {func.name}: String  # {func.solve or ""}')
+        lines.append("}")
+        lines.append("")
+        
+        lines.append("type Mutation {")
+        for func in all_functions:
+            if not (func.name.startswith("get_") or func.name.startswith("list_")):
+                lines.append(f'  {func.name}: String  # {func.solve or ""}')
+        lines.append("}")
+        lines.append("")
+        
+        schema = "\n".join(lines)
+        
+        if output_file:
+            output_path = Path(output_file)
+            output_path.parent.mkdir(parents=True, exist_ok=True)
+            output_path.write_text(schema, encoding='utf-8')
+        
+        return schema
+
+    def _generate_request_example(self, func: FunctionAnnotation) -> Dict[str, Any]:
+        """Generate example request from preconditions."""
+        import re
+        example = {}
+        
+        if func.preconditions:
+            for pre in func.preconditions:
+                # Pattern: "x > 0" → x = 1
+                if match := re.match(r'(\w+)\s*>\s*(\d+)', pre):
+                    param_name = match.group(1)
+                    min_val = int(match.group(2))
+                    example[param_name] = min_val + 1
+                
+                # Pattern: "x >= 0" → x = 0
+                elif match := re.match(r'(\w+)\s*>=\s*(\d+)', pre):
+                    param_name = match.group(1)
+                    min_val = int(match.group(2))
+                    example[param_name] = min_val
+                
+                # Pattern: "x in [1, 2, 3]" → x = 1
+                elif match := re.match(r'(\w+)\s+in\s+\[(.+?)\]', pre):
+                    param_name = match.group(1)
+                    values = [v.strip().strip('"\'') for v in match.group(2).split(',')]
+                    try:
+                        example[param_name] = int(values[0])
+                    except ValueError:
+                        example[param_name] = values[0]
+                
+                # Pattern: "x is string" → x = "example"
+                elif match := re.search(r'(\w+).*(?:is|must be).*string', pre, re.IGNORECASE):
+                    param_name = match.group(1)
+                    example[param_name] = "example"
+                
+                # Pattern: "x is list" → x = []
+                elif match := re.search(r'(\w+).*(?:is|must be).*(list|array)', pre, re.IGNORECASE):
+                    param_name = match.group(1)
+                    example[param_name] = ["item1", "item2"]
+                
+                # Pattern: "x is boolean" → x = true
+                elif match := re.search(r'(\w+).*(?:is|must be).*bool', pre, re.IGNORECASE):
+                    param_name = match.group(1)
+                    example[param_name] = True
+        
+        return example if example else {"input": "example"}
+    
+    def _generate_response_example(self, func: FunctionAnnotation) -> Dict[str, Any]:
+        """Generate example response from postconditions."""
+        example = {"result": "success"}
+        
+        if func.postconditions:
+            # Try to infer result structure from postconditions
+            for post in func.postconditions:
+                if "result" in post.lower():
+                    example["result"] = "computed_value"
+                    break
+        
+        return example