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

mcp_ticketer/analysis/dependency_graph.py

@@ -0,0 +1,255 @@
+"""Dependency graph analysis for tickets.
+
+This module parses ticket descriptions and builds dependency graphs to:
+- Identify ticket dependencies (blocks/depends on)
+- Find critical paths (longest dependency chains)
+- Detect circular dependencies
+- Recommend optimal work order
+"""
+
+import re
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from ..core.models import Task
+
+
+class DependencyNode(BaseModel):
+    """A node in the dependency graph.
+
+    Attributes:
+        ticket_id: ID of the ticket
+        blocks: List of ticket IDs that this ticket blocks
+        blocked_by: List of ticket IDs that block this ticket
+        depth: Depth in the dependency tree (0 = leaf, higher = more dependencies)
+
+    """
+
+    ticket_id: str
+    blocks: list[str] = []
+    blocked_by: list[str] = []
+    depth: int = 0
+
+
+class DependencyGraph:
+    """Build and analyze ticket dependency graphs.
+
+    Parses ticket descriptions to identify references to other tickets
+    and builds a directed graph of dependencies.
+
+    Supported patterns:
+    - "Related to TICKET-123"
+    - "Depends on 1M-315"
+    - "Blocks #456"
+    - "1M-316: Feature name"
+    - "Blocked by PROJ-789"
+    """
+
+    # Regex patterns for dependency detection
+    DEPENDENCY_PATTERNS = [
+        (r"depends\s+on\s+([A-Z0-9]+-\d+)\b", "blocked_by"),
+        (r"depends\s+on\s+#(\d+)\b", "blocked_by"),
+        (r"blocked\s+by\s+([A-Z0-9]+-\d+)\b", "blocked_by"),
+        (r"blocked\s+by\s+#(\d+)\b", "blocked_by"),
+        (r"blocks\s+([A-Z0-9]+-\d+)\b", "blocks"),
+        (r"blocks\s+#(\d+)\b", "blocks"),
+        (r"related\s+to\s+([A-Z0-9]+-\d+)\b", "related"),
+        (r"related\s+to\s+#(\d+)\b", "related"),
+        # Inline references like "1M-316:" or "TICKET-123:"
+        (r"\b([A-Z0-9]+-\d+):", "related"),
+    ]
+
+    def __init__(self) -> None:
+        """Initialize the dependency graph."""
+        self.nodes: dict[str, DependencyNode] = {}
+        self.edges: dict[str, set[str]] = defaultdict(set)  # ticket_id -> blocks set
+        self.reverse_edges: dict[str, set[str]] = defaultdict(
+            set
+        )  # ticket_id -> blocked_by set
+
+    def add_ticket(self, ticket: "Task") -> None:
+        """Add a ticket to the graph and extract its dependencies.
+
+        Args:
+            ticket: The ticket to add
+
+        """
+        ticket_id = ticket.id or ""
+        if not ticket_id:
+            return
+
+        # Initialize node if not exists
+        if ticket_id not in self.nodes:
+            self.nodes[ticket_id] = DependencyNode(ticket_id=ticket_id)
+
+        # Parse description and title for dependencies
+        text = f"{ticket.title or ''}\n{ticket.description or ''}"
+        dependencies = self._extract_dependencies(text, ticket_id)
+
+        # Update graph edges
+        for dep_type, dep_id in dependencies:
+            if dep_type == "blocks":
+                self.edges[ticket_id].add(dep_id)
+                self.reverse_edges[dep_id].add(ticket_id)
+            elif dep_type == "blocked_by":
+                self.edges[dep_id].add(ticket_id)
+                self.reverse_edges[ticket_id].add(dep_id)
+            elif dep_type == "related":
+                # For related, add bidirectional soft dependency
+                # (lower priority in recommendations)
+                pass
+
+    def _extract_dependencies(self, text: str, ticket_id: str) -> list[tuple[str, str]]:
+        """Extract dependencies from ticket text.
+
+        Args:
+            text: The text to parse (title + description)
+            ticket_id: ID of the ticket being parsed (to avoid self-references)
+
+        Returns:
+            List of (dependency_type, ticket_id) tuples
+
+        """
+        dependencies = []
+        text_lower = text.lower()
+
+        for pattern, dep_type in self.DEPENDENCY_PATTERNS:
+            matches = re.finditer(pattern, text_lower, re.IGNORECASE)
+            for match in matches:
+                dep_id = match.group(1)
+                # Normalize ticket ID (handle both "1M-123" and "123" formats)
+                if not re.match(r"[A-Z0-9]+-\d+", dep_id, re.IGNORECASE):
+                    # If just a number, try to infer project prefix from current ticket
+                    if "-" in ticket_id:
+                        prefix = ticket_id.split("-")[0]
+                        dep_id = f"{prefix}-{dep_id}"
+
+                # Avoid self-references
+                if dep_id.upper() != ticket_id.upper():
+                    dependencies.append((dep_type, dep_id.upper()))
+
+        return dependencies
+
+    def calculate_depths(self) -> None:
+        """Calculate depth of each node in the dependency tree.
+
+        Depth is the longest path from this node to a leaf node.
+        Higher depth means more dependencies downstream.
+        """
+        # Build adjacency list from edges
+        visited = set()
+
+        def dfs(node_id: str) -> int:
+            """DFS to calculate max depth."""
+            if node_id in visited:
+                return 0  # Avoid cycles
+
+            visited.add(node_id)
+
+            # Get all tickets this one blocks
+            blocked_tickets = self.edges.get(node_id, set())
+            if not blocked_tickets:
+                depth = 0
+            else:
+                # Depth is 1 + max depth of any blocked ticket
+                depth = 1 + max(
+                    (dfs(blocked) for blocked in blocked_tickets), default=0
+                )
+
+            if node_id in self.nodes:
+                self.nodes[node_id].depth = depth
+
+            visited.remove(node_id)
+            return depth
+
+        # Calculate depth for all nodes
+        for node_id in list(self.nodes.keys()):
+            if node_id not in visited:
+                dfs(node_id)
+
+    def get_critical_path(self) -> list[str]:
+        """Get the critical path (longest dependency chain).
+
+        Returns:
+            List of ticket IDs in the critical path, ordered from
+            start to end
+
+        """
+        if not self.nodes:
+            return []
+
+        # Find node with maximum depth
+        max_depth_node = max(self.nodes.values(), key=lambda n: n.depth)
+
+        if max_depth_node.depth == 0:
+            return [max_depth_node.ticket_id]
+
+        # Trace back the critical path
+        path = [max_depth_node.ticket_id]
+        current = max_depth_node.ticket_id
+
+        while True:
+            blocked_tickets = self.edges.get(current, set())
+            if not blocked_tickets:
+                break
+
+            # Find the blocked ticket with maximum depth
+            next_ticket = max(
+                blocked_tickets,
+                key=lambda tid: self.nodes[tid].depth if tid in self.nodes else 0,
+                default=None,
+            )
+
+            if next_ticket and next_ticket not in path:
+                path.append(next_ticket)
+                current = next_ticket
+            else:
+                break
+
+        return path
+
+    def get_blocked_tickets(self) -> dict[str, list[str]]:
+        """Get all blocked tickets and their blockers.
+
+        Returns:
+            Dictionary mapping ticket_id -> list of blocker ticket IDs
+
+        """
+        blocked = {}
+        for ticket_id, blockers in self.reverse_edges.items():
+            if blockers:
+                blocked[ticket_id] = list(blockers)
+        return blocked
+
+    def get_high_impact_tickets(self) -> list[tuple[str, int]]:
+        """Get tickets that block the most other tickets.
+
+        Returns:
+            List of (ticket_id, count) tuples sorted by impact (descending)
+
+        """
+        impact = []
+        for ticket_id, blocked_set in self.edges.items():
+            if blocked_set:
+                impact.append((ticket_id, len(blocked_set)))
+
+        return sorted(impact, key=lambda x: x[1], reverse=True)
+
+    def finalize(self) -> None:
+        """Finalize the graph by calculating all metrics.
+
+        Call this after adding all tickets to compute depths and
+        other derived metrics.
+        """
+        # Update nodes with edge information
+        for ticket_id in self.nodes:
+            self.nodes[ticket_id].blocks = list(self.edges.get(ticket_id, set()))
+            self.nodes[ticket_id].blocked_by = list(
+                self.reverse_edges.get(ticket_id, set())
+            )
+
+        # Calculate depths
+        self.calculate_depths()

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