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

mcp_ticketer/adapters/linear/types.py

@@ -3,47 +3,47 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Dict
+from typing import Any
 
 from mcp_ticketer.core.models import Priority, TicketState
 
 
 class LinearPriorityMapping:
     """Mapping between universal Priority and Linear priority values."""
-    
+
     # Linear uses numeric priorities: 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low
-    TO_LINEAR: Dict[Priority, int] = {
+    TO_LINEAR: dict[Priority, int] = {
         Priority.CRITICAL: 1,  # Urgent
-        Priority.HIGH: 2,      # High
-        Priority.MEDIUM: 3,    # Medium
-        Priority.LOW: 4,       # Low
+        Priority.HIGH: 2,  # High
+        Priority.MEDIUM: 3,  # Medium
+        Priority.LOW: 4,  # Low
     }
-    
-    FROM_LINEAR: Dict[int, Priority] = {
-        0: Priority.LOW,       # No priority -> Low
+
+    FROM_LINEAR: dict[int, Priority] = {
+        0: Priority.LOW,  # No priority -> Low
         1: Priority.CRITICAL,  # Urgent -> Critical
-        2: Priority.HIGH,      # High -> High
-        3: Priority.MEDIUM,    # Medium -> Medium
-        4: Priority.LOW,       # Low -> Low
+        2: Priority.HIGH,  # High -> High
+        3: Priority.MEDIUM,  # Medium -> Medium
+        4: Priority.LOW,  # Low -> Low
     }
 
 
 class LinearStateMapping:
     """Mapping between universal TicketState and Linear workflow state types."""
-    
+
     # Linear workflow state types
-    TO_LINEAR: Dict[TicketState, str] = {
+    TO_LINEAR: dict[TicketState, str] = {
         TicketState.OPEN: "unstarted",
         TicketState.IN_PROGRESS: "started",
         TicketState.READY: "unstarted",  # No direct equivalent, use unstarted
-        TicketState.TESTED: "started",   # No direct equivalent, use started
+        TicketState.TESTED: "started",  # No direct equivalent, use started
         TicketState.DONE: "completed",
         TicketState.CLOSED: "canceled",
         TicketState.WAITING: "unstarted",
         TicketState.BLOCKED: "unstarted",
     }
-    
-    FROM_LINEAR: Dict[str, TicketState] = {
+
+    FROM_LINEAR: dict[str, TicketState] = {
         "backlog": TicketState.OPEN,
         "unstarted": TicketState.OPEN,
         "started": TicketState.IN_PROGRESS,
@@ -51,10 +51,38 @@ class LinearStateMapping:
         "canceled": TicketState.CLOSED,
     }
 
+    # Semantic state name mappings for flexible workflow matching (1M-552)
+    # Maps universal states to common Linear state names (case-insensitive)
+    SEMANTIC_NAMES: dict[TicketState, list[str]] = {
+        TicketState.OPEN: ["todo", "to do", "open", "new", "backlog"],
+        TicketState.READY: ["ready", "triage", "ready for dev", "ready to start"],
+        TicketState.TESTED: [
+            "tested",
+            "in review",
+            "review",
+            "qa",
+            "testing",
+            "ready for review",
+        ],
+        TicketState.WAITING: ["waiting", "on hold", "paused"],
+        TicketState.BLOCKED: ["blocked"],
+        TicketState.IN_PROGRESS: [
+            "in progress",
+            "in-progress",
+            "started",
+            "doing",
+            "active",
+            "in development",
+            "in dev",
+        ],
+        TicketState.DONE: ["done", "completed", "finished"],
+        TicketState.CLOSED: ["closed", "canceled", "cancelled", "won't do", "wont do"],
+    }
+
 
 class LinearWorkflowStateType(Enum):
     """Linear workflow state types."""
-    
+
     BACKLOG = "backlog"
     UNSTARTED = "unstarted"
     STARTED = "started"
@@ -64,7 +92,7 @@ class LinearWorkflowStateType(Enum):
 
 class LinearProjectState(Enum):
     """Linear project states."""
-    
+
     PLANNED = "planned"
     STARTED = "started"
     COMPLETED = "completed"
@@ -74,7 +102,7 @@ class LinearProjectState(Enum):
 
 class LinearIssueRelationType(Enum):
     """Linear issue relation types."""
-    
+
     BLOCKS = "blocks"
     BLOCKED_BY = "blockedBy"
     DUPLICATE = "duplicate"
@@ -84,57 +112,143 @@ class LinearIssueRelationType(Enum):
 
 class LinearCommentType(Enum):
     """Linear comment types."""
-    
+
     COMMENT = "comment"
     SYSTEM = "system"
 
 
 def get_linear_priority(priority: Priority) -> int:
     """Convert universal Priority to Linear priority value.
-    
+
     Args:
         priority: Universal priority enum
-        
+
     Returns:
         Linear priority integer (0-4)
+
     """
     return LinearPriorityMapping.TO_LINEAR.get(priority, 3)  # Default to Medium
 
 
 def get_universal_priority(linear_priority: int) -> Priority:
     """Convert Linear priority value to universal Priority.
-    
+
     Args:
         linear_priority: Linear priority integer (0-4)
-        
+
     Returns:
         Universal priority enum
+
     """
     return LinearPriorityMapping.FROM_LINEAR.get(linear_priority, Priority.MEDIUM)
 
 
 def get_linear_state_type(state: TicketState) -> str:
     """Convert universal TicketState to Linear workflow state type.
-    
+
     Args:
         state: Universal ticket state enum
-        
+
     Returns:
         Linear workflow state type string
+
     """
     return LinearStateMapping.TO_LINEAR.get(state, "unstarted")
 
 
-def get_universal_state(linear_state_type: str) -> TicketState:
-    """Convert Linear workflow state type to universal TicketState.
-    
+def get_universal_state(
+    linear_state_type: str, state_name: str | None = None
+) -> TicketState:
+    """Convert Linear workflow state type to universal TicketState with synonym matching.
+
+    This function implements intelligent state mapping with fallback strategies:
+    1. Try exact match on state type (backlog, unstarted, started, completed, canceled)
+    2. Try synonym matching on state name (ToDo, In Review, Testing, etc.)
+    3. Default to OPEN for unknown states
+
+    Synonym Matching Rules (ticket 1M-164, fixed in v2.0.4):
+    - "done", "completed", "finished", "resolved" → DONE
+    - "closed", "canceled", "cancelled", "won't do" → CLOSED
+    - Everything else → OPEN
+
     Args:
-        linear_state_type: Linear workflow state type string
-        
+        linear_state_type: Linear workflow state type string (from state.type field)
+        state_name: Linear workflow state name (from state.name field, optional)
+
     Returns:
         Universal ticket state enum
+
     """
-    return LinearStateMapping.FROM_LINEAR.get(linear_state_type, TicketState.OPEN)
+    # First try exact type match
+    if linear_state_type in LinearStateMapping.FROM_LINEAR:
+        return LinearStateMapping.FROM_LINEAR[linear_state_type]
+
+    # If no exact match and state_name provided, try synonym matching
+    if state_name:
+        state_name_lower = state_name.lower().strip()
+
+        # DONE states: Work successfully completed
+        # - User finished the work
+        # - Requirements met
+        # - Quality verified
+        done_synonyms = [
+            "done",
+            "completed",
+            "finished",
+            "resolved",
+        ]
+
+        if any(synonym in state_name_lower for synonym in done_synonyms):
+            return TicketState.DONE
+
+        # CLOSED states: Work terminated without completion
+        # - User decided not to do it
+        # - Requirements changed
+        # - Duplicate/invalid ticket
+        closed_synonyms = [
+            "closed",
+            "cancelled",
+            "canceled",
+            "won't do",
+            "wont do",
+            "rejected",
+        ]
+
+        if any(synonym in state_name_lower for synonym in closed_synonyms):
+            return TicketState.CLOSED
+
+        # Check for "in progress" synonyms
+        in_progress_synonyms = [
+            "in progress",
+            "in-progress",
+            "working",
+            "active",
+            "started",
+            "doing",
+            "in development",
+            "in dev",
+        ]
+
+        if any(synonym in state_name_lower for synonym in in_progress_synonyms):
+            return TicketState.IN_PROGRESS
+
+        # Check for "review/testing" synonyms
+        review_synonyms = [
+            "review",
+            "in review",
+            "in-review",
+            "testing",
+            "in test",
+            "in-test",
+            "qa",
+            "ready for review",
+        ]
+
+        if any(synonym in state_name_lower for synonym in review_synonyms):
+            return TicketState.READY
+
+    # Default: everything else is OPEN (including "ToDo", "Backlog", "To Do", etc.)
+    return TicketState.OPEN
 
 
 def build_issue_filter(
@@ -143,57 +257,64 @@ def build_issue_filter(
     priority: Priority | None = None,
     team_id: str | None = None,
     project_id: str | None = None,
+    parent_id: str | None = None,
     labels: list[str] | None = None,
     created_after: str | None = None,
     updated_after: str | None = None,
     due_before: str | None = None,
     include_archived: bool = False,
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     """Build a Linear issue filter from parameters.
-    
+
     Args:
         state: Filter by ticket state
         assignee_id: Filter by assignee Linear user ID
         priority: Filter by priority
         team_id: Filter by team ID
         project_id: Filter by project ID
+        parent_id: Filter by parent issue ID (for listing sub-issues)
         labels: Filter by label names
         created_after: Filter by creation date (ISO string)
         updated_after: Filter by update date (ISO string)
         due_before: Filter by due date (ISO string)
         include_archived: Whether to include archived issues
-        
+
     Returns:
         Linear GraphQL filter object
+
     """
-    issue_filter: Dict[str, Any] = {}
-    
+    issue_filter: dict[str, Any] = {}
+
     # Team filter (required for most operations)
     if team_id:
         issue_filter["team"] = {"id": {"eq": team_id}}
-    
+
     # State filter
     if state:
         state_type = get_linear_state_type(state)
         issue_filter["state"] = {"type": {"eq": state_type}}
-    
+
     # Assignee filter
     if assignee_id:
         issue_filter["assignee"] = {"id": {"eq": assignee_id}}
-    
+
     # Priority filter
     if priority:
         linear_priority = get_linear_priority(priority)
         issue_filter["priority"] = {"eq": linear_priority}
-    
+
     # Project filter
     if project_id:
         issue_filter["project"] = {"id": {"eq": project_id}}
-    
+
+    # Parent filter (for listing children/sub-issues)
+    if parent_id:
+        issue_filter["parent"] = {"id": {"eq": parent_id}}
+
     # Labels filter
     if labels:
         issue_filter["labels"] = {"some": {"name": {"in": labels}}}
-    
+
     # Date filters
     if created_after:
         issue_filter["createdAt"] = {"gte": created_after}
@@ -201,11 +322,11 @@ def build_issue_filter(
         issue_filter["updatedAt"] = {"gte": updated_after}
     if due_before:
         issue_filter["dueDate"] = {"lte": due_before}
-    
+
     # Archived filter
     if not include_archived:
         issue_filter["archivedAt"] = {"null": True}
-    
+
     return issue_filter
 
 
@@ -213,65 +334,67 @@ def build_project_filter(
     state: str | None = None,
     team_id: str | None = None,
     include_completed: bool = True,
-) -> Dict[str, Any]:
+) -> dict[str, Any]:
     """Build a Linear project filter from parameters.
-    
+
     Args:
         state: Filter by project state
         team_id: Filter by team ID
         include_completed: Whether to include completed projects
-        
+
     Returns:
         Linear GraphQL filter object
+
     """
-    project_filter: Dict[str, Any] = {}
-    
+    project_filter: dict[str, Any] = {}
+
     # Team filter
     if team_id:
         project_filter["teams"] = {"some": {"id": {"eq": team_id}}}
-    
+
     # State filter
     if state:
         project_filter["state"] = {"eq": state}
     elif not include_completed:
         # Exclude completed projects by default
         project_filter["state"] = {"neq": "completed"}
-    
+
     return project_filter
 
 
-def extract_linear_metadata(issue_data: Dict[str, Any]) -> Dict[str, Any]:
+def extract_linear_metadata(issue_data: dict[str, Any]) -> dict[str, Any]:
     """Extract Linear-specific metadata from issue data.
-    
+
     Args:
         issue_data: Raw Linear issue data from GraphQL
-        
+
     Returns:
         Dictionary of Linear-specific metadata
+
     """
     metadata = {}
-    
+
     # Extract Linear-specific fields
     if "dueDate" in issue_data and issue_data["dueDate"]:
         metadata["due_date"] = issue_data["dueDate"]
-    
+
     if "cycle" in issue_data and issue_data["cycle"]:
         metadata["cycle_id"] = issue_data["cycle"]["id"]
         metadata["cycle_name"] = issue_data["cycle"]["name"]
-    
+
     if "estimate" in issue_data and issue_data["estimate"]:
         metadata["estimate"] = issue_data["estimate"]
-    
+
     if "branchName" in issue_data and issue_data["branchName"]:
         metadata["branch_name"] = issue_data["branchName"]
-    
+
     if "url" in issue_data:
         metadata["linear_url"] = issue_data["url"]
-    
+
     if "slaBreachesAt" in issue_data and issue_data["slaBreachesAt"]:
         metadata["sla_breaches_at"] = issue_data["slaBreachesAt"]
-    
+
     if "customerTicketCount" in issue_data:
         metadata["customer_ticket_count"] = issue_data["customerTicketCount"]
-    
+
     return metadata

mcp_ticketer/adapters/linear.py

@@ -8,8 +8,8 @@ For new code, import directly from the linear package:
     from mcp_ticketer.adapters.linear import LinearAdapter
 """
 
-# Import the refactored adapter
-from .linear import LinearAdapter
+# Import the refactored adapter from the modular structure
+from .linear.adapter import LinearAdapter
 
 # Re-export for backward compatibility
 __all__ = ["LinearAdapter"]

mcp_ticketer/analysis/__init__.py

@@ -0,0 +1,56 @@
+"""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
+- Dependency graph: Build and analyze ticket dependency graphs
+- Health assessment: Assess project health based on ticket metrics
+- Project status: Comprehensive project status analysis and work planning
+
+These tools help product managers maintain ticket health and development practices.
+
+Note: Some analysis features require optional dependencies (scikit-learn, rapidfuzz).
+Install with: pip install mcp-ticketer[analysis]
+"""
+
+# Import dependency graph and health assessment (no optional deps required)
+from .dependency_graph import DependencyGraph, DependencyNode
+from .health_assessment import HealthAssessor, HealthMetrics, ProjectHealth
+from .project_status import ProjectStatusResult, StatusAnalyzer, TicketRecommendation
+
+# Import optional analysis modules (may fail if dependencies not installed)
+try:
+    from .orphaned import OrphanedResult, OrphanedTicketDetector
+    from .similarity import SimilarityResult, TicketSimilarityAnalyzer
+    from .staleness import StalenessResult, StaleTicketDetector
+
+    ANALYSIS_AVAILABLE = True
+except ImportError:
+    # Set placeholder values when optional deps not available
+    OrphanedResult = None  # type: ignore
+    OrphanedTicketDetector = None  # type: ignore
+    SimilarityResult = None  # type: ignore
+    TicketSimilarityAnalyzer = None  # type: ignore
+    StalenessResult = None  # type: ignore
+    StaleTicketDetector = None  # type: ignore
+    ANALYSIS_AVAILABLE = False
+
+__all__ = [
+    "DependencyGraph",
+    "DependencyNode",
+    "HealthAssessor",
+    "HealthMetrics",
+    "ProjectHealth",
+    "ProjectStatusResult",
+    "StatusAnalyzer",
+    "TicketRecommendation",
+    "SimilarityResult",
+    "TicketSimilarityAnalyzer",
+    "StalenessResult",
+    "StaleTicketDetector",
+    "OrphanedResult",
+    "OrphanedTicketDetector",
+    "ANALYSIS_AVAILABLE",
+]