mcp-ticketer 0.3.0__py3-none-any.whl → 2.2.9__py3-none-any.whl

mcp_ticketer/core/adapter.py

@@ -1,10 +1,29 @@
 """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 .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from .models import (
+    Comment,
+    Epic,
+    Milestone,
+    Project,
+    ProjectScope,
+    ProjectState,
+    ProjectStatistics,
+    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 +36,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 +92,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 +103,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 +149,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Delete a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             True if deleted, False otherwise
 
         """
@@ -98,16 +161,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 +183,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Search tickets using advanced query.
 
         Args:
+        ----
             query: Search parameters
 
         Returns:
+        -------
             List of tickets matching search criteria
 
         """
@@ -129,14 +196,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 +216,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 +233,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 +249,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 +263,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 +352,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 +411,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 +429,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 +450,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 +481,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 +495,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 +537,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 +550,431 @@ 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
+
+    # Milestone Operations (Phase 1 - Abstract methods)
+
+    @abstractmethod
+    async def milestone_create(
+        self,
+        name: str,
+        target_date: datetime | None = None,
+        labels: list[str] | None = None,
+        description: str = "",
+        project_id: str | None = None,
+    ) -> Milestone:
+        """Create a new milestone.
+
+        Args:
+        ----
+            name: Milestone name
+            target_date: Target completion date (ISO format: YYYY-MM-DD)
+            labels: Labels that define this milestone
+            description: Milestone description
+            project_id: Associated project ID
+
+        Returns:
+        -------
+            Created Milestone object
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_get(self, milestone_id: str) -> Milestone | None:
+        """Get milestone by ID with progress calculation.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+
+        Returns:
+        -------
+            Milestone object with calculated progress, None if not found
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_list(
+        self,
+        project_id: str | None = None,
+        state: str | None = None,
+    ) -> builtins.list[Milestone]:
+        """List milestones with optional filters.
+
+        Args:
+        ----
+            project_id: Filter by project
+            state: Filter by state (open, active, completed, closed)
+
+        Returns:
+        -------
+            List of Milestone objects
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_update(
+        self,
+        milestone_id: str,
+        name: str | None = None,
+        target_date: datetime | None = None,
+        state: str | None = None,
+        labels: list[str] | None = None,
+        description: str | None = None,
+    ) -> Milestone | None:
+        """Update milestone properties.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            name: New name (optional)
+            target_date: New target date (optional)
+            state: New state (optional)
+            labels: New labels (optional)
+            description: New description (optional)
+
+        Returns:
+        -------
+            Updated Milestone object, None if not found
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_delete(self, milestone_id: str) -> bool:
+        """Delete milestone.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+
+        Returns:
+        -------
+            True if deleted successfully, False otherwise
+
+        """
+        pass
+
+    @abstractmethod
+    async def milestone_get_issues(
+        self,
+        milestone_id: str,
+        state: str | None = None,
+    ) -> builtins.list[Task]:
+        """Get issues associated with milestone.
+
+        Args:
+        ----
+            milestone_id: Milestone identifier
+            state: Filter by issue state (optional)
+
+        Returns:
+        -------
+            List of Task objects (issues)
+
+        """
+        pass
+
+    # Project Operations (Phase 1 - Abstract methods)
+    # These methods are optional - adapters that don't support projects
+    # can raise NotImplementedError with a helpful message
+
+    async def project_list(
+        self,
+        scope: ProjectScope | None = None,
+        state: ProjectState | None = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> builtins.list[Project]:
+        """List projects with optional filters.
+
+        Args:
+        ----
+            scope: Filter by project scope (user, team, org, repo)
+            state: Filter by project state
+            limit: Maximum results (default: 50)
+            offset: Pagination offset (default: 0)
+
+        Returns:
+        -------
+            List of Project objects
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use Epic operations for this adapter."
+        )
+
+    async def project_get(self, project_id: str) -> Project | None:
+        """Get project by ID.
+
+        Args:
+        ----
+            project_id: Project identifier (platform-specific or unified)
+
+        Returns:
+        -------
+            Project object if found, None otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use get_epic() for this adapter."
+        )
+
+    async def project_create(
+        self,
+        name: str,
+        description: str | None = None,
+        state: ProjectState = ProjectState.PLANNED,
+        target_date: datetime | None = None,
+        **kwargs: Any,
+    ) -> Project:
+        """Create new project.
+
+        Args:
+        ----
+            name: Project name (required)
+            description: Project description
+            state: Initial project state (default: PLANNED)
+            target_date: Target completion date
+            **kwargs: Platform-specific additional fields
+
+        Returns:
+        -------
+            Created Project object
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use create_epic() for this adapter."
+        )
+
+    async def project_update(
+        self,
+        project_id: str,
+        name: str | None = None,
+        description: str | None = None,
+        state: ProjectState | None = None,
+        **kwargs: Any,
+    ) -> Project | None:
+        """Update project properties.
+
+        Args:
+        ----
+            project_id: Project identifier
+            name: New name (optional)
+            description: New description (optional)
+            state: New state (optional)
+            **kwargs: Platform-specific fields to update
+
+        Returns:
+        -------
+            Updated Project object, None if not found
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_delete(self, project_id: str) -> bool:
+        """Delete or archive project.
+
+        Args:
+        ----
+            project_id: Project identifier
+
+        Returns:
+        -------
+            True if deleted successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_get_issues(
+        self, project_id: str, state: TicketState | None = None
+    ) -> builtins.list[Task]:
+        """Get all issues in project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            state: Filter by issue state (optional)
+
+        Returns:
+        -------
+            List of Task objects (issues in project)
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations. "
+            "Use list_issues_by_epic() for this adapter."
+        )
+
+    async def project_add_issue(self, project_id: str, issue_id: str) -> bool:
+        """Add issue to project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            issue_id: Issue identifier to add
+
+        Returns:
+        -------
+            True if added successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_remove_issue(self, project_id: str, issue_id: str) -> bool:
+        """Remove issue from project.
+
+        Args:
+        ----
+            project_id: Project identifier
+            issue_id: Issue identifier to remove
+
+        Returns:
+        -------
+            True if removed successfully, False otherwise
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project operations."
+        )
+
+    async def project_get_statistics(self, project_id: str) -> ProjectStatistics:
+        """Get project statistics and metrics.
+
+        Calculates or retrieves statistics including issue counts by state,
+        progress percentage, and velocity metrics.
+
+        Args:
+        ----
+            project_id: Project identifier
+
+        Returns:
+        -------
+            ProjectStatistics object with calculated metrics
+
+        Raises:
+        ------
+            NotImplementedError: If adapter doesn't support projects
+
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support project statistics."
+        )