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

mcp_ticketer/adapters/github.py

@@ -1,6 +1,7 @@
 """GitHub adapter implementation using REST API v3 and GraphQL API v4."""
 
 import builtins
+import logging
 import re
 from datetime import datetime
 from pathlib import Path
@@ -13,6 +14,8 @@ from ..core.env_loader import load_adapter_config, validate_adapter_config
 from ..core.models import Comment, Epic, Priority, SearchQuery, Task, TicketState
 from ..core.registry import AdapterRegistry
 
+logger = logging.getLogger(__name__)
+
 
 class GitHubStateMapping:
     """GitHub issue states and label-based extended states."""
@@ -133,6 +136,27 @@ class GitHubGraphQLQueries:
         }
     """
 
+    GET_PROJECT_ITERATIONS = """
+        query GetProjectIterations($projectId: ID!, $first: Int!, $after: String) {
+            node(id: $projectId) {
+                ... on ProjectV2 {
+                    iterations(first: $first, after: $after) {
+                        nodes {
+                            id
+                            title
+                            startDate
+                            duration
+                        }
+                        pageInfo {
+                            hasNextPage
+                            endCursor
+                        }
+                    }
+                }
+            }
+        }
+    """
+
 
 class GitHubAdapter(BaseAdapter[Task]):
     """Adapter for GitHub Issues tracking system."""
@@ -141,6 +165,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Initialize GitHub adapter.
 
         Args:
+        ----
             config: Configuration with:
                 - token: GitHub PAT (or GITHUB_TOKEN env var)
                 - owner: Repository owner (or GITHUB_OWNER env var)
@@ -208,6 +233,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Validate that required credentials are present.
 
         Returns:
+        -------
             (is_valid, error_message) - Tuple of validation result and error message
 
         """
@@ -288,9 +314,11 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Convert GitHub milestone to Epic model.
 
         Args:
+        ----
             milestone: GitHub milestone data
 
         Returns:
+        -------
             Epic instance
 
         """
@@ -547,30 +575,72 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         return self._task_from_github_issue(created_issue)
 
-    async def read(self, ticket_id: str) -> Task | None:
-        """Read a GitHub issue by number."""
+    async def read(self, ticket_id: str) -> Task | Epic | None:
+        """Read a GitHub issue OR milestone by number with unified find.
+
+        Tries to find the entity in the following order:
+        1. Issue (most common case) - returns Task
+        2. Milestone (project/epic) - returns Epic
+
+        Args:
+        ----
+            ticket_id: GitHub issue number or milestone number (as string)
+
+        Returns:
+        -------
+            Task if issue found,
+            Epic if milestone found,
+            None if not found as either type
+
+        Examples:
+        --------
+            >>> # Read issue #123
+            >>> task = await adapter.read("123")
+            >>> isinstance(task, Task)  # True
+            >>>
+            >>> # Read milestone #5
+            >>> epic = await adapter.read("5")
+            >>> isinstance(epic, Epic)  # True (if 5 is milestone, not issue)
+
+        """
         # Validate credentials before attempting operation
         is_valid, error_message = self.validate_credentials()
         if not is_valid:
             raise ValueError(error_message)
 
         try:
-            issue_number = int(ticket_id)
+            entity_number = int(ticket_id)
         except ValueError:
             return None
 
+        # Try reading as Issue first (most common case)
         try:
             response = await self.client.get(
-                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}"
+                f"/repos/{self.owner}/{self.repo}/issues/{entity_number}"
             )
-            if response.status_code == 404:
-                return None
-            response.raise_for_status()
+            if response.status_code == 200:
+                response.raise_for_status()
+                issue = response.json()
+                logger.debug(f"Found GitHub entity as Issue: {ticket_id}")
+                return self._task_from_github_issue(issue)
+            elif response.status_code == 404:
+                # Not found as issue, will try milestone next
+                logger.debug(f"Not found as Issue ({ticket_id}), trying Milestone")
+        except httpx.HTTPError as e:
+            logger.debug(f"Error reading as Issue ({ticket_id}): {e}")
+
+        # Try reading as Milestone (Epic)
+        try:
+            milestone = await self.get_milestone(entity_number)
+            if milestone:
+                logger.debug(f"Found GitHub entity as Milestone: {ticket_id}")
+                return milestone
+        except Exception as e:
+            logger.debug(f"Error reading as Milestone ({ticket_id}): {e}")
 
-            issue = response.json()
-            return self._task_from_github_issue(issue)
-        except httpx.HTTPError:
-            return None
+        # Not found as either Issue or Milestone
+        logger.warning(f"GitHub entity not found: {ticket_id}")
+        return None
 
     async def update(self, ticket_id: str, updates: dict[str, Any]) -> Task | None:
         """Update a GitHub issue."""
@@ -1018,6 +1088,62 @@ class GitHubAdapter(BaseAdapter[Task]):
 
         return [self._milestone_to_epic(milestone) for milestone in response.json()]
 
+    async def delete_epic(self, epic_id: str) -> bool:
+        """Delete a GitHub milestone (Epic).
+
+        Args:
+        ----
+            epic_id: Milestone number (not ID) as a string
+
+        Returns:
+        -------
+            True if successfully deleted, False otherwise
+
+        Raises:
+        ------
+            ValueError: If credentials are invalid or epic_id is not a valid number
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            # Extract milestone number from epic_id
+            milestone_number = int(epic_id)
+        except ValueError as e:
+            raise ValueError(
+                f"Invalid milestone number '{epic_id}'. GitHub milestones use numeric IDs."
+            ) from e
+
+        try:
+            # Delete milestone using REST API
+            response = await self.client.delete(
+                f"/repos/{self.owner}/{self.repo}/milestones/{milestone_number}"
+            )
+
+            # GitHub returns 204 No Content on successful deletion
+            if response.status_code == 204:
+                return True
+
+            # Handle 404 errors gracefully
+            if response.status_code == 404:
+                return False
+
+            # Other errors - raise for visibility
+            response.raise_for_status()
+            return True
+
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                # Milestone not found
+                return False
+            # Re-raise other HTTP errors
+            raise ValueError(f"Failed to delete milestone: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Failed to delete milestone: {e}") from e
+
     async def link_to_pull_request(self, issue_number: int, pr_number: int) -> bool:
         """Link an issue to a pull request using keywords."""
         # This is typically done through PR description keywords like "fixes #123"
@@ -1043,6 +1169,7 @@ class GitHubAdapter(BaseAdapter[Task]):
         """Create a pull request linked to an issue.
 
         Args:
+        ----
             ticket_id: Issue number to link the PR to
             base_branch: Target branch for the PR (default: main)
             head_branch: Source branch name (auto-generated if not provided)
@@ -1051,6 +1178,7 @@ class GitHubAdapter(BaseAdapter[Task]):
             draft: Create as draft PR
 
         Returns:
+        -------
             Dictionary with PR details including number, url, and branch
 
         """
@@ -1219,10 +1347,12 @@ Fixes #{issue_number}
         """Link an existing pull request to a ticket.
 
         Args:
+        ----
             ticket_id: Issue number to link the PR to
             pr_url: GitHub PR URL to link
 
         Returns:
+        -------
             Dictionary with link status and PR details
 
         """
@@ -1315,6 +1445,7 @@ Fixes #{issue_number}
         """List all labels available in the repository.
 
         Returns:
+        -------
             List of label dictionaries with 'id', 'name', and 'color' fields
 
         """
@@ -1340,6 +1471,7 @@ Fixes #{issue_number}
         """Update a GitHub milestone (Epic).
 
         Args:
+        ----
             milestone_number: Milestone number (not ID)
             updates: Dictionary with fields to update:
                 - title: Milestone title
@@ -1348,9 +1480,11 @@ Fixes #{issue_number}
                 - target_date: Due date in ISO format
 
         Returns:
+        -------
             Updated Epic object or None if not found
 
         Raises:
+        ------
             ValueError: If no fields to update
             httpx.HTTPError: If API request fails
 
@@ -1408,10 +1542,12 @@ Fixes #{issue_number}
         either a milestone number or the epic ID from the Epic object.
 
         Args:
+        ----
             epic_id: Epic ID (e.g., "milestone-5") or milestone number as string
             updates: Dictionary with fields to update
 
         Returns:
+        -------
             Updated Epic object or None if not found
 
         """
@@ -1437,18 +1573,22 @@ Fixes #{issue_number}
         that users can edit to add actual file attachments through the UI.
 
         Args:
+        ----
             issue_number: Issue number
             file_path: Path to file to attach
             comment: Optional comment text (defaults to "Attached: {filename}")
 
         Returns:
+        -------
             Dictionary with comment data and file info
 
         Raises:
+        ------
             FileNotFoundError: If file doesn't exist
             ValueError: If file too large (>25 MB)
 
         Note:
+        ----
             GitHub file size limit: 25 MB
             Supported: Images, videos, documents
 
@@ -1498,14 +1638,17 @@ Fixes #{issue_number}
         this method appends a markdown link to the milestone description.
 
         Args:
+        ----
             milestone_number: Milestone number
             file_url: URL to the file (external or GitHub-hosted)
             description: Description/title for the file
 
         Returns:
+        -------
             Updated Epic object
 
         Example:
+        -------
             await adapter.add_attachment_reference_to_milestone(
                 5,
                 "https://example.com/spec.pdf",
@@ -1541,14 +1684,17 @@ Fixes #{issue_number}
         - Milestones: Not supported, raises NotImplementedError with guidance
 
         Args:
+        ----
             ticket_id: Ticket identifier (issue number or milestone ID)
             file_path: Path to file to attach
             description: Optional description
 
         Returns:
+        -------
             Attachment metadata
 
         Raises:
+        ------
             NotImplementedError: For milestones (no native support)
             FileNotFoundError: If file doesn't exist
 
@@ -1565,6 +1711,374 @@ Fixes #{issue_number}
         issue_number = int(ticket_id.replace("issue-", ""))
         return await self.add_attachment_to_issue(issue_number, file_path, description)
 
+    async def list_cycles(
+        self, project_id: str | None = None, limit: int = 50
+    ) -> builtins.list[dict[str, Any]]:
+        """List GitHub Project iterations (cycles/sprints).
+
+        GitHub Projects V2 uses "iterations" for sprint/cycle functionality.
+        Requires a project node ID (not numeric ID).
+
+        Args:
+        ----
+            project_id: GitHub Project V2 node ID (e.g., 'PVT_kwDOABcdefgh').
+                       This is required for Projects V2. Can be found in the
+                       project's GraphQL ID.
+            limit: Maximum number of iterations to return (default: 50)
+
+        Returns:
+        -------
+            List of iteration dictionaries with fields:
+                - id: Iteration node ID
+                - title: Iteration title/name
+                - startDate: Start date (ISO format)
+                - duration: Duration in days
+                - endDate: Calculated end date (startDate + duration)
+
+        Raises:
+        ------
+            ValueError: If project_id not provided or credentials invalid
+            httpx.HTTPError: If GraphQL query fails
+
+        Example:
+        -------
+            >>> iterations = await adapter.list_cycles(
+            ...     project_id="PVT_kwDOABCD1234",
+            ...     limit=10
+            ... )
+            >>> for iteration in iterations:
+            ...     print(f"{iteration['title']}: {iteration['startDate']} ({iteration['duration']} days)")
+
+        Note:
+        ----
+            GitHub Projects V2 node IDs can be obtained via the GitHub GraphQL API.
+            This is different from project numbers shown in the UI.
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        if not project_id:
+            raise ValueError(
+                "project_id is required for GitHub Projects V2. "
+                "Provide a project node ID (e.g., 'PVT_kwDOABcdefgh'). "
+                "Find this via GraphQL API: query { organization(login: 'org') { "
+                "projectV2(number: 1) { id } } }"
+            )
+
+        # Execute GraphQL query to fetch iterations
+        query = GitHubGraphQLQueries.GET_PROJECT_ITERATIONS
+        variables = {"projectId": project_id, "first": min(limit, 100), "after": None}
+
+        try:
+            result = await self._graphql_request(query, variables)
+
+            # Extract iterations from response
+            project_node = result.get("node")
+            if not project_node:
+                raise ValueError(
+                    f"Project not found with ID: {project_id}. "
+                    "Verify the project ID is correct and you have access."
+                )
+
+            iterations_data = project_node.get("iterations", {})
+            iteration_nodes = iterations_data.get("nodes", [])
+
+            # Transform to standard format and calculate end dates
+            iterations = []
+            for iteration in iteration_nodes:
+                # Calculate end date from start date + duration
+                start_date = iteration.get("startDate")
+                duration = iteration.get("duration", 0)
+
+                end_date = None
+                if start_date and duration:
+                    from datetime import datetime, timedelta
+
+                    start_dt = datetime.fromisoformat(start_date.replace("Z", "+00:00"))
+                    end_dt = start_dt + timedelta(days=duration)
+                    end_date = end_dt.isoformat()
+
+                iterations.append(
+                    {
+                        "id": iteration["id"],
+                        "title": iteration.get("title", ""),
+                        "startDate": start_date,
+                        "duration": duration,
+                        "endDate": end_date,
+                    }
+                )
+
+            return iterations
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except Exception as e:
+            raise ValueError(f"Failed to list project iterations: {e}") from e
+
+    async def get_issue_status(self, issue_number: int) -> dict[str, Any]:
+        """Get rich status information for a GitHub issue.
+
+        GitHub issues have binary states (open/closed) natively. Extended status
+        tracking uses labels following the status:* convention (e.g., status:in_progress).
+
+        Args:
+        ----
+            issue_number: GitHub issue number
+
+        Returns:
+        -------
+            Dictionary with comprehensive status information:
+                - state: Native GitHub state ('open' or 'closed')
+                - status_label: Extended status from labels (in_progress, blocked, etc.)
+                - extended_state: Universal TicketState value
+                - labels: All issue labels
+                - state_reason: For closed issues (completed or not_planned)
+                - metadata: Additional issue metadata (assignees, milestone, etc.)
+
+        Raises:
+        ------
+            ValueError: If credentials invalid or issue not found
+            httpx.HTTPError: If API request fails
+
+        Example:
+        -------
+            >>> status = await adapter.get_issue_status(123)
+            >>> print(f"Issue #{status['number']}: {status['extended_state']}")
+            >>> print(f"Native state: {status['state']}")
+            >>> if status['status_label']:
+            ...     print(f"Label-based status: {status['status_label']}")
+
+        Note:
+        ----
+            GitHub's binary state model is extended via labels:
+            - open + no label = OPEN
+            - open + status:in-progress = IN_PROGRESS
+            - open + status:blocked = BLOCKED
+            - closed = CLOSED (check state_reason for details)
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            # Fetch issue via REST API
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/issues/{issue_number}"
+            )
+
+            if response.status_code == 404:
+                raise ValueError(f"Issue #{issue_number} not found")
+
+            response.raise_for_status()
+            issue = response.json()
+
+            # Extract labels
+            labels = [label["name"] for label in issue.get("labels", [])]
+
+            # Derive extended state from issue data
+            extended_state = self._extract_state_from_issue(issue)
+
+            # Find status label if present
+            status_label = None
+            for _state, label_name in GitHubStateMapping.STATE_LABELS.items():
+                if label_name.lower() in [label.lower() for label in labels]:
+                    status_label = label_name
+                    break
+
+            # Build comprehensive status response
+            status_info = {
+                "number": issue["number"],
+                "state": issue["state"],  # 'open' or 'closed'
+                "status_label": status_label,  # Label-based extended status
+                "extended_state": extended_state.value,  # Universal TicketState
+                "labels": labels,
+                "state_reason": issue.get(
+                    "state_reason"
+                ),  # 'completed' or 'not_planned'
+                "metadata": {
+                    "title": issue["title"],
+                    "url": issue["html_url"],
+                    "assignees": [
+                        assignee["login"] for assignee in issue.get("assignees", [])
+                    ],
+                    "milestone": (
+                        issue.get("milestone", {}).get("title")
+                        if issue.get("milestone")
+                        else None
+                    ),
+                    "created_at": issue["created_at"],
+                    "updated_at": issue["updated_at"],
+                    "closed_at": issue.get("closed_at"),
+                },
+            }
+
+            return status_info
+
+        except ValueError:
+            # Re-raise validation errors
+            raise
+        except httpx.HTTPError as e:
+            raise ValueError(f"Failed to get issue status: {e}") from e
+
+    async def list_issue_statuses(self) -> builtins.list[dict[str, Any]]:
+        """List available issue statuses in GitHub.
+
+        Returns all possible issue statuses including native GitHub states
+        and extended label-based states.
+
+        Returns:
+        -------
+            List of status dictionaries with fields:
+                - name: Status name (e.g., 'open', 'in_progress', 'closed')
+                - type: Status type ('native' or 'extended')
+                - label: Associated label name (for extended statuses)
+                - description: Human-readable description
+                - category: Status category (open, in_progress, done, etc.)
+
+        Example:
+        -------
+            >>> statuses = await adapter.list_issue_statuses()
+            >>> for status in statuses:
+            ...     print(f"{status['name']}: {status['description']}")
+            ...     if status['type'] == 'extended':
+            ...         print(f"  Label: {status['label']}")
+
+        Note:
+        ----
+            GitHub natively supports only 'open' and 'closed' states.
+            Extended statuses are implemented via labels following the
+            status:* naming convention (e.g., status:in-progress).
+
+        """
+        # Define native GitHub states
+        statuses = [
+            {
+                "name": "open",
+                "type": "native",
+                "label": None,
+                "description": "Issue is open and not yet completed",
+                "category": "open",
+            },
+            {
+                "name": "closed",
+                "type": "native",
+                "label": None,
+                "description": "Issue is closed (completed or not planned)",
+                "category": "done",
+            },
+        ]
+
+        # Add extended label-based states
+        for state, label_name in GitHubStateMapping.STATE_LABELS.items():
+            statuses.append(
+                {
+                    "name": state.value,
+                    "type": "extended",
+                    "label": label_name,
+                    "description": f"Issue is {state.value.replace('_', ' ')} (tracked via label)",
+                    "category": state.value,
+                }
+            )
+
+        return statuses
+
+    async def list_project_labels(
+        self, milestone_number: int | None = None
+    ) -> builtins.list[dict[str, Any]]:
+        """List labels used in a GitHub milestone (project/epic).
+
+        If milestone_number is provided, returns only labels used by issues
+        in that milestone. Otherwise, returns all repository labels.
+
+        Args:
+        ----
+            milestone_number: Optional milestone number to filter labels.
+                            If None, returns all repository labels.
+
+        Returns:
+        -------
+            List of label dictionaries with fields:
+                - id: Label identifier (name)
+                - name: Label name
+                - color: Label color (hex without #)
+                - description: Label description (if available)
+                - usage_count: Number of issues using this label (if milestone filtered)
+
+        Example:
+        -------
+            >>> # Get all repository labels
+            >>> all_labels = await adapter.list_project_labels()
+            >>> print(f"Repository has {len(all_labels)} labels")
+            >>>
+            >>> # Get labels used in milestone 5
+            >>> milestone_labels = await adapter.list_project_labels(milestone_number=5)
+            >>> for label in milestone_labels:
+            ...     print(f"{label['name']}: used by {label['usage_count']} issues")
+
+        Note:
+        ----
+            Labels are repository-scoped in GitHub, not milestone-scoped.
+            When filtering by milestone, this method queries issues in that
+            milestone and extracts their unique labels.
+
+        """
+        # Validate credentials
+        is_valid, error_message = self.validate_credentials()
+        if not is_valid:
+            raise ValueError(error_message)
+
+        try:
+            if milestone_number is None:
+                # Return all repository labels (delegate to existing method)
+                return await self.list_labels()
+
+            # Query issues in the milestone
+            params = {
+                "milestone": str(milestone_number),
+                "state": "all",
+                "per_page": 100,
+            }
+
+            response = await self.client.get(
+                f"/repos/{self.owner}/{self.repo}/issues", params=params
+            )
+            response.raise_for_status()
+            issues = response.json()
+
+            # Extract unique labels from issues
+            label_usage = {}  # {label_name: {data, count}}
+            for issue in issues:
+                # Skip pull requests
+                if "pull_request" in issue:
+                    continue
+
+                for label in issue.get("labels", []):
+                    label_name = label["name"]
+                    if label_name not in label_usage:
+                        label_usage[label_name] = {
+                            "id": label_name,
+                            "name": label_name,
+                            "color": label["color"],
+                            "description": label.get("description", ""),
+                            "usage_count": 0,
+                        }
+                    label_usage[label_name]["usage_count"] += 1
+
+            # Convert to list and sort by usage count
+            labels = list(label_usage.values())
+            labels.sort(key=lambda x: x["usage_count"], reverse=True)
+
+            return labels
+
+        except httpx.HTTPError as e:
+            raise ValueError(f"Failed to list project labels: {e}") from e
+
     async def close(self) -> None:
         """Close the HTTP client connection."""
         await self.client.aclose()