mcp-ticketer 0.1.30__py3-none-any.whl → 1.2.11__py3-none-any.whl

mcp_ticketer/analysis/__init__.py

@@ -0,0 +1,23 @@
+"""Ticket analysis and cleanup tools for PM monitoring.
+
+This module provides comprehensive analysis capabilities for ticket health:
+- Similarity detection: Find duplicate or related tickets using TF-IDF
+- Staleness detection: Identify old, inactive tickets
+- Orphaned detection: Find tickets missing hierarchy (epic/project)
+- Cleanup reports: Comprehensive analysis with recommendations
+
+These tools help product managers maintain ticket health and development practices.
+"""
+
+from .orphaned import OrphanedResult, OrphanedTicketDetector
+from .similarity import SimilarityResult, TicketSimilarityAnalyzer
+from .staleness import StalenessResult, StaleTicketDetector
+
+__all__ = [
+    "SimilarityResult",
+    "TicketSimilarityAnalyzer",
+    "StalenessResult",
+    "StaleTicketDetector",
+    "OrphanedResult",
+    "OrphanedTicketDetector",
+]

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")

mcp_ticketer/analysis/similarity.py

@@ -0,0 +1,224 @@
+"""Ticket similarity detection using TF-IDF and fuzzy matching.
+
+This module provides similarity analysis between tickets to detect:
+- Duplicate tickets that should be merged
+- Related tickets that should be linked
+- Similar work that could be consolidated
+
+Uses TF-IDF vectorization with cosine similarity for content analysis,
+and fuzzy string matching for title comparison.
+"""
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+from rapidfuzz import fuzz
+from sklearn.feature_extraction.text import TfidfVectorizer
+from sklearn.metrics.pairwise import cosine_similarity
+
+if TYPE_CHECKING:
+    from ..core.models import Task
+
+
+class SimilarityResult(BaseModel):
+    """Result of similarity analysis between two tickets.
+
+    Attributes:
+        ticket1_id: ID of first ticket
+        ticket1_title: Title of first ticket
+        ticket2_id: ID of second ticket
+        ticket2_title: Title of second ticket
+        similarity_score: Overall similarity score (0.0-1.0)
+        similarity_reasons: List of reasons for similarity
+        suggested_action: Recommended action (merge, link, ignore)
+        confidence: Confidence in the similarity (0.0-1.0)
+
+    """
+
+    ticket1_id: str
+    ticket1_title: str
+    ticket2_id: str
+    ticket2_title: str
+    similarity_score: float  # 0.0-1.0
+    similarity_reasons: list[str]
+    suggested_action: str  # "merge", "link", "ignore"
+    confidence: float
+
+
+class TicketSimilarityAnalyzer:
+    """Analyzes tickets to find similar/duplicate entries.
+
+    Uses a combination of TF-IDF vectorization on titles and descriptions,
+    plus fuzzy string matching on titles to identify similar tickets.
+
+    Attributes:
+        threshold: Minimum similarity score to report (0.0-1.0)
+        title_weight: Weight given to title similarity (0.0-1.0)
+        description_weight: Weight given to description similarity (0.0-1.0)
+
+    """
+
+    def __init__(
+        self,
+        threshold: float = 0.75,
+        title_weight: float = 0.7,
+        description_weight: float = 0.3,
+    ):
+        """Initialize the similarity analyzer.
+
+        Args:
+            threshold: Minimum similarity score to report (default: 0.75)
+            title_weight: Weight for title similarity (default: 0.7)
+            description_weight: Weight for description similarity (default: 0.3)
+
+        """
+        self.threshold = threshold
+        self.title_weight = title_weight
+        self.description_weight = description_weight
+
+    def find_similar_tickets(
+        self,
+        tickets: list["Task"],
+        target_ticket: "Task | None" = None,
+        limit: int = 10,
+    ) -> list[SimilarityResult]:
+        """Find similar tickets using TF-IDF + cosine similarity.
+
+        Args:
+            tickets: List of tickets to analyze
+            target_ticket: Find similar to this ticket (if None, find all pairs)
+            limit: Maximum results to return
+
+        Returns:
+            List of similarity results above threshold, sorted by score
+
+        """
+        if len(tickets) < 2:
+            return []
+
+        # Build corpus for TF-IDF
+        titles = [t.title for t in tickets]
+        descriptions = [t.description or "" for t in tickets]
+
+        # TF-IDF on titles
+        title_vectorizer = TfidfVectorizer(
+            min_df=1, stop_words="english", lowercase=True, ngram_range=(1, 2)
+        )
+        title_matrix = title_vectorizer.fit_transform(titles)
+
+        # TF-IDF on descriptions (if available)
+        desc_matrix = None
+        if any(descriptions):
+            desc_vectorizer = TfidfVectorizer(
+                min_df=1, stop_words="english", lowercase=True, ngram_range=(1, 2)
+            )
+            desc_matrix = desc_vectorizer.fit_transform(descriptions)
+
+        # Compute similarity matrices
+        title_similarity = cosine_similarity(title_matrix)
+
+        if desc_matrix is not None:
+            desc_similarity = cosine_similarity(desc_matrix)
+            # Weighted combination
+            combined_similarity = (
+                self.title_weight * title_similarity
+                + self.description_weight * desc_similarity
+            )
+        else:
+            # Only use title similarity if no descriptions
+            combined_similarity = title_similarity
+
+        results = []
+
+        if target_ticket:
+            # Find similar to specific ticket
+            target_idx = next(
+                (i for i, t in enumerate(tickets) if t.id == target_ticket.id),
+                None,
+            )
+            if target_idx is None:
+                return []
+
+            for i, ticket in enumerate(tickets):
+                if i == target_idx:
+                    continue
+
+                score = float(combined_similarity[target_idx, i])
+                if score >= self.threshold:
+                    results.append(self._create_result(target_ticket, ticket, score))
+        else:
+            # Find all similar pairs
+            for i in range(len(tickets)):
+                for j in range(i + 1, len(tickets)):
+                    score = float(combined_similarity[i, j])
+                    if score >= self.threshold:
+                        results.append(
+                            self._create_result(tickets[i], tickets[j], score)
+                        )
+
+        # Sort by score and limit
+        results.sort(key=lambda x: x.similarity_score, reverse=True)
+        return results[:limit]
+
+    def _create_result(
+        self,
+        ticket1: "Task",
+        ticket2: "Task",
+        score: float,
+    ) -> SimilarityResult:
+        """Create similarity result with analysis.
+
+        Args:
+            ticket1: First ticket
+            ticket2: Second ticket
+            score: Similarity score
+
+        Returns:
+            SimilarityResult with detailed analysis
+
+        """
+        reasons = []
+
+        # Title similarity using fuzzy matching
+        title_sim = fuzz.ratio(ticket1.title, ticket2.title) / 100.0
+        if title_sim > 0.8:
+            reasons.append("very_similar_titles")
+        elif title_sim > 0.6:
+            reasons.append("similar_titles")
+
+        # Tag overlap
+        tags1 = set(ticket1.tags or [])
+        tags2 = set(ticket2.tags or [])
+        if tags1 and tags2:
+            overlap = len(tags1 & tags2) / len(tags1 | tags2)
+            if overlap > 0.5:
+                reasons.append(f"tag_overlap_{int(overlap*100)}%")
+
+        # Same state
+        if ticket1.state == ticket2.state:
+            reasons.append("same_state")
+
+        # Same assignee
+        assignee1 = getattr(ticket1, "assignee", None)
+        assignee2 = getattr(ticket2, "assignee", None)
+        if assignee1 and assignee2 and assignee1 == assignee2:
+            reasons.append("same_assignee")
+
+        # Determine action
+        if score > 0.9:
+            action = "merge"  # Very likely duplicates
+        elif score > 0.75:
+            action = "link"  # Related, should be linked
+        else:
+            action = "ignore"  # Low confidence
+
+        return SimilarityResult(
+            ticket1_id=ticket1.id or "unknown",
+            ticket1_title=ticket1.title,
+            ticket2_id=ticket2.id or "unknown",
+            ticket2_title=ticket2.title,
+            similarity_score=score,
+            similarity_reasons=reasons,
+            suggested_action=action,
+            confidence=score,
+        )