mcp-ticketer 0.1.21__py3-none-any.whl → 0.1.23__py3-none-any.whl

mcp_ticketer/core/mappers.py

@@ -1,31 +1,31 @@
 """Centralized mapping utilities for state and priority conversions."""
 
 import logging
-from typing import Dict, List, Optional, Any, TypeVar, Generic, Callable
-from functools import lru_cache
 from abc import ABC, abstractmethod
-from enum import Enum
+from functools import lru_cache
+from typing import Any, Generic, Optional, TypeVar
 
-from .models import TicketState, Priority
+from .models import Priority, TicketState
 
 logger = logging.getLogger(__name__)
 
-T = TypeVar('T')
-U = TypeVar('U')
+T = TypeVar("T")
+U = TypeVar("U")
 
 
 class BiDirectionalDict(Generic[T, U]):
     """Bidirectional dictionary for efficient lookups in both directions."""
 
-    def __init__(self, mapping: Dict[T, U]):
+    def __init__(self, mapping: dict[T, U]):
         """Initialize with forward mapping.
 
         Args:
             mapping: Forward mapping dictionary
+
         """
-        self._forward: Dict[T, U] = mapping.copy()
-        self._reverse: Dict[U, T] = {v: k for k, v in mapping.items()}
-        self._cache: Dict[str, Any] = {}
+        self._forward: dict[T, U] = mapping.copy()
+        self._reverse: dict[U, T] = {v: k for k, v in mapping.items()}
+        self._cache: dict[str, Any] = {}
 
     def get_forward(self, key: T, default: Optional[U] = None) -> Optional[U]:
         """Get value by forward key."""
@@ -43,15 +43,15 @@ class BiDirectionalDict(Generic[T, U]):
         """Check if reverse key exists."""
         return key in self._reverse
 
-    def forward_keys(self) -> List[T]:
+    def forward_keys(self) -> list[T]:
         """Get all forward keys."""
         return list(self._forward.keys())
 
-    def reverse_keys(self) -> List[U]:
+    def reverse_keys(self) -> list[U]:
         """Get all reverse keys."""
         return list(self._reverse.keys())
 
-    def items(self) -> List[tuple[T, U]]:
+    def items(self) -> list[tuple[T, U]]:
         """Get all key-value pairs."""
         return list(self._forward.items())
 
@@ -64,9 +64,10 @@ class BaseMapper(ABC):
 
         Args:
             cache_size: Size of LRU cache for mapping results
+
         """
         self.cache_size = cache_size
-        self._cache: Dict[str, Any] = {}
+        self._cache: dict[str, Any] = {}
 
     @abstractmethod
     def get_mapping(self) -> BiDirectionalDict:
@@ -81,12 +82,15 @@ class BaseMapper(ABC):
 class StateMapper(BaseMapper):
     """Universal state mapping utility."""
 
-    def __init__(self, adapter_type: str, custom_mappings: Optional[Dict[str, Any]] = None):
+    def __init__(
+        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+    ):
         """Initialize state mapper.
 
         Args:
             adapter_type: Type of adapter (github, jira, linear, etc.)
             custom_mappings: Custom state mappings to override defaults
+
         """
         super().__init__()
         self.adapter_type = adapter_type
@@ -104,11 +108,11 @@ class StateMapper(BaseMapper):
             "github": {
                 TicketState.OPEN: "open",
                 TicketState.IN_PROGRESS: "open",  # Uses labels
-                TicketState.READY: "open",        # Uses labels
-                TicketState.TESTED: "open",       # Uses labels
+                TicketState.READY: "open",  # Uses labels
+                TicketState.TESTED: "open",  # Uses labels
                 TicketState.DONE: "closed",
-                TicketState.WAITING: "open",      # Uses labels
-                TicketState.BLOCKED: "open",      # Uses labels
+                TicketState.WAITING: "open",  # Uses labels
+                TicketState.BLOCKED: "open",  # Uses labels
                 TicketState.CLOSED: "closed",
             },
             "jira": {
@@ -124,8 +128,8 @@ class StateMapper(BaseMapper):
             "linear": {
                 TicketState.OPEN: "backlog",
                 TicketState.IN_PROGRESS: "started",
-                TicketState.READY: "started",      # Uses labels
-                TicketState.TESTED: "started",     # Uses labels
+                TicketState.READY: "started",  # Uses labels
+                TicketState.TESTED: "started",  # Uses labels
                 TicketState.DONE: "completed",
                 TicketState.WAITING: "unstarted",  # Uses labels
                 TicketState.BLOCKED: "unstarted",  # Uses labels
@@ -140,7 +144,7 @@ class StateMapper(BaseMapper):
                 TicketState.WAITING: "waiting",
                 TicketState.BLOCKED: "blocked",
                 TicketState.CLOSED: "closed",
-            }
+            },
         }
 
         mapping = default_mappings.get(self.adapter_type, {})
@@ -160,6 +164,7 @@ class StateMapper(BaseMapper):
 
         Returns:
             Universal ticket state
+
         """
         cache_key = f"to_system_{adapter_state}"
         if cache_key in self._cache:
@@ -172,12 +177,17 @@ class StateMapper(BaseMapper):
             # Fallback: try case-insensitive matching
             adapter_state_lower = adapter_state.lower()
             for universal_state, system_state in mapping.items():
-                if isinstance(system_state, str) and system_state.lower() == adapter_state_lower:
+                if (
+                    isinstance(system_state, str)
+                    and system_state.lower() == adapter_state_lower
+                ):
                     result = universal_state
                     break
 
         if result is None:
-            logger.warning(f"Unknown {self.adapter_type} state: {adapter_state}, defaulting to OPEN")
+            logger.warning(
+                f"Unknown {self.adapter_type} state: {adapter_state}, defaulting to OPEN"
+            )
             result = TicketState.OPEN
 
         self._cache[cache_key] = result
@@ -191,6 +201,7 @@ class StateMapper(BaseMapper):
 
         Returns:
             State in adapter format
+
         """
         cache_key = f"from_system_{system_state.value}"
         if cache_key in self._cache:
@@ -200,7 +211,9 @@ class StateMapper(BaseMapper):
         result = mapping.get_forward(system_state)
 
         if result is None:
-            logger.warning(f"No {self.adapter_type} mapping for state: {system_state}, using default")
+            logger.warning(
+                f"No {self.adapter_type} mapping for state: {system_state}, using default"
+            )
             # Fallback to first available state
             available_states = mapping.reverse_keys()
             result = available_states[0] if available_states else "open"
@@ -208,7 +221,7 @@ class StateMapper(BaseMapper):
         self._cache[cache_key] = result
         return result
 
-    def get_available_states(self) -> List[str]:
+    def get_available_states(self) -> list[str]:
         """Get all available adapter states."""
         return self.get_mapping().reverse_keys()
 
@@ -224,6 +237,7 @@ class StateMapper(BaseMapper):
 
         Returns:
             Label name if state requires a label, None otherwise
+
         """
         if not self.supports_state_labels():
             return None
@@ -243,12 +257,15 @@ class StateMapper(BaseMapper):
 class PriorityMapper(BaseMapper):
     """Universal priority mapping utility."""
 
-    def __init__(self, adapter_type: str, custom_mappings: Optional[Dict[str, Any]] = None):
+    def __init__(
+        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+    ):
         """Initialize priority mapper.
 
         Args:
             adapter_type: Type of adapter (github, jira, linear, etc.)
             custom_mappings: Custom priority mappings to override defaults
+
         """
         super().__init__()
         self.adapter_type = adapter_type
@@ -286,7 +303,7 @@ class PriorityMapper(BaseMapper):
                 Priority.HIGH: "high",
                 Priority.MEDIUM: "medium",
                 Priority.LOW: "low",
-            }
+            },
         }
 
         mapping = default_mappings.get(self.adapter_type, {})
@@ -306,6 +323,7 @@ class PriorityMapper(BaseMapper):
 
         Returns:
             Universal priority
+
         """
         cache_key = f"to_system_{adapter_priority}"
         if cache_key in self._cache:
@@ -319,18 +337,32 @@ class PriorityMapper(BaseMapper):
             if isinstance(adapter_priority, str):
                 adapter_priority_lower = adapter_priority.lower()
                 for universal_priority, system_priority in mapping.items():
-                    if isinstance(system_priority, str) and system_priority.lower() == adapter_priority_lower:
+                    if (
+                        isinstance(system_priority, str)
+                        and system_priority.lower() == adapter_priority_lower
+                    ):
                         result = universal_priority
                         break
                     # Check for common priority patterns
-                    elif ("critical" in adapter_priority_lower or "urgent" in adapter_priority_lower or
-                          "highest" in adapter_priority_lower or adapter_priority_lower in ["p0", "0"]):
+                    elif (
+                        "critical" in adapter_priority_lower
+                        or "urgent" in adapter_priority_lower
+                        or "highest" in adapter_priority_lower
+                        or adapter_priority_lower in ["p0", "0"]
+                    ):
                         result = Priority.CRITICAL
                         break
-                    elif ("high" in adapter_priority_lower or adapter_priority_lower in ["p1", "1"]):
+                    elif "high" in adapter_priority_lower or adapter_priority_lower in [
+                        "p1",
+                        "1",
+                    ]:
                         result = Priority.HIGH
                         break
-                    elif ("low" in adapter_priority_lower or adapter_priority_lower in ["p3", "3", "lowest"]):
+                    elif "low" in adapter_priority_lower or adapter_priority_lower in [
+                        "p3",
+                        "3",
+                        "lowest",
+                    ]:
                         result = Priority.LOW
                         break
             elif isinstance(adapter_priority, (int, float)):
@@ -345,7 +377,9 @@ class PriorityMapper(BaseMapper):
                     result = Priority.MEDIUM
 
         if result is None:
-            logger.warning(f"Unknown {self.adapter_type} priority: {adapter_priority}, defaulting to MEDIUM")
+            logger.warning(
+                f"Unknown {self.adapter_type} priority: {adapter_priority}, defaulting to MEDIUM"
+            )
             result = Priority.MEDIUM
 
         self._cache[cache_key] = result
@@ -359,6 +393,7 @@ class PriorityMapper(BaseMapper):
 
         Returns:
             Priority in adapter format
+
         """
         cache_key = f"from_system_{system_priority.value}"
         if cache_key in self._cache:
@@ -368,7 +403,9 @@ class PriorityMapper(BaseMapper):
         result = mapping.get_forward(system_priority)
 
         if result is None:
-            logger.warning(f"No {self.adapter_type} mapping for priority: {system_priority}")
+            logger.warning(
+                f"No {self.adapter_type} mapping for priority: {system_priority}"
+            )
             # Fallback based on adapter type
             fallback_mappings = {
                 "github": "P2",
@@ -381,11 +418,11 @@ class PriorityMapper(BaseMapper):
         self._cache[cache_key] = result
         return result
 
-    def get_available_priorities(self) -> List[Any]:
+    def get_available_priorities(self) -> list[Any]:
         """Get all available adapter priorities."""
         return self.get_mapping().reverse_keys()
 
-    def get_priority_labels(self, priority: Priority) -> List[str]:
+    def get_priority_labels(self, priority: Priority) -> list[str]:
         """Get possible label names for a priority (GitHub-style).
 
         Args:
@@ -393,6 +430,7 @@ class PriorityMapper(BaseMapper):
 
         Returns:
             List of possible label names
+
         """
         if self.adapter_type != "github":
             return []
@@ -407,7 +445,7 @@ class PriorityMapper(BaseMapper):
 
         return priority_labels.get(priority, [])
 
-    def detect_priority_from_labels(self, labels: List[str]) -> Priority:
+    def detect_priority_from_labels(self, labels: list[str]) -> Priority:
         """Detect priority from issue labels (GitHub-style).
 
         Args:
@@ -415,6 +453,7 @@ class PriorityMapper(BaseMapper):
 
         Returns:
             Detected priority
+
         """
         if self.adapter_type != "github":
             return Priority.MEDIUM
@@ -422,7 +461,12 @@ class PriorityMapper(BaseMapper):
         labels_lower = [label.lower() for label in labels]
 
         # Check each priority level
-        for priority in [Priority.CRITICAL, Priority.HIGH, Priority.LOW, Priority.MEDIUM]:
+        for priority in [
+            Priority.CRITICAL,
+            Priority.HIGH,
+            Priority.LOW,
+            Priority.MEDIUM,
+        ]:
             priority_labels = self.get_priority_labels(priority)
             for priority_label in priority_labels:
                 if priority_label.lower() in labels_lower:
@@ -434,14 +478,12 @@ class PriorityMapper(BaseMapper):
 class MapperRegistry:
     """Registry for managing mappers across different adapters."""
 
-    _state_mappers: Dict[str, StateMapper] = {}
-    _priority_mappers: Dict[str, PriorityMapper] = {}
+    _state_mappers: dict[str, StateMapper] = {}
+    _priority_mappers: dict[str, PriorityMapper] = {}
 
     @classmethod
     def get_state_mapper(
-        self,
-        adapter_type: str,
-        custom_mappings: Optional[Dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
     ) -> StateMapper:
         """Get or create state mapper for adapter type.
 
@@ -451,17 +493,16 @@ class MapperRegistry:
 
         Returns:
             State mapper instance
+
         """
         cache_key = f"{adapter_type}_{hash(str(custom_mappings))}"
-        if cache_key not in self._state_mappers:
-            self._state_mappers[cache_key] = StateMapper(adapter_type, custom_mappings)
-        return self._state_mappers[cache_key]
+        if cache_key not in cls._state_mappers:
+            cls._state_mappers[cache_key] = StateMapper(adapter_type, custom_mappings)
+        return cls._state_mappers[cache_key]
 
     @classmethod
     def get_priority_mapper(
-        self,
-        adapter_type: str,
-        custom_mappings: Optional[Dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
     ) -> PriorityMapper:
         """Get or create priority mapper for adapter type.
 
@@ -471,11 +512,14 @@ class MapperRegistry:
 
         Returns:
             Priority mapper instance
+
         """
         cache_key = f"{adapter_type}_{hash(str(custom_mappings))}"
-        if cache_key not in self._priority_mappers:
-            self._priority_mappers[cache_key] = PriorityMapper(adapter_type, custom_mappings)
-        return self._priority_mappers[cache_key]
+        if cache_key not in cls._priority_mappers:
+            cls._priority_mappers[cache_key] = PriorityMapper(
+                adapter_type, custom_mappings
+            )
+        return cls._priority_mappers[cache_key]
 
     @classmethod
     def clear_cache(cls) -> None:
@@ -489,4 +533,4 @@ class MapperRegistry:
     def reset(cls) -> None:
         """Reset all mappers."""
         cls._state_mappers.clear()
-        cls._priority_mappers.clear()
+        cls._priority_mappers.clear()

mcp_ticketer/core/models.py

@@ -2,12 +2,14 @@
 
 from datetime import datetime
 from enum import Enum
-from typing import Optional, Dict, Any, List
-from pydantic import BaseModel, Field, ConfigDict
+from typing import Any, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class Priority(str, Enum):
     """Universal priority levels."""
+
     LOW = "low"
     MEDIUM = "medium"
     HIGH = "high"
@@ -16,14 +18,16 @@ class Priority(str, Enum):
 
 class TicketType(str, Enum):
     """Ticket type hierarchy."""
-    EPIC = "epic"        # Strategic level (Projects in Linear, Milestones in GitHub)
-    ISSUE = "issue"      # Work item level (standard issues/tasks)
-    TASK = "task"        # Sub-task level (sub-issues, checkboxes)
+
+    EPIC = "epic"  # Strategic level (Projects in Linear, Milestones in GitHub)
+    ISSUE = "issue"  # Work item level (standard issues/tasks)
+    TASK = "task"  # Sub-task level (sub-issues, checkboxes)
     SUBTASK = "subtask"  # Alias for task (for clarity)
 
 
 class TicketState(str, Enum):
     """Universal ticket states with state machine abstraction."""
+
     OPEN = "open"
     IN_PROGRESS = "in_progress"
     READY = "ready"
@@ -34,7 +38,7 @@ class TicketState(str, Enum):
     CLOSED = "closed"
 
     @classmethod
-    def valid_transitions(cls) -> Dict[str, List[str]]:
+    def valid_transitions(cls) -> dict[str, list[str]]:
         """Define valid state transitions."""
         return {
             cls.OPEN: [cls.IN_PROGRESS, cls.WAITING, cls.BLOCKED, cls.CLOSED],
@@ -54,6 +58,7 @@ class TicketState(str, Enum):
 
 class BaseTicket(BaseModel):
     """Base model for all ticket types."""
+
     model_config = ConfigDict(use_enum_values=True)
 
     id: Optional[str] = Field(None, description="Unique identifier")
@@ -61,30 +66,32 @@ class BaseTicket(BaseModel):
     description: Optional[str] = Field(None, description="Detailed description")
     state: TicketState = Field(TicketState.OPEN, description="Current state")
     priority: Priority = Field(Priority.MEDIUM, description="Priority level")
-    tags: List[str] = Field(default_factory=list, description="Tags/labels")
+    tags: list[str] = Field(default_factory=list, description="Tags/labels")
     created_at: Optional[datetime] = Field(None, description="Creation timestamp")
     updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
 
     # Metadata for field mapping to different systems
-    metadata: Dict[str, Any] = Field(
-        default_factory=dict,
-        description="System-specific metadata and field mappings"
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="System-specific metadata and field mappings"
     )
 
 
 class Epic(BaseTicket):
     """Epic - highest level container for work (Projects in Linear, Milestones in GitHub)."""
-    ticket_type: TicketType = Field(default=TicketType.EPIC, frozen=True, description="Always EPIC type")
-    child_issues: List[str] = Field(
-        default_factory=list,
-        description="IDs of child issues"
+
+    ticket_type: TicketType = Field(
+        default=TicketType.EPIC, frozen=True, description="Always EPIC type"
+    )
+    child_issues: list[str] = Field(
+        default_factory=list, description="IDs of child issues"
     )
 
-    def validate_hierarchy(self) -> List[str]:
+    def validate_hierarchy(self) -> list[str]:
         """Validate epic hierarchy rules.
 
         Returns:
             List of validation errors (empty if valid)
+
         """
         # Epics don't have parents in our hierarchy
         return []
@@ -92,11 +99,14 @@ class Epic(BaseTicket):
 
 class Task(BaseTicket):
     """Task - individual work item (can be ISSUE or TASK type)."""
-    ticket_type: TicketType = Field(default=TicketType.ISSUE, description="Ticket type in hierarchy")
+
+    ticket_type: TicketType = Field(
+        default=TicketType.ISSUE, description="Ticket type in hierarchy"
+    )
     parent_issue: Optional[str] = Field(None, description="Parent issue ID (for tasks)")
     parent_epic: Optional[str] = Field(None, description="Parent epic ID (for issues)")
     assignee: Optional[str] = Field(None, description="Assigned user")
-    children: List[str] = Field(default_factory=list, description="Child task IDs")
+    children: list[str] = Field(default_factory=list, description="Child task IDs")
 
     # Additional fields common across systems
     estimated_hours: Optional[float] = Field(None, description="Time estimate")
@@ -114,11 +124,12 @@ class Task(BaseTicket):
         """Check if this is a sub-task."""
         return self.ticket_type in (TicketType.TASK, TicketType.SUBTASK)
 
-    def validate_hierarchy(self) -> List[str]:
+    def validate_hierarchy(self) -> list[str]:
         """Validate ticket hierarchy rules.
 
         Returns:
             List of validation errors (empty if valid)
+
         """
         errors = []
 
@@ -132,13 +143,16 @@ class Task(BaseTicket):
 
         # Tasks should not have both parent_issue and parent_epic
         if self.is_task() and self.parent_epic:
-            errors.append("Tasks should only have parent_issue, not parent_epic (epic comes from parent issue)")
+            errors.append(
+                "Tasks should only have parent_issue, not parent_epic (epic comes from parent issue)"
+            )
 
         return errors
 
 
 class Comment(BaseModel):
     """Comment on a ticket."""
+
     model_config = ConfigDict(use_enum_values=True)
 
     id: Optional[str] = Field(None, description="Comment ID")
@@ -146,18 +160,18 @@ class Comment(BaseModel):
     author: Optional[str] = Field(None, description="Comment author")
     content: str = Field(..., min_length=1, description="Comment text")
     created_at: Optional[datetime] = Field(None, description="Creation timestamp")
-    metadata: Dict[str, Any] = Field(
-        default_factory=dict,
-        description="System-specific metadata"
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="System-specific metadata"
     )
 
 
 class SearchQuery(BaseModel):
     """Search query parameters."""
+
     query: Optional[str] = Field(None, description="Text search query")
     state: Optional[TicketState] = Field(None, description="Filter by state")
     priority: Optional[Priority] = Field(None, description="Filter by priority")
-    tags: Optional[List[str]] = Field(None, description="Filter by tags")
+    tags: Optional[list[str]] = Field(None, description="Filter by tags")
     assignee: Optional[str] = Field(None, description="Filter by assignee")
     limit: int = Field(10, gt=0, le=100, description="Maximum results")
-    offset: int = Field(0, ge=0, description="Result offset for pagination")
+    offset: int = Field(0, ge=0, description="Result offset for pagination")