mcp-ticketer 0.12.0__py3-none-any.whl → 2.2.13__py3-none-any.whl

mcp_ticketer/core/adapter.py

@@ -4,9 +4,23 @@ from __future__ import annotations
 
 import builtins
 from abc import ABC, abstractmethod
+from datetime import datetime
 from typing import TYPE_CHECKING, Any, Generic, TypeVar
 
-from .models import Comment, Epic, SearchQuery, Task, TicketState, TicketType
+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
@@ -22,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
 
         """
@@ -43,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
 
         """
@@ -53,9 +103,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Create a new ticket.
 
         Args:
+        ----
             ticket: Ticket to create (Epic or Task)
 
         Returns:
+        -------
             Created ticket with ID populated
 
         """
@@ -66,9 +118,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Read a ticket by ID.
 
         Args:
+        ----
             ticket_id: Unique ticket identifier
 
         Returns:
+        -------
             Ticket if found, None otherwise
 
         """
@@ -79,10 +133,12 @@ class BaseAdapter(ABC, Generic[T]):
         """Update a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             updates: Fields to update
 
         Returns:
+        -------
             Updated ticket if successful, None otherwise
 
         """
@@ -93,9 +149,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Delete a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             True if deleted, False otherwise
 
         """
@@ -108,11 +166,13 @@ class BaseAdapter(ABC, Generic[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
 
         """
@@ -123,9 +183,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Search tickets using advanced query.
 
         Args:
+        ----
             query: Search parameters
 
         Returns:
+        -------
             List of tickets matching search criteria
 
         """
@@ -138,10 +200,12 @@ class BaseAdapter(ABC, Generic[T]):
         """Transition ticket to a new state.
 
         Args:
+        ----
             ticket_id: Ticket identifier
             target_state: Target state
 
         Returns:
+        -------
             Updated ticket if transition successful, None otherwise
 
         """
@@ -152,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
 
         """
@@ -167,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
 
         """
@@ -181,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
 
         """
@@ -193,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):
@@ -225,7 +352,35 @@ 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
 
@@ -235,11 +390,13 @@ class BaseAdapter(ABC, Generic[T]):
         """Create epic (top-level grouping).
 
         Args:
+        ----
             title: Epic title
             description: Epic description
             **kwargs: Additional adapter-specific fields
 
         Returns:
+        -------
             Created epic or None if failed
 
         """
@@ -258,9 +415,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Get epic by ID.
 
         Args:
+        ----
             epic_id: Epic identifier
 
         Returns:
+        -------
             Epic if found, None otherwise
 
         """
@@ -274,9 +433,11 @@ class BaseAdapter(ABC, Generic[T]):
         """List all epics.
 
         Args:
+        ----
             **kwargs: Adapter-specific filter parameters
 
         Returns:
+        -------
             List of epics
 
         """
@@ -296,12 +457,14 @@ class BaseAdapter(ABC, Generic[T]):
         """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
 
         """
@@ -318,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
 
         """
@@ -335,15 +500,18 @@ class BaseAdapter(ABC, Generic[T]):
         """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
 
         """
@@ -369,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
 
         """
@@ -390,14 +560,17 @@ class BaseAdapter(ABC, Generic[T]):
         """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
@@ -412,9 +585,11 @@ class BaseAdapter(ABC, Generic[T]):
         """Get all attachments for a ticket.
 
         Args:
+        ----
             ticket_id: Ticket identifier
 
         Returns:
+        -------
             List of attachments (empty if none or not supported)
 
         """
@@ -430,13 +605,16 @@ class BaseAdapter(ABC, Generic[T]):
         """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
 
         """
@@ -447,3 +625,356 @@ class BaseAdapter(ABC, Generic[T]):
     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."
+        )