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

mcp_ticketer/core/adapter.py

@@ -1,10 +1,16 @@
 """Base adapter abstract class for ticket systems."""
 
+from __future__ import annotations
+
 import builtins
 from abc import ABC, abstractmethod
-from typing import Any, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
 from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
+from .state_matcher import get_state_matcher
+
+if TYPE_CHECKING:
+    from .models import Attachment
 
 # Generic type for tickets
 T = TypeVar("T", Epic, Task)
@@ -17,17 +23,52 @@ class BaseAdapter(ABC, Generic[T]):
         """Initialize adapter with configuration.
 
         Args:
+        ----
             config: Adapter-specific configuration dictionary
 
         """
         self.config = config
         self._state_mapping = self._get_state_mapping()
 
+    @property
+    def adapter_type(self) -> str:
+        """Return lowercase adapter type identifier.
+
+        This identifier is used in MCP responses to show which adapter
+        handled the operation (e.g., "linear", "github", "jira", "asana").
+
+        Returns:
+        -------
+            Lowercase adapter type (e.g., "linear", "github")
+
+        """
+        # Extract adapter type from class name
+        # LinearAdapter -> linear, GitHubAdapter -> github
+        class_name = self.__class__.__name__
+        if class_name.endswith("Adapter"):
+            adapter_name = class_name[: -len("Adapter")]
+        else:
+            adapter_name = class_name
+
+        return adapter_name.lower()
+
+    @property
+    def adapter_display_name(self) -> str:
+        """Return human-readable adapter name.
+
+        Returns:
+        -------
+            Title-cased adapter name (e.g., "Linear", "Github", "Jira")
+
+        """
+        return self.adapter_type.title()
+
     @abstractmethod
     def _get_state_mapping(self) -> dict[TicketState, str]:
         """Get mapping from universal states to system-specific states.
 
         Returns:
+        -------
             Dictionary mapping TicketState to system-specific state strings
 
         """
@@ -38,6 +79,7 @@ class BaseAdapter(ABC, Generic[T]):
         """Validate that required credentials are present.
 
         Returns:
+        -------
             (is_valid, error_message) - Tuple of validation result and error message
 
         """
@@ -48,36 +90,42 @@ class BaseAdapter(ABC, Generic[T]):
         """Create a new ticket.
 
         Args:
+        ----
             ticket: Ticket to create (Epic or Task)
 
         Returns:
+        -------
             Created ticket with ID populated
 
         """
         pass
 
     @abstractmethod
-    async def read(self, ticket_id: str) -> Optional[T]:
+    async def read(self, ticket_id: str) -> T | None:
         """Read a ticket by ID.
 
         Args:
+        ----
             ticket_id: Unique ticket identifier
 
         Returns:
+        -------
             Ticket if found, None otherwise
 
         """
         pass
 
     @abstractmethod
-    async def update(self, ticket_id: str, updates: dict[str, Any]) -> Optional[T]:
+    async def update(self, ticket_id: str, updates: dict[str, Any]) -> T | None:
         """Update a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             updates: Fields to update
 
         Returns:
+        -------
             Updated ticket if successful, None otherwise
 
         """
@@ -88,9 +136,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Delete a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             True if deleted, False otherwise
 
         """
@@ -98,16 +148,18 @@ class BaseAdapter(ABC, Generic[T]):
 
     @abstractmethod
     async def list(
-        self, limit: int = 10, offset: int = 0, filters: Optional[dict[str, Any]] = None
+        self, limit: int = 10, offset: int = 0, filters: dict[str, Any] | None = None
     ) -> list[T]:
         """List tickets with pagination and filters.
 
         Args:
+        ----
             limit: Maximum number of tickets
             offset: Skip this many tickets
             filters: Optional filter criteria
 
         Returns:
+        -------
             List of tickets matching criteria
 
         """
@@ -118,9 +170,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Search tickets using advanced query.
 
         Args:
+        ----
             query: Search parameters
 
         Returns:
+        -------
             List of tickets matching search criteria
 
         """
@@ -129,14 +183,16 @@ class BaseAdapter(ABC, Generic[T]):
     @abstractmethod
     async def transition_state(
         self, ticket_id: str, target_state: TicketState
-    ) -> Optional[T]:
+    ) -> T | None:
         """Transition ticket to a new state.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             target_state: Target state
 
         Returns:
+        -------
             Updated ticket if transition successful, None otherwise
 
         """
@@ -147,9 +203,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Add a comment to a ticket.
 
         Args:
+        ----
             comment: Comment to add
 
         Returns:
+        -------
             Created comment with ID populated
 
         """
@@ -162,11 +220,13 @@ class BaseAdapter(ABC, Generic[T]):
         """Get comments for a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             limit: Maximum number of comments
             offset: Skip this many comments
 
         Returns:
+        -------
             List of comments for the ticket
 
         """
@@ -176,9 +236,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Map universal state to system-specific state.
 
         Args:
+        ----
             state: Universal ticket state
 
         Returns:
+        -------
             System-specific state string
 
         """
@@ -188,31 +250,88 @@ class BaseAdapter(ABC, Generic[T]):
         """Map system-specific state to universal state.
 
         Args:
+        ----
             system_state: System-specific state string
 
         Returns:
+        -------
             Universal ticket state
 
         """
         reverse_mapping = {v: k for k, v in self._state_mapping.items()}
         return reverse_mapping.get(system_state, TicketState.OPEN)
 
+    def get_available_states(self) -> list[str]:
+        """Get list of adapter-specific available states.
+
+        Returns adapter-specific state names that can be used for
+        semantic state matching. Override in subclasses to provide
+        platform-specific state names.
+
+        Returns:
+        -------
+            List of adapter-specific state names
+
+        Example:
+        -------
+            >>> # Linear adapter override
+            >>> def get_available_states(self):
+            ...     return ["Backlog", "Todo", "In Progress", "Done", "Canceled"]
+
+        """
+        # Default: return universal state values
+        return [state.value for state in TicketState]
+
+    def resolve_state(self, user_input: str) -> TicketState:
+        """Resolve user input to universal state using semantic matcher.
+
+        Uses the semantic state matcher to interpret natural language
+        inputs and resolve them to universal TicketState values.
+
+        Args:
+        ----
+            user_input: Natural language state input (e.g., "working on it")
+
+        Returns:
+        -------
+            Resolved universal TicketState
+
+        Example:
+        -------
+            >>> adapter = get_adapter()
+            >>> state = adapter.resolve_state("working on it")
+            >>> print(state)
+            TicketState.IN_PROGRESS
+
+        """
+        matcher = get_state_matcher()
+        adapter_states = self.get_available_states()
+        result = matcher.match_state(user_input, adapter_states)
+        return result.state
+
     async def validate_transition(
         self, ticket_id: str, target_state: TicketState
     ) -> bool:
         """Validate if state transition is allowed.
 
+        Validates both workflow rules and parent/child state constraints:
+        - Parent issues must remain at least as complete as their most complete child
+        - Standard workflow transitions must be valid
+
         Args:
+        ----
             ticket_id: Ticket identifier
             target_state: Target state
 
         Returns:
+        -------
             True if transition is valid
 
         """
         ticket = await self.read(ticket_id)
         if not ticket:
             return False
+
         # Handle case where state might be stored as string due to use_enum_values=True
         current_state = ticket.state
         if isinstance(current_state, str):
@@ -220,21 +339,51 @@ class BaseAdapter(ABC, Generic[T]):
                 current_state = TicketState(current_state)
             except ValueError:
                 return False
-        return current_state.can_transition_to(target_state)
+
+        # Check workflow transition validity
+        if not current_state.can_transition_to(target_state):
+            return False
+
+        # Check parent/child state constraint
+        # If this ticket has children, ensure target state >= max child state
+        if isinstance(ticket, Task):
+            # Get all children
+            children = await self.list_tasks_by_issue(ticket_id)
+            if children:
+                # Find max child completion level
+                max_child_level = 0
+                for child in children:
+                    child_state = child.state
+                    if isinstance(child_state, str):
+                        try:
+                            child_state = TicketState(child_state)
+                        except ValueError:
+                            continue
+                    max_child_level = max(
+                        max_child_level, child_state.completion_level()
+                    )
+
+                # Target state must be at least as complete as most complete child
+                if target_state.completion_level() < max_child_level:
+                    return False
+
+        return True
 
     # Epic/Issue/Task Hierarchy Methods
 
     async def create_epic(
-        self, title: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Epic]:
+        self, title: str, description: str | None = None, **kwargs: Any
+    ) -> Epic | None:
         """Create epic (top-level grouping).
 
         Args:
+        ----
             title: Epic title
             description: Epic description
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created epic or None if failed
 
         """
@@ -249,13 +398,15 @@ class BaseAdapter(ABC, Generic[T]):
             return result
         return None
 
-    async def get_epic(self, epic_id: str) -> Optional[Epic]:
+    async def get_epic(self, epic_id: str) -> Epic | None:
         """Get epic by ID.
 
         Args:
+        ----
             epic_id: Epic identifier
 
         Returns:
+        -------
             Epic if found, None otherwise
 
         """
@@ -265,13 +416,15 @@ class BaseAdapter(ABC, Generic[T]):
             return result
         return None
 
-    async def list_epics(self, **kwargs) -> builtins.list[Epic]:
+    async def list_epics(self, **kwargs: Any) -> builtins.list[Epic]:
         """List all epics.
 
         Args:
+        ----
             **kwargs: Adapter-specific filter parameters
 
         Returns:
+        -------
             List of epics
 
         """
@@ -284,19 +437,21 @@ class BaseAdapter(ABC, Generic[T]):
     async def create_issue(
         self,
         title: str,
-        description: Optional[str] = None,
-        epic_id: Optional[str] = None,
-        **kwargs,
-    ) -> Optional[Task]:
+        description: str | None = None,
+        epic_id: str | None = None,
+        **kwargs: Any,
+    ) -> Task | None:
         """Create issue, optionally linked to epic.
 
         Args:
+        ----
             title: Issue title
             description: Issue description
             epic_id: Optional parent epic ID
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created issue or None if failed
 
         """
@@ -313,9 +468,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all issues in epic.
 
         Args:
+        ----
             epic_id: Epic identifier
 
         Returns:
+        -------
             List of issues belonging to epic
 
         """
@@ -325,20 +482,23 @@ class BaseAdapter(ABC, Generic[T]):
         return [r for r in results if isinstance(r, Task) and r.is_issue()]
 
     async def create_task(
-        self, title: str, parent_id: str, description: Optional[str] = None, **kwargs
-    ) -> Optional[Task]:
+        self, title: str, parent_id: str, description: str | None = None, **kwargs: Any
+    ) -> Task | None:
         """Create task as sub-ticket of parent issue.
 
         Args:
+        ----
             title: Task title
             parent_id: Required parent issue ID
             description: Task description
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created task or None if failed
 
         Raises:
+        ------
             ValueError: If parent_id is not provided
 
         """
@@ -364,9 +524,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all tasks under an issue.
 
         Args:
+        ----
             issue_id: Issue identifier
 
         Returns:
+        -------
             List of tasks belonging to issue
 
         """
@@ -375,6 +537,78 @@ class BaseAdapter(ABC, Generic[T]):
         results = await self.list(filters=filters)
         return [r for r in results if isinstance(r, Task) and r.is_task()]
 
+    # Attachment methods
+    async def add_attachment(
+        self,
+        ticket_id: str,
+        file_path: str,
+        description: str | None = None,
+    ) -> Attachment:
+        """Attach a file to a ticket.
+
+        Args:
+        ----
+            ticket_id: Ticket identifier
+            file_path: Local file path to upload
+            description: Optional attachment description
+
+        Returns:
+        -------
+            Created Attachment with metadata
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support attachments
+            FileNotFoundError: If file doesn't exist
+            ValueError: If ticket doesn't exist or upload fails
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments. "
+            "Use comments to reference external files instead."
+        )
+
+    async def get_attachments(self, ticket_id: str) -> list[Attachment]:
+        """Get all attachments for a ticket.
+
+        Args:
+        ----
+            ticket_id: Ticket identifier
+
+        Returns:
+        -------
+            List of attachments (empty if none or not supported)
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support file attachments."
+        )
+
+    async def delete_attachment(
+        self,
+        ticket_id: str,
+        attachment_id: str,
+    ) -> bool:
+        """Delete an attachment (optional implementation).
+
+        Args:
+        ----
+            ticket_id: Ticket identifier
+            attachment_id: Attachment identifier
+
+        Returns:
+        -------
+            True if deleted, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support deletion
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support attachment deletion."
+        )
+
     async def close(self) -> None:
         """Close adapter and cleanup resources."""
         pass