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

mcp_ticketer/analysis/health_assessment.py

@@ -0,0 +1,304 @@
+"""Project health assessment for epics and projects.
+
+This module evaluates project health based on:
+- Completion rate (% of tickets done)
+- Progress rate (% of tickets in progress)
+- Blocker rate (% of tickets blocked)
+- Priority distribution
+- Work distribution balance
+"""
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..core.models import Task
+
+
+class ProjectHealth(str, Enum):
+    """Project health status levels.
+
+    Attributes:
+        ON_TRACK: Project is progressing well, no major issues
+        AT_RISK: Project has some concerns but still recoverable
+        OFF_TRACK: Project has serious issues requiring intervention
+
+    """
+
+    ON_TRACK = "on_track"
+    AT_RISK = "at_risk"
+    OFF_TRACK = "off_track"
+
+
+class HealthMetrics(BaseModel):
+    """Calculated health metrics for a project.
+
+    Attributes:
+        total_tickets: Total number of tickets
+        completion_rate: Percentage of tickets done (0.0-1.0)
+        progress_rate: Percentage of tickets in progress (0.0-1.0)
+        blocked_rate: Percentage of tickets blocked (0.0-1.0)
+        critical_count: Number of critical priority tickets
+        high_count: Number of high priority tickets
+        health_score: Overall health score (0.0-1.0, higher is better)
+        health_status: Overall health status
+
+    """
+
+    total_tickets: int
+    completion_rate: float
+    progress_rate: float
+    blocked_rate: float
+    critical_count: int
+    high_count: int
+    health_score: float
+    health_status: ProjectHealth
+
+
+class HealthAssessor:
+    """Assess project health based on ticket metrics.
+
+    Uses weighted scoring of multiple factors:
+    - Completion rate (30% weight): How many tickets are done
+    - Progress rate (25% weight): How many tickets are actively worked
+    - Blocker rate (30% weight): How many tickets are blocked (negative)
+    - Priority balance (15% weight): Critical/high priority completion
+    """
+
+    # Thresholds for health determination
+    HEALTHY_COMPLETION_THRESHOLD = 0.5
+    HEALTHY_PROGRESS_THRESHOLD = 0.2
+    RISKY_BLOCKED_THRESHOLD = 0.2
+    CRITICAL_BLOCKED_THRESHOLD = 0.4
+
+    # Weights for health score calculation
+    COMPLETION_WEIGHT = 0.30
+    PROGRESS_WEIGHT = 0.25
+    BLOCKER_WEIGHT = 0.30
+    PRIORITY_WEIGHT = 0.15
+
+    def __init__(self) -> None:
+        """Initialize the health assessor."""
+        pass
+
+    def assess(self, tickets: list["Task"]) -> HealthMetrics:
+        """Assess project health from a list of tickets.
+
+        Args:
+            tickets: List of tickets in the project
+
+        Returns:
+            Health metrics including status and score
+
+        """
+        if not tickets:
+            return HealthMetrics(
+                total_tickets=0,
+                completion_rate=0.0,
+                progress_rate=0.0,
+                blocked_rate=0.0,
+                critical_count=0,
+                high_count=0,
+                health_score=0.0,
+                health_status=ProjectHealth.OFF_TRACK,
+            )
+
+        total = len(tickets)
+
+        # Calculate state-based metrics
+        completion_rate = self._calculate_completion_rate(tickets)
+        progress_rate = self._calculate_progress_rate(tickets)
+        blocked_rate = self._calculate_blocked_rate(tickets)
+
+        # Count priority tickets
+        critical_count = self._count_by_priority(tickets, "critical")
+        high_count = self._count_by_priority(tickets, "high")
+
+        # Calculate overall health score
+        health_score = self._calculate_health_score(
+            completion_rate, progress_rate, blocked_rate, tickets
+        )
+
+        # Determine health status
+        health_status = self._determine_health_status(
+            completion_rate, progress_rate, blocked_rate, health_score
+        )
+
+        return HealthMetrics(
+            total_tickets=total,
+            completion_rate=completion_rate,
+            progress_rate=progress_rate,
+            blocked_rate=blocked_rate,
+            critical_count=critical_count,
+            high_count=high_count,
+            health_score=health_score,
+            health_status=health_status,
+        )
+
+    def _calculate_completion_rate(self, tickets: list["Task"]) -> float:
+        """Calculate percentage of completed tickets."""
+        from ..core.models import TicketState
+
+        if not tickets:
+            return 0.0
+
+        completed = sum(
+            1
+            for t in tickets
+            if t.state in (TicketState.DONE, TicketState.CLOSED, TicketState.TESTED)
+        )
+        return completed / len(tickets)
+
+    def _calculate_progress_rate(self, tickets: list["Task"]) -> float:
+        """Calculate percentage of in-progress tickets."""
+        from ..core.models import TicketState
+
+        if not tickets:
+            return 0.0
+
+        in_progress = sum(
+            1
+            for t in tickets
+            if t.state
+            in (TicketState.IN_PROGRESS, TicketState.READY, TicketState.TESTED)
+        )
+        return in_progress / len(tickets)
+
+    def _calculate_blocked_rate(self, tickets: list["Task"]) -> float:
+        """Calculate percentage of blocked tickets."""
+        from ..core.models import TicketState
+
+        if not tickets:
+            return 0.0
+
+        blocked = sum(
+            1 for t in tickets if t.state in (TicketState.BLOCKED, TicketState.WAITING)
+        )
+        return blocked / len(tickets)
+
+    def _count_by_priority(self, tickets: list["Task"], priority: str) -> int:
+        """Count tickets with a specific priority."""
+        # Handle both enum and string values
+        return sum(
+            1
+            for t in tickets
+            if t.priority
+            and (t.priority.value if hasattr(t.priority, "value") else t.priority)
+            == priority
+        )
+
+    def _calculate_health_score(
+        self,
+        completion_rate: float,
+        progress_rate: float,
+        blocked_rate: float,
+        tickets: list["Task"],
+    ) -> float:
+        """Calculate weighted health score.
+
+        Args:
+            completion_rate: Percentage of completed tickets
+            progress_rate: Percentage of in-progress tickets
+            blocked_rate: Percentage of blocked tickets
+            tickets: All tickets (for priority analysis)
+
+        Returns:
+            Health score from 0.0 (worst) to 1.0 (best)
+
+        """
+        # Completion score (0.0-1.0)
+        completion_score = completion_rate
+
+        # Progress score (0.0-1.0, capped at reasonable level)
+        # Having some progress is good, but 100% in progress isn't ideal
+        progress_score = min(progress_rate * 2, 1.0)
+
+        # Blocker score (0.0-1.0, inverted since blockers are bad)
+        blocker_score = max(0.0, 1.0 - (blocked_rate * 2.5))
+
+        # Priority score: Check if critical/high priority items are addressed
+        priority_score = self._calculate_priority_score(tickets)
+
+        # Weighted average
+        health_score = (
+            completion_score * self.COMPLETION_WEIGHT
+            + progress_score * self.PROGRESS_WEIGHT
+            + blocker_score * self.BLOCKER_WEIGHT
+            + priority_score * self.PRIORITY_WEIGHT
+        )
+
+        return min(1.0, max(0.0, health_score))
+
+    def _calculate_priority_score(self, tickets: list["Task"]) -> float:
+        """Calculate score based on critical/high priority completion.
+
+        Returns:
+            Score from 0.0-1.0 based on priority ticket completion
+
+        """
+        from ..core.models import Priority, TicketState
+
+        critical_tickets = [
+            t
+            for t in tickets
+            if t.priority == Priority.CRITICAL or t.priority == Priority.HIGH
+        ]
+
+        if not critical_tickets:
+            return 1.0  # No high priority items = good score
+
+        completed_critical = sum(
+            1
+            for t in critical_tickets
+            if t.state in (TicketState.DONE, TicketState.CLOSED, TicketState.TESTED)
+        )
+
+        in_progress_critical = sum(
+            1
+            for t in critical_tickets
+            if t.state in (TicketState.IN_PROGRESS, TicketState.READY)
+        )
+
+        # Score: 1.0 for completed, 0.5 for in progress, 0.0 for not started
+        score = (completed_critical + 0.5 * in_progress_critical) / len(
+            critical_tickets
+        )
+
+        return score
+
+    def _determine_health_status(
+        self,
+        completion_rate: float,
+        progress_rate: float,
+        blocked_rate: float,
+        health_score: float,
+    ) -> ProjectHealth:
+        """Determine overall health status from metrics.
+
+        Args:
+            completion_rate: Percentage of completed tickets
+            progress_rate: Percentage of in-progress tickets
+            blocked_rate: Percentage of blocked tickets
+            health_score: Overall health score
+
+        Returns:
+            Health status (ON_TRACK, AT_RISK, or OFF_TRACK)
+
+        """
+        # Critical thresholds take priority
+        if blocked_rate >= self.CRITICAL_BLOCKED_THRESHOLD:
+            return ProjectHealth.OFF_TRACK
+
+        # Check for on-track conditions
+        if completion_rate >= self.HEALTHY_COMPLETION_THRESHOLD and blocked_rate == 0.0:
+            return ProjectHealth.ON_TRACK
+
+        # Use health score as tie-breaker
+        if health_score >= 0.7:
+            return ProjectHealth.ON_TRACK
+        elif health_score >= 0.4:
+            return ProjectHealth.AT_RISK
+        else:
+            return ProjectHealth.OFF_TRACK

mcp_ticketer/analysis/orphaned.py

@@ -0,0 +1,218 @@
+"""Orphaned ticket detection - tickets without parent epic/project.
+
+This module identifies tickets that are not properly organized in the hierarchy:
+- Tickets without parent epic/milestone
+- Tickets not assigned to any project/team
+- Standalone issues that should be part of larger initiatives
+
+Proper hierarchy ensures better organization and tracking of work.
+"""
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..core.models import Task
+
+
+class OrphanedResult(BaseModel):
+    """Result of orphaned ticket analysis.
+
+    Attributes:
+        ticket_id: ID of the orphaned ticket
+        ticket_title: Title of the orphaned ticket
+        ticket_type: Type of ticket (task, issue, epic)
+        orphan_type: Type of orphan condition (no_parent, no_epic, no_project)
+        suggested_action: Recommended action (assign_epic, assign_project, review)
+        reason: Human-readable explanation
+
+    """
+
+    ticket_id: str
+    ticket_title: str
+    ticket_type: str  # "task", "issue", "epic"
+    orphan_type: str  # "no_parent", "no_epic", "no_project"
+    suggested_action: str  # "assign_epic", "assign_project", "review"
+    reason: str
+
+
+class OrphanedTicketDetector:
+    """Detects orphaned tickets without proper hierarchy.
+
+    Analyzes tickets to find those missing proper parent relationships:
+    - Tasks without parent issues
+    - Issues without parent epics
+    - Tickets without project/team assignments
+
+    This helps identify organizational gaps in ticket management.
+    """
+
+    def find_orphaned_tickets(
+        self,
+        tickets: list["Task"],
+        epics: list["Task"] | None = None,
+    ) -> list[OrphanedResult]:
+        """Find tickets without parent epic/project associations.
+
+        Args:
+            tickets: List of tickets to analyze
+            epics: Optional list of epics for validation
+
+        Returns:
+            List of orphaned tickets with suggested actions
+
+        """
+        results = []
+
+        for ticket in tickets:
+            orphan_types = self._check_orphaned(ticket)
+
+            for orphan_type in orphan_types:
+                result = OrphanedResult(
+                    ticket_id=ticket.id or "unknown",
+                    ticket_title=ticket.title,
+                    ticket_type=self._get_ticket_type(ticket),
+                    orphan_type=orphan_type,
+                    suggested_action=self._suggest_action(orphan_type),
+                    reason=self._build_reason(orphan_type, ticket),
+                )
+                results.append(result)
+
+        return results
+
+    def _check_orphaned(self, ticket: "Task") -> list[str]:
+        """Check if ticket is orphaned in various ways.
+
+        Args:
+            ticket: Ticket to check
+
+        Returns:
+            List of orphan type strings
+
+        """
+        orphan_types = []
+        metadata = ticket.metadata or {}
+
+        # Check ticket type
+        ticket_type = self._get_ticket_type(ticket)
+
+        # For tasks, check parent_issue
+        if ticket_type == "task":
+            if not getattr(ticket, "parent_issue", None):
+                orphan_types.append("no_parent")
+            return orphan_types
+
+        # For issues, check parent_epic and project
+        if ticket_type == "issue":
+            # Check for parent epic
+            has_epic = any(
+                [
+                    getattr(ticket, "parent_epic", None),
+                    metadata.get("parent_id"),
+                    metadata.get("parentId"),
+                    metadata.get("epic_id"),
+                    metadata.get("epicId"),
+                    metadata.get("milestone_id"),  # GitHub milestones
+                    metadata.get("epic"),  # JIRA epics
+                ]
+            )
+
+            if not has_epic:
+                orphan_types.append("no_epic")
+
+            # Check for project assignment
+            has_project = any(
+                [
+                    metadata.get("project_id"),
+                    metadata.get("projectId"),
+                    metadata.get("team_id"),
+                    metadata.get("teamId"),
+                    metadata.get("board_id"),  # JIRA boards
+                    metadata.get("workspace_id"),  # Asana workspaces
+                ]
+            )
+
+            if not has_project:
+                orphan_types.append("no_project")
+
+            # If neither epic nor project
+            if not has_epic and not has_project:
+                orphan_types.append("no_parent")
+
+        return orphan_types
+
+    def _get_ticket_type(self, ticket: "Task") -> str:
+        """Determine ticket type from metadata.
+
+        Args:
+            ticket: Ticket to analyze
+
+        Returns:
+            Ticket type string (task, issue, epic)
+
+        """
+        from ..core.models import TicketType
+
+        # Check explicit ticket_type field
+        ticket_type = getattr(ticket, "ticket_type", None)
+        if ticket_type:
+            if ticket_type == TicketType.EPIC:
+                return "epic"
+            elif ticket_type in (TicketType.TASK, TicketType.SUBTASK):
+                return "task"
+            elif ticket_type == TicketType.ISSUE:
+                return "issue"
+
+        # Fallback to metadata inspection
+        metadata = ticket.metadata or {}
+
+        if metadata.get("type") == "epic":
+            return "epic"
+        elif metadata.get("issue_type") == "Epic":
+            return "epic"
+        elif metadata.get("type") == "task":
+            return "task"
+        elif getattr(ticket, "parent_issue", None):
+            return "task"  # Has parent issue, so it's a task
+        else:
+            return "issue"  # Default to issue
+
+    def _suggest_action(self, orphan_type: str) -> str:
+        """Suggest action for orphaned ticket.
+
+        Args:
+            orphan_type: Type of orphan condition
+
+        Returns:
+            Suggested action string
+
+        """
+        if orphan_type == "no_parent":
+            return "review"  # Needs manual review
+        elif orphan_type == "no_epic":
+            return "assign_epic"
+        elif orphan_type == "no_project":
+            return "assign_project"
+        else:
+            return "review"
+
+    def _build_reason(self, orphan_type: str, ticket: "Task") -> str:
+        """Build human-readable reason.
+
+        Args:
+            orphan_type: Type of orphan condition
+            ticket: The ticket being analyzed
+
+        Returns:
+            Human-readable explanation
+
+        """
+        ticket_type = self._get_ticket_type(ticket)
+
+        reasons = {
+            "no_parent": f"{ticket_type.capitalize()} has no parent epic or project assigned",
+            "no_epic": f"{ticket_type.capitalize()} is missing parent epic/milestone",
+            "no_project": f"{ticket_type.capitalize()} is not assigned to any project/team",
+        }
+        return reasons.get(orphan_type, "Orphaned ticket")