"""
Base Parser Interface

Defines the abstract interface that all API specification parsers must implement.
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, Optional, List
from dataclasses import dataclass


@dataclass
class OCPTool:
    """Represents a discovered API tool/endpoint"""
    name: str
    description: str
    method: str
    path: str
    parameters: Dict[str, Any]
    response_schema: Optional[Dict[str, Any]]
    operation_id: Optional[str] = None
    tags: Optional[List[str]] = None


@dataclass 
class OCPAPISpec:
    """Represents a parsed API specification"""
    base_url: str
    title: str
    version: str
    description: str
    tools: List[OCPTool]
    raw_spec: Dict[str, Any]
    name: Optional[str] = None


class APISpecParser(ABC):
    """
    Abstract base class for API specification parsers.
    
    All parsers must implement three methods:
    - can_parse(): Detect if this parser can handle a given spec
    - parse(): Convert the spec into an OCPAPISpec with tools
    - get_format_name(): Return a human-readable format name
    """
    
    @abstractmethod
    def can_parse(self, spec_data: Dict[str, Any]) -> bool:
        """
        Determine if this parser can handle the given specification.
        
        Args:
            spec_data: The raw specification data as a dictionary
            
        Returns:
            True if this parser can handle the format, False otherwise
        """
        pass
    
    @abstractmethod
    def parse(
        self, 
        spec_data: Dict[str, Any], 
        base_url_override: Optional[str] = None,
        include_resources: Optional[List[str]] = None,
        path_prefix: Optional[str] = None
    ) -> OCPAPISpec:
        """
        Parse the specification and extract tools.
        
        Args:
            spec_data: The raw specification data as a dictionary
            base_url_override: Optional override for the API base URL
            include_resources: Optional list of resource names to filter tools by
            path_prefix: Optional path prefix to strip before filtering
            
        Returns:
            OCPAPISpec containing extracted tools and metadata
            
        Raises:
            Exception: If parsing fails
        """
        pass
    
    @abstractmethod
    def get_format_name(self) -> str:
        """
        Get the human-readable name of the format this parser handles.
        
        Returns:
            Format name (e.g., "OpenAPI", "Postman Collection", "GraphQL")
        """
        pass
