mcp-ticketer 0.1.30__py3-none-any.whl → 1.2.11__py3-none-any.whl

mcp_ticketer/core/mappers.py

@@ -3,7 +3,7 @@
 import logging
 from abc import ABC, abstractmethod
 from functools import lru_cache
-from typing import Any, Generic, Optional, TypeVar
+from typing import Any, Generic, TypeVar
 
 from .models import Priority, TicketState
 
@@ -27,11 +27,11 @@ class BiDirectionalDict(Generic[T, U]):
         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]:
+    def get_forward(self, key: T, default: U | None = None) -> U | None:
         """Get value by forward key."""
         return self._forward.get(key, default)
 
-    def get_reverse(self, key: U, default: Optional[T] = None) -> Optional[T]:
+    def get_reverse(self, key: U, default: T | None = None) -> T | None:
         """Get value by reverse key."""
         return self._reverse.get(key, default)
 
@@ -83,7 +83,7 @@ class StateMapper(BaseMapper):
     """Universal state mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize state mapper.
 
@@ -95,16 +95,16 @@ class StateMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
-    def get_mapping(self) -> BiDirectionalDict:
+    def get_mapping(self) -> BiDirectionalDict[TicketState, str]:
         """Get cached bidirectional state mapping."""
         if self._mapping is not None:
             return self._mapping
 
         # Default mappings by adapter type
-        default_mappings = {
+        default_mappings: dict[str, dict[TicketState, str]] = {
             "github": {
                 TicketState.OPEN: "open",
                 TicketState.IN_PROGRESS: "open",  # Uses labels
@@ -147,13 +147,16 @@ class StateMapper(BaseMapper):
             },
         }
 
-        mapping = default_mappings.get(self.adapter_type, {})
+        mapping: dict[TicketState, str] = default_mappings.get(self.adapter_type, {})
 
-        # Apply custom mappings
+        # Apply custom mappings (cast to proper type)
         if self.custom_mappings:
-            mapping.update(self.custom_mappings)
+            # custom_mappings might have str keys, need to convert to TicketState
+            for key, value in self.custom_mappings.items():
+                if isinstance(key, TicketState):
+                    mapping[key] = value
 
-        self._mapping = BiDirectionalDict(mapping)
+        self._mapping = BiDirectionalDict[TicketState, str](mapping)
         return self._mapping
 
     def to_system_state(self, adapter_state: str) -> TicketState:
@@ -168,7 +171,9 @@ class StateMapper(BaseMapper):
         """
         cache_key = f"to_system_{adapter_state}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, TicketState):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_reverse(adapter_state)
@@ -205,7 +210,9 @@ class StateMapper(BaseMapper):
         """
         cache_key = f"from_system_{system_state.value}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, str):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_forward(system_state)
@@ -229,7 +236,7 @@ class StateMapper(BaseMapper):
         """Check if adapter uses labels for extended states."""
         return self.adapter_type in ["github", "linear"]
 
-    def get_state_label(self, state: TicketState) -> Optional[str]:
+    def get_state_label(self, state: TicketState) -> str | None:
         """Get label name for extended states that require labels.
 
         Args:
@@ -258,7 +265,7 @@ class PriorityMapper(BaseMapper):
     """Universal priority mapping utility."""
 
     def __init__(
-        self, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        self, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ):
         """Initialize priority mapper.
 
@@ -270,16 +277,16 @@ class PriorityMapper(BaseMapper):
         super().__init__()
         self.adapter_type = adapter_type
         self.custom_mappings = custom_mappings or {}
-        self._mapping: Optional[BiDirectionalDict] = None
+        self._mapping: BiDirectionalDict | None = None
 
     @lru_cache(maxsize=1)
-    def get_mapping(self) -> BiDirectionalDict:
+    def get_mapping(self) -> BiDirectionalDict[Priority, Any]:
         """Get cached bidirectional priority mapping."""
         if self._mapping is not None:
             return self._mapping
 
         # Default mappings by adapter type
-        default_mappings = {
+        default_mappings: dict[str, dict[Priority, Any]] = {
             "github": {
                 Priority.CRITICAL: "P0",
                 Priority.HIGH: "P1",
@@ -306,13 +313,16 @@ class PriorityMapper(BaseMapper):
             },
         }
 
-        mapping = default_mappings.get(self.adapter_type, {})
+        mapping: dict[Priority, Any] = default_mappings.get(self.adapter_type, {})
 
-        # Apply custom mappings
+        # Apply custom mappings (cast to proper type)
         if self.custom_mappings:
-            mapping.update(self.custom_mappings)
+            # custom_mappings might have str keys, need to convert to Priority
+            for key, value in self.custom_mappings.items():
+                if isinstance(key, Priority):
+                    mapping[key] = value
 
-        self._mapping = BiDirectionalDict(mapping)
+        self._mapping = BiDirectionalDict[Priority, Any](mapping)
         return self._mapping
 
     def to_system_priority(self, adapter_priority: Any) -> Priority:
@@ -327,7 +337,9 @@ class PriorityMapper(BaseMapper):
         """
         cache_key = f"to_system_{adapter_priority}"
         if cache_key in self._cache:
-            return self._cache[cache_key]
+            cached = self._cache[cache_key]
+            if isinstance(cached, Priority):
+                return cached
 
         mapping = self.get_mapping()
         result = mapping.get_reverse(adapter_priority)
@@ -365,7 +377,7 @@ class PriorityMapper(BaseMapper):
                     ]:
                         result = Priority.LOW
                         break
-            elif isinstance(adapter_priority, (int, float)):
+            elif isinstance(adapter_priority, int | float):
                 # Handle numeric priorities (Linear-style)
                 if adapter_priority <= 1:
                     result = Priority.CRITICAL
@@ -483,7 +495,7 @@ class MapperRegistry:
 
     @classmethod
     def get_state_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> StateMapper:
         """Get or create state mapper for adapter type.
 
@@ -502,7 +514,7 @@ class MapperRegistry:
 
     @classmethod
     def get_priority_mapper(
-        cls, adapter_type: str, custom_mappings: Optional[dict[str, Any]] = None
+        cls, adapter_type: str, custom_mappings: dict[str, Any] | None = None
     ) -> PriorityMapper:
         """Get or create priority mapper for adapter type.
 
@@ -524,10 +536,10 @@ class MapperRegistry:
     @classmethod
     def clear_cache(cls) -> None:
         """Clear all mapper caches."""
-        for mapper in cls._state_mappers.values():
-            mapper.clear_cache()
-        for mapper in cls._priority_mappers.values():
-            mapper.clear_cache()
+        for state_mapper in cls._state_mappers.values():
+            state_mapper.clear_cache()
+        for priority_mapper in cls._priority_mappers.values():
+            priority_mapper.clear_cache()
 
     @classmethod
     def reset(cls) -> None:

mcp_ticketer/core/models.py

@@ -1,14 +1,50 @@
-"""Simplified Universal Ticket models using Pydantic."""
+"""Universal Ticket models using Pydantic.
+
+This module defines the core data models for the MCP Ticketer system, providing
+a unified interface across different ticket management platforms (Linear, JIRA,
+GitHub, etc.).
+
+The models follow a hierarchical structure:
+- Epic: Strategic level containers (Projects in Linear, Epics in JIRA)
+- Issue: Standard work items (Issues in GitHub, Stories in JIRA)
+- Task: Sub-work items (Sub-issues in Linear, Sub-tasks in JIRA)
+
+All models use Pydantic v2 for validation and serialization, ensuring type safety
+and consistent data handling across adapters.
+
+Example:
+    >>> from mcp_ticketer.core.models import Task, Priority, TicketState
+    >>> task = Task(
+    ...     title="Fix authentication bug",
+    ...     priority=Priority.HIGH,
+    ...     state=TicketState.IN_PROGRESS
+    ... )
+    >>> print(task.model_dump_json())
+
+"""
 
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
 
 class Priority(str, Enum):
-    """Universal priority levels."""
+    """Universal priority levels for tickets.
+
+    These priority levels are mapped to platform-specific priorities:
+    - Linear: 1 (Critical), 2 (High), 3 (Medium), 4 (Low)
+    - JIRA: Highest, High, Medium, Low
+    - GitHub: P0/critical, P1/high, P2/medium, P3/low labels
+
+    Attributes:
+        LOW: Low priority, non-urgent work
+        MEDIUM: Standard priority, default for most work
+        HIGH: High priority, should be addressed soon
+        CRITICAL: Critical priority, urgent work requiring immediate attention
+
+    """
 
     LOW = "low"
     MEDIUM = "medium"
@@ -17,7 +53,23 @@ class Priority(str, Enum):
 
 
 class TicketType(str, Enum):
-    """Ticket type hierarchy."""
+    """Ticket type hierarchy for organizing work.
+
+    Defines the three-level hierarchy used across all platforms:
+
+    Platform Mappings:
+    - Linear: Project (Epic) → Issue (Issue) → Sub-issue (Task)
+    - JIRA: Epic (Epic) → Story/Task (Issue) → Sub-task (Task)
+    - GitHub: Milestone (Epic) → Issue (Issue) → Checklist item (Task)
+    - Aitrackdown: Epic file → Issue file → Task reference
+
+    Attributes:
+        EPIC: Strategic level containers for large features or initiatives
+        ISSUE: Standard work items, the primary unit of work
+        TASK: Sub-work items, smaller pieces of an issue
+        SUBTASK: Alias for TASK for backward compatibility
+
+    """
 
     EPIC = "epic"  # Strategic level (Projects in Linear, Milestones in GitHub)
     ISSUE = "issue"  # Work item level (standard issues/tasks)
@@ -26,7 +78,34 @@ class TicketType(str, Enum):
 
 
 class TicketState(str, Enum):
-    """Universal ticket states with state machine abstraction."""
+    """Universal ticket states with workflow state machine.
+
+    Implements a standardized workflow that maps to different platform states:
+
+    State Flow:
+        OPEN → IN_PROGRESS → READY → TESTED → DONE → CLOSED
+          ↓         ↓          ↓
+        CLOSED   WAITING    BLOCKED
+                    ↓          ↓
+                IN_PROGRESS ← IN_PROGRESS
+
+    Platform Mappings:
+    - Linear: Backlog (OPEN), Started (IN_PROGRESS), Completed (DONE), Canceled (CLOSED)
+    - JIRA: To Do (OPEN), In Progress (IN_PROGRESS), Done (DONE), etc.
+    - GitHub: open (OPEN), closed (CLOSED) + labels for extended states
+    - Aitrackdown: File-based state tracking
+
+    Attributes:
+        OPEN: Initial state, work not yet started
+        IN_PROGRESS: Work is actively being done
+        READY: Work is complete and ready for review/testing
+        TESTED: Work has been tested and verified
+        DONE: Work is complete and accepted
+        WAITING: Work is paused waiting for external dependency
+        BLOCKED: Work is blocked by an impediment
+        CLOSED: Final state, work is closed/archived
+
+    """
 
     OPEN = "open"
     IN_PROGRESS = "in_progress"
@@ -39,7 +118,15 @@ class TicketState(str, Enum):
 
     @classmethod
     def valid_transitions(cls) -> dict[str, list[str]]:
-        """Define valid state transitions."""
+        """Define valid state transitions for workflow enforcement.
+
+        Returns:
+            Dictionary mapping each state to list of valid target states
+
+        Note:
+            CLOSED is a terminal state with no valid transitions
+
+        """
         return {
             cls.OPEN: [cls.IN_PROGRESS, cls.WAITING, cls.BLOCKED, cls.CLOSED],
             cls.IN_PROGRESS: [cls.READY, cls.WAITING, cls.BLOCKED, cls.OPEN],
@@ -52,23 +139,100 @@ class TicketState(str, Enum):
         }
 
     def can_transition_to(self, target: "TicketState") -> bool:
-        """Check if transition to target state is valid."""
+        """Check if transition to target state is valid.
+
+        Validates state transitions according to the defined workflow rules.
+        This prevents invalid state changes and ensures workflow integrity.
+
+        Args:
+            target: The state to transition to
+
+        Returns:
+            True if the transition is valid, False otherwise
+
+        Example:
+            >>> state = TicketState.OPEN
+            >>> state.can_transition_to(TicketState.IN_PROGRESS)
+            True
+            >>> state.can_transition_to(TicketState.DONE)
+            False
+
+        """
         return target.value in self.valid_transitions().get(self, [])
 
+    def completion_level(self) -> int:
+        """Get numeric completion level for state ordering.
+
+        Higher numbers indicate more complete states. Used for parent/child
+        state constraints where parents must be at least as complete as
+        their most complete child.
+
+        Returns:
+            Completion level (0-7)
+
+        Example:
+            >>> TicketState.OPEN.completion_level()
+            0
+            >>> TicketState.DONE.completion_level()
+            6
+            >>> TicketState.DONE.completion_level() > TicketState.IN_PROGRESS.completion_level()
+            True
+
+        """
+        levels = {
+            TicketState.OPEN: 0,  # Not started
+            TicketState.BLOCKED: 1,  # Blocked
+            TicketState.WAITING: 2,  # Waiting
+            TicketState.IN_PROGRESS: 3,  # In progress
+            TicketState.READY: 4,  # Ready for review
+            TicketState.TESTED: 5,  # Tested
+            TicketState.DONE: 6,  # Done
+            TicketState.CLOSED: 7,  # Closed (terminal)
+        }
+        return levels.get(self, 0)
+
 
 class BaseTicket(BaseModel):
-    """Base model for all ticket types."""
+    """Base model for all ticket types with universal field mapping.
+
+    Provides common fields and functionality shared across all ticket types
+    (Epic, Task, Comment). Uses Pydantic v2 for validation and serialization.
+
+    The metadata field allows adapters to store platform-specific information
+    while maintaining the universal interface.
+
+    Attributes:
+        id: Unique identifier assigned by the platform
+        title: Human-readable title (required, min 1 character)
+        description: Optional detailed description or body text
+        state: Current workflow state (defaults to OPEN)
+        priority: Priority level (defaults to MEDIUM)
+        tags: List of tags/labels for categorization
+        created_at: Timestamp when ticket was created
+        updated_at: Timestamp when ticket was last modified
+        metadata: Platform-specific data and field mappings
+
+    Example:
+        >>> ticket = BaseTicket(
+        ...     title="Fix login issue",
+        ...     description="Users cannot log in with SSO",
+        ...     priority=Priority.HIGH,
+        ...     tags=["bug", "authentication"]
+        ... )
+        >>> ticket.state = TicketState.IN_PROGRESS
+
+    """
 
     model_config = ConfigDict(use_enum_values=True)
 
-    id: Optional[str] = Field(None, description="Unique identifier")
+    id: str | None = Field(None, description="Unique identifier")
     title: str = Field(..., min_length=1, description="Ticket title")
-    description: Optional[str] = Field(None, description="Detailed description")
+    description: str | None = 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")
-    created_at: Optional[datetime] = Field(None, description="Creation timestamp")
-    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
+    updated_at: datetime | None = Field(None, description="Last update timestamp")
 
     # Metadata for field mapping to different systems
     metadata: dict[str, Any] = Field(
@@ -77,7 +241,33 @@ class BaseTicket(BaseModel):
 
 
 class Epic(BaseTicket):
-    """Epic - highest level container for work (Projects in Linear, Milestones in GitHub)."""
+    """Epic - highest level container for strategic work initiatives.
+
+    Epics represent large features, projects, or initiatives that contain
+    multiple related issues. They map to different concepts across platforms:
+
+    Platform Mappings:
+    - Linear: Projects (with issues as children)
+    - JIRA: Epics (with stories/tasks as children)
+    - GitHub: Milestones (with issues as children)
+    - Aitrackdown: Epic files (with issue references)
+
+    Epics sit at the top of the hierarchy and cannot have parent epics.
+    They can contain multiple child issues, which in turn can contain tasks.
+
+    Attributes:
+        ticket_type: Always TicketType.EPIC (frozen field)
+        child_issues: List of issue IDs that belong to this epic
+
+    Example:
+        >>> epic = Epic(
+        ...     title="User Authentication System",
+        ...     description="Complete overhaul of authentication",
+        ...     priority=Priority.HIGH
+        ... )
+        >>> epic.child_issues = ["ISSUE-123", "ISSUE-124"]
+
+    """
 
     ticket_type: TicketType = Field(
         default=TicketType.EPIC, frozen=True, description="Always EPIC type"
@@ -89,8 +279,11 @@ class Epic(BaseTicket):
     def validate_hierarchy(self) -> list[str]:
         """Validate epic hierarchy rules.
 
+        Epics are at the top of the hierarchy and have no parent constraints.
+        This method is provided for consistency with other ticket types.
+
         Returns:
-            List of validation errors (empty if valid)
+            Empty list (epics have no hierarchy constraints)
 
         """
         # Epics don't have parents in our hierarchy
@@ -98,19 +291,47 @@ class Epic(BaseTicket):
 
 
 class Task(BaseTicket):
-    """Task - individual work item (can be ISSUE or TASK type)."""
+    """Task - individual work item (can be ISSUE or TASK type).
+
+    Note: The `project` field is a synonym for `parent_epic` to provide
+    flexibility in CLI and API usage. Both fields map to the same underlying
+    value (the parent epic/project ID).
+    """
 
     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")
+    parent_issue: str | None = Field(None, description="Parent issue ID (for tasks)")
+    parent_epic: str | None = Field(
+        None,
+        description="Parent epic/project ID (for issues). Synonym: 'project'",
+    )
+    assignee: str | None = Field(None, description="Assigned user")
     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")
-    actual_hours: Optional[float] = Field(None, description="Actual time spent")
+    estimated_hours: float | None = Field(None, description="Time estimate")
+    actual_hours: float | None = Field(None, description="Actual time spent")
+
+    @property
+    def project(self) -> str | None:
+        """Synonym for parent_epic.
+
+        Returns:
+            Parent epic/project ID
+
+        """
+        return self.parent_epic
+
+    @project.setter
+    def project(self, value: str | None) -> None:
+        """Set parent_epic via project synonym.
+
+        Args:
+            value: Parent epic/project ID
+
+        """
+        self.parent_epic = value
 
     def is_epic(self) -> bool:
         """Check if this is an epic (should use Epic class instead)."""
@@ -155,23 +376,54 @@ class Comment(BaseModel):
 
     model_config = ConfigDict(use_enum_values=True)
 
-    id: Optional[str] = Field(None, description="Comment ID")
+    id: str | None = Field(None, description="Comment ID")
     ticket_id: str = Field(..., description="Parent ticket ID")
-    author: Optional[str] = Field(None, description="Comment author")
+    author: str | None = Field(None, description="Comment author")
     content: str = Field(..., min_length=1, description="Comment text")
-    created_at: Optional[datetime] = Field(None, description="Creation timestamp")
+    created_at: datetime | None = Field(None, description="Creation timestamp")
     metadata: dict[str, Any] = Field(
         default_factory=dict, description="System-specific metadata"
     )
 
 
+class Attachment(BaseModel):
+    """File attachment metadata for tickets.
+
+    Represents a file attached to a ticket across all adapters.
+    Each adapter maps its native attachment format to this model.
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str | None = Field(None, description="Attachment unique identifier")
+    ticket_id: str = Field(..., description="Parent ticket identifier")
+    filename: str = Field(..., description="Original filename")
+    url: str | None = Field(None, description="Download URL or file path")
+    content_type: str | None = Field(
+        None, description="MIME type (e.g., 'application/pdf', 'image/png')"
+    )
+    size_bytes: int | None = Field(None, description="File size in bytes")
+    created_at: datetime | None = Field(None, description="Upload timestamp")
+    created_by: str | None = Field(None, description="User who uploaded the attachment")
+    description: str | None = Field(None, description="Attachment description or notes")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict, description="Adapter-specific attachment metadata"
+    )
+
+    def __str__(self) -> str:
+        """Return string representation showing filename and size."""
+        size_str = f" ({self.size_bytes} bytes)" if self.size_bytes else ""
+        return f"Attachment({self.filename}{size_str})"
+
+
 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")
-    assignee: Optional[str] = Field(None, description="Filter by assignee")
+    query: str | None = Field(None, description="Text search query")
+    state: TicketState | None = Field(None, description="Filter by state")
+    priority: Priority | None = Field(None, description="Filter by priority")
+    tags: list[str] | None = Field(None, description="Filter by tags")
+    assignee: str | None = Field(None, description="Filter by assignee")
+    project: str | None = Field(None, description="Filter by project/epic ID or name")
     limit: int = Field(10, gt=0, le=100, description="Maximum results")
     offset: int = Field(0, ge=0, description="Result offset for pagination")