claude-mpm 4.1.4__py3-none-any.whl → 4.1.5__py3-none-any.whl

claude_mpm/services/ticket_services/search_service.py

@@ -0,0 +1,324 @@
+"""
+Search service for tickets.
+
+WHY: Extracts search logic into a dedicated service for better
+organization and testability of search functionality.
+
+DESIGN DECISIONS:
+- Supports text-based search across multiple fields
+- Handles filtering by type and status
+- Provides relevance ranking for search results
+- Abstracts search backend (can switch between different implementations)
+"""
+
+from typing import Any, Dict, List, Optional
+
+from ...core.logger import get_logger
+
+
+class TicketSearchService:
+    """Service for searching tickets."""
+
+    def __init__(self, ticket_manager=None):
+        """
+        Initialize the search service.
+
+        Args:
+            ticket_manager: Optional ticket manager instance for testing
+        """
+        self.logger = get_logger("services.ticket_search")
+        self._ticket_manager = ticket_manager
+
+    @property
+    def ticket_manager(self):
+        """Lazy load ticket manager."""
+        if self._ticket_manager is None:
+            try:
+                from ..ticket_manager import TicketManager
+            except ImportError:
+                from claude_mpm.services.ticket_manager import TicketManager
+            self._ticket_manager = TicketManager()
+        return self._ticket_manager
+
+    def search_tickets(
+        self,
+        query: str,
+        type_filter: str = "all",
+        status_filter: str = "all",
+        limit: int = 10,
+        search_fields: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Search tickets by query string.
+
+        Args:
+            query: Search query
+            type_filter: Filter by ticket type
+            status_filter: Filter by status
+            limit: Maximum results to return
+            search_fields: Fields to search in (default: title, description, tags)
+
+        Returns:
+            List of matching tickets
+        """
+        if not search_fields:
+            search_fields = ["title", "description", "tags"]
+
+        try:
+            # Get all available tickets
+            all_tickets = self.ticket_manager.list_recent_tickets(limit=100)
+
+            # Search and filter
+            matched_tickets = []
+            query_lower = query.lower()
+
+            for ticket in all_tickets:
+                # Check if query matches any search field
+                if self._matches_query(ticket, query_lower, search_fields):
+                    # Apply type filter
+                    if not self._passes_type_filter(ticket, type_filter):
+                        continue
+
+                    # Apply status filter
+                    if not self._passes_status_filter(ticket, status_filter):
+                        continue
+
+                    matched_tickets.append(ticket)
+
+                    if len(matched_tickets) >= limit:
+                        break
+
+            # Sort by relevance
+            return self._sort_by_relevance(matched_tickets, query_lower)
+
+        except Exception as e:
+            self.logger.error(f"Error searching tickets: {e}")
+            return []
+
+    def _matches_query(
+        self, ticket: Dict[str, Any], query: str, search_fields: List[str]
+    ) -> bool:
+        """
+        Check if ticket matches the search query.
+
+        Returns:
+            True if ticket matches query in any search field
+        """
+        for field in search_fields:
+            if field == "title" and query in ticket.get("title", "").lower():
+                return True
+
+            if (
+                field == "description"
+                and query in ticket.get("description", "").lower()
+            ):
+                return True
+
+            if field == "tags":
+                tags = ticket.get("tags", [])
+                if any(query in tag.lower() for tag in tags):
+                    return True
+
+            if field == "id" and query in ticket.get("id", "").lower():
+                return True
+
+            # Search in metadata fields
+            if field == "metadata":
+                metadata = ticket.get("metadata", {})
+                for value in metadata.values():
+                    if isinstance(value, str) and query in value.lower():
+                        return True
+
+        return False
+
+    def _passes_type_filter(self, ticket: Dict[str, Any], type_filter: str) -> bool:
+        """
+        Check if ticket passes type filter.
+
+        Returns:
+            True if ticket matches type filter
+        """
+        if type_filter == "all":
+            return True
+
+        ticket_type = ticket.get("metadata", {}).get("ticket_type", "unknown")
+        return ticket_type == type_filter
+
+    def _passes_status_filter(self, ticket: Dict[str, Any], status_filter: str) -> bool:
+        """
+        Check if ticket passes status filter.
+
+        Returns:
+            True if ticket matches status filter
+        """
+        if status_filter == "all":
+            return True
+
+        return ticket.get("status") == status_filter
+
+    def _sort_by_relevance(
+        self, tickets: List[Dict[str, Any]], query: str
+    ) -> List[Dict[str, Any]]:
+        """
+        Sort tickets by relevance to search query.
+
+        Returns:
+            Sorted list of tickets (most relevant first)
+        """
+
+        def relevance_score(ticket):
+            score = 0
+
+            # Title matches are most relevant
+            if query in ticket.get("title", "").lower():
+                score += 10
+
+            # ID matches are very relevant
+            if query in ticket.get("id", "").lower():
+                score += 8
+
+            # Tag matches are moderately relevant
+            tags = ticket.get("tags", [])
+            for tag in tags:
+                if query in tag.lower():
+                    score += 5
+
+            # Description matches are less relevant
+            if query in ticket.get("description", "").lower():
+                score += 2
+
+            # Boost recent tickets slightly
+            if ticket.get("status") in ["open", "in_progress"]:
+                score += 1
+
+            return score
+
+        return sorted(tickets, key=relevance_score, reverse=True)
+
+    def find_similar_tickets(
+        self, ticket_id: str, limit: int = 5
+    ) -> List[Dict[str, Any]]:
+        """
+        Find tickets similar to a given ticket.
+
+        Args:
+            ticket_id: ID of the reference ticket
+            limit: Maximum similar tickets to return
+
+        Returns:
+            List of similar tickets
+        """
+        try:
+            # Get the reference ticket
+            reference = self.ticket_manager.get_ticket(ticket_id)
+            if not reference:
+                return []
+
+            # Extract keywords from title and tags
+            keywords = self._extract_keywords(reference)
+
+            # Search for similar tickets
+            similar = []
+            all_tickets = self.ticket_manager.list_recent_tickets(limit=50)
+
+            for ticket in all_tickets:
+                if ticket["id"] == ticket_id:
+                    continue  # Skip the reference ticket
+
+                # Calculate similarity score
+                score = self._calculate_similarity(reference, ticket, keywords)
+
+                if score > 0:
+                    similar.append((score, ticket))
+
+            # Sort by similarity and return top results
+            similar.sort(key=lambda x: x[0], reverse=True)
+            return [ticket for _, ticket in similar[:limit]]
+
+        except Exception as e:
+            self.logger.error(f"Error finding similar tickets: {e}")
+            return []
+
+    def _extract_keywords(self, ticket: Dict[str, Any]) -> List[str]:
+        """
+        Extract keywords from a ticket for similarity matching.
+
+        Returns:
+            List of keywords
+        """
+        keywords = []
+
+        # Extract words from title
+        title = ticket.get("title", "")
+        keywords.extend(title.lower().split())
+
+        # Add tags as keywords
+        keywords.extend([tag.lower() for tag in ticket.get("tags", [])])
+
+        # Extract key words from description (first 100 chars)
+        desc = ticket.get("description", "")[:100]
+        keywords.extend(desc.lower().split()[:10])
+
+        # Remove common words
+        common_words = {
+            "the",
+            "a",
+            "an",
+            "and",
+            "or",
+            "but",
+            "in",
+            "on",
+            "at",
+            "to",
+            "for",
+        }
+        keywords = [w for w in keywords if w not in common_words and len(w) > 2]
+
+        return list(set(keywords))  # Remove duplicates
+
+    def _calculate_similarity(
+        self, ref_ticket: Dict[str, Any], ticket: Dict[str, Any], keywords: List[str]
+    ) -> float:
+        """
+        Calculate similarity score between two tickets.
+
+        Returns:
+            Similarity score (0-100)
+        """
+        score = 0.0
+
+        # Same type bonus
+        ref_type = ref_ticket.get("metadata", {}).get("ticket_type")
+        ticket_type = ticket.get("metadata", {}).get("ticket_type")
+        if ref_type and ticket_type and ref_type == ticket_type:
+            score += 10
+
+        # Same status bonus
+        if ref_ticket.get("status") == ticket.get("status"):
+            score += 5
+
+        # Same priority bonus
+        if ref_ticket.get("priority") == ticket.get("priority"):
+            score += 3
+
+        # Keyword matches
+        ticket_text = (
+            ticket.get("title", "").lower()
+            + " "
+            + ticket.get("description", "").lower()
+            + " "
+            + " ".join(ticket.get("tags", []))
+        ).lower()
+
+        for keyword in keywords:
+            if keyword in ticket_text:
+                score += 2
+
+        # Common tags
+        ref_tags = set(ref_ticket.get("tags", []))
+        ticket_tags = set(ticket.get("tags", []))
+        common_tags = ref_tags.intersection(ticket_tags)
+        score += len(common_tags) * 5
+
+        return min(score, 100)  # Cap at 100

claude_mpm/services/ticket_services/validation_service.py

@@ -0,0 +1,303 @@
+"""
+Input validation service for tickets.
+
+WHY: Centralizes all validation logic to ensure data integrity and
+provide consistent error messages across the ticket system.
+
+DESIGN DECISIONS:
+- Returns validation results with detailed error messages
+- Validates ticket IDs, types, statuses, priorities
+- Handles pagination parameter validation
+- Provides sanitization for user inputs
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class TicketValidationService:
+    """Service for validating ticket inputs."""
+
+    # Valid ticket types
+    VALID_TYPES = ["task", "issue", "epic", "bug", "feature", "story"]
+
+    # Valid ticket statuses
+    VALID_STATUSES = [
+        "open",
+        "in_progress",
+        "ready",
+        "tested",
+        "done",
+        "waiting",
+        "closed",
+        "blocked",
+        "all",
+    ]
+
+    # Valid priorities
+    VALID_PRIORITIES = ["low", "medium", "high", "critical"]
+
+    # Valid workflow states
+    VALID_WORKFLOW_STATES = [
+        "todo",
+        "in_progress",
+        "ready",
+        "tested",
+        "done",
+        "blocked",
+    ]
+
+    def validate_ticket_id(self, ticket_id: Any) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket ID.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not ticket_id:
+            return False, "No ticket ID provided"
+
+        if not isinstance(ticket_id, str):
+            return False, "Ticket ID must be a string"
+
+        if len(ticket_id) < 3:
+            return False, "Invalid ticket ID format"
+
+        return True, None
+
+    def validate_ticket_type(self, ticket_type: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket type.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not ticket_type:
+            return True, None  # Type is optional, default will be used
+
+        if ticket_type not in self.VALID_TYPES:
+            return (
+                False,
+                f"Invalid ticket type: {ticket_type}. Valid types: {', '.join(self.VALID_TYPES)}",
+            )
+
+        return True, None
+
+    def validate_status(self, status: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket status.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not status:
+            return True, None  # Status is optional
+
+        if status not in self.VALID_STATUSES:
+            return (
+                False,
+                f"Invalid status: {status}. Valid statuses: {', '.join(self.VALID_STATUSES)}",
+            )
+
+        return True, None
+
+    def validate_priority(self, priority: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a ticket priority.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not priority:
+            return True, None  # Priority is optional, default will be used
+
+        if priority not in self.VALID_PRIORITIES:
+            return (
+                False,
+                f"Invalid priority: {priority}. Valid priorities: {', '.join(self.VALID_PRIORITIES)}",
+            )
+
+        return True, None
+
+    def validate_workflow_state(self, state: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a workflow state.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not state:
+            return False, "No workflow state provided"
+
+        if state not in self.VALID_WORKFLOW_STATES:
+            return (
+                False,
+                f"Invalid workflow state: {state}. Valid states: {', '.join(self.VALID_WORKFLOW_STATES)}",
+            )
+
+        return True, None
+
+    def validate_pagination(
+        self, page: int, page_size: int
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate pagination parameters.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if page < 1:
+            return False, "Page number must be 1 or greater"
+
+        if page_size < 1:
+            return False, "Page size must be 1 or greater"
+
+        if page_size > 100:
+            return False, "Page size cannot exceed 100"
+
+        return True, None
+
+    def validate_create_params(
+        self, params: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate parameters for ticket creation.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # Title is required
+        if not params.get("title"):
+            return False, "Title is required for ticket creation"
+
+        if len(params["title"]) < 3:
+            return False, "Title must be at least 3 characters long"
+
+        if len(params["title"]) > 200:
+            return False, "Title cannot exceed 200 characters"
+
+        # Validate optional fields if provided
+        if "type" in params:
+            valid, error = self.validate_ticket_type(params["type"])
+            if not valid:
+                return False, error
+
+        if "priority" in params:
+            valid, error = self.validate_priority(params["priority"])
+            if not valid:
+                return False, error
+
+        # Validate parent references
+        if params.get("parent_epic"):
+            valid, error = self.validate_ticket_id(params["parent_epic"])
+            if not valid:
+                return False, f"Invalid parent epic: {error}"
+
+        if params.get("parent_issue"):
+            valid, error = self.validate_ticket_id(params["parent_issue"])
+            if not valid:
+                return False, f"Invalid parent issue: {error}"
+
+        return True, None
+
+    def validate_update_params(
+        self, params: Dict[str, Any]
+    ) -> Tuple[bool, Optional[str]]:
+        """
+        Validate parameters for ticket update.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        # At least one update field must be provided
+        update_fields = ["status", "priority", "description", "tags", "assign"]
+        if not any(field in params for field in update_fields):
+            return False, "No update fields specified"
+
+        # Validate status if provided
+        if "status" in params:
+            valid, error = self.validate_status(params["status"])
+            if not valid:
+                return False, error
+
+        # Validate priority if provided
+        if "priority" in params:
+            valid, error = self.validate_priority(params["priority"])
+            if not valid:
+                return False, error
+
+        return True, None
+
+    def sanitize_tags(self, tags: Any) -> List[str]:
+        """
+        Sanitize and parse tags input.
+
+        Returns:
+            List of sanitized tags
+        """
+        if not tags:
+            return []
+
+        if isinstance(tags, str):
+            # Split comma-separated tags
+            tag_list = [tag.strip() for tag in tags.split(",")]
+        elif isinstance(tags, list):
+            tag_list = [str(tag).strip() for tag in tags]
+        else:
+            return []
+
+        # Remove empty tags and duplicates
+        return list(filter(None, dict.fromkeys(tag_list)))
+
+    def sanitize_description(self, description: Any) -> str:
+        """
+        Sanitize description input.
+
+        Returns:
+            Sanitized description string
+        """
+        if not description:
+            return ""
+
+        if isinstance(description, list):
+            # Join list elements with spaces
+            return " ".join(str(item) for item in description)
+
+        return str(description).strip()
+
+    def validate_search_query(self, query: str) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a search query.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not query:
+            return False, "Search query cannot be empty"
+
+        if len(query) < 2:
+            return False, "Search query must be at least 2 characters"
+
+        if len(query) > 100:
+            return False, "Search query cannot exceed 100 characters"
+
+        return True, None
+
+    def validate_comment(self, comment: Any) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a comment.
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not comment:
+            return False, "Comment cannot be empty"
+
+        comment_str = self.sanitize_description(comment)
+
+        if len(comment_str) < 1:
+            return False, "Comment cannot be empty"
+
+        if len(comment_str) > 5000:
+            return False, "Comment cannot exceed 5000 characters"
+
+        return True, None