claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/templates/questions/ticket_mgmt.py

@@ -0,0 +1,394 @@
+"""Ticket management question templates.
+
+This module provides templates for gathering user preferences about ticket
+prioritization, scope, and management during sprint planning and execution.
+
+Templates:
+- TicketPrioritizationTemplate: How to order/prioritize tickets
+- TicketScopeTemplate: Testing and documentation requirements per ticket
+- TicketDependencyTemplate: How to handle ticket dependencies
+
+These templates help PM make informed decisions about ticket execution order
+and completeness criteria.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from claude_mpm.templates.questions.base import ConditionalTemplate
+from claude_mpm.utils.structured_questions import QuestionBuilder, QuestionSet
+
+if TYPE_CHECKING:
+    from claude_mpm.utils.structured_questions import StructuredQuestion
+
+
+class TicketPrioritizationTemplate(ConditionalTemplate):
+    """Template for ticket prioritization decisions.
+
+    Asks about:
+    - How to order tickets (priority-based, dependency-based, etc.)
+    - Whether to work serially or in parallel
+    - How to handle blockers
+
+    Context Parameters:
+        num_tickets (int): Number of tickets to prioritize
+        has_dependencies (bool): Whether tickets have interdependencies
+        team_size (int): Number of engineers available
+
+    Example:
+        >>> template = TicketPrioritizationTemplate(
+        ...     num_tickets=5,
+        ...     has_dependencies=True,
+        ...     team_size=1
+        ... )
+        >>> question_set = template.build()
+    """
+
+    def __init__(
+        self,
+        num_tickets: int = 1,
+        has_dependencies: bool = False,
+        team_size: int = 1,
+        **context,
+    ):
+        """Initialize ticket prioritization template.
+
+        Args:
+            num_tickets: Number of tickets to manage
+            has_dependencies: Whether tickets depend on each other
+            team_size: Number of engineers available
+            **context: Additional context values
+        """
+        super().__init__(
+            num_tickets=num_tickets,
+            has_dependencies=has_dependencies,
+            team_size=team_size,
+            **context,
+        )
+
+    def build(self) -> QuestionSet:
+        """Build ticket prioritization questions.
+
+        Returns:
+            QuestionSet with prioritization questions
+        """
+        num_tickets = self.get_context("num_tickets", 1)
+        has_dependencies = self.get_context("has_dependencies", False)
+        team_size = self.get_context("team_size", 1)
+
+        questions: list[StructuredQuestion] = []
+
+        # Question 1: Prioritization strategy (only if multiple tickets)
+        if num_tickets > 1:
+            if has_dependencies:
+                priority_question = (
+                    QuestionBuilder()
+                    .ask("How should we handle ticket dependencies?")
+                    .header("Dependencies")
+                    .add_option(
+                        "Sequential execution",
+                        "Complete tickets in dependency order (foundational work first)",
+                    )
+                    .add_option(
+                        "Parallel where possible",
+                        "Work on independent tickets in parallel, sequential for dependent ones",
+                    )
+                    .build()
+                )
+            else:
+                priority_question = (
+                    QuestionBuilder()
+                    .ask("How should we prioritize the tickets?")
+                    .header("Priority")
+                    .add_option(
+                        "User-visible first",
+                        "Prioritize features that directly impact users",
+                    )
+                    .add_option(
+                        "Infrastructure first",
+                        "Build foundational components before user-facing features",
+                    )
+                    .add_option(
+                        "Quick wins first",
+                        "Start with easiest tickets to build momentum",
+                    )
+                    .add_option(
+                        "High risk first",
+                        "Tackle uncertain/risky tickets early to derisk project",
+                    )
+                    .build()
+                )
+            questions.append(priority_question)
+
+        # Question 2: Execution strategy (only if multiple tickets and team)
+        if num_tickets > 1 and team_size >= 1:
+            execution_question = (
+                QuestionBuilder()
+                .ask("How should tickets be executed?")
+                .header("Execution")
+                .add_option(
+                    "One at a time",
+                    "Complete each ticket fully before starting the next",
+                )
+                .add_option(
+                    "Parallel execution",
+                    "Work on multiple tickets simultaneously when possible",
+                )
+                .build()
+            )
+            questions.append(execution_question)
+
+        # Fallback for single ticket or default case
+        if not questions:
+            scope_question = (
+                QuestionBuilder()
+                .ask("What should be the ticket completion criteria?")
+                .header("Criteria")
+                .add_option(
+                    "Implementation only",
+                    "Code implementation complete, basic functionality working",
+                )
+                .add_option(
+                    "Implementation + tests",
+                    "Code complete with passing unit tests",
+                )
+                .build()
+            )
+            questions.append(scope_question)
+
+        return QuestionSet(questions)
+
+
+class TicketScopeTemplate(ConditionalTemplate):
+    """Template for ticket scope and completeness requirements.
+
+    Asks about:
+    - Testing requirements (unit, integration, e2e)
+    - Documentation requirements
+    - Code review requirements
+    - Definition of done
+
+    Context Parameters:
+        ticket_type (str): Type of ticket (feature, bug, refactor)
+        is_user_facing (bool): Whether ticket affects end users
+        project_maturity (str): Project stage (prototype, beta, production)
+
+    Example:
+        >>> template = TicketScopeTemplate(
+        ...     ticket_type="feature",
+        ...     is_user_facing=True,
+        ...     project_maturity="production"
+        ... )
+        >>> question_set = template.build()
+    """
+
+    def __init__(
+        self,
+        ticket_type: str | None = "feature",
+        is_user_facing: bool = False,
+        project_maturity: str = "development",
+        **context,
+    ):
+        """Initialize ticket scope template.
+
+        Args:
+            ticket_type: Type of ticket (feature, bug, refactor, etc.)
+            is_user_facing: Whether changes affect end users
+            project_maturity: Stage of project (prototype, development, production)
+            **context: Additional context values
+        """
+        super().__init__(
+            ticket_type=ticket_type,
+            is_user_facing=is_user_facing,
+            project_maturity=project_maturity,
+            **context,
+        )
+
+    def build(self) -> QuestionSet:
+        """Build ticket scope questions.
+
+        Returns:
+            QuestionSet with scope questions
+        """
+        ticket_type = self.get_context("ticket_type", "feature")
+        is_user_facing = self.get_context("is_user_facing", False)
+        project_maturity = self.get_context("project_maturity", "development")
+
+        questions: list[StructuredQuestion] = []
+
+        # Question 1: Testing requirements
+        if project_maturity == "production" or is_user_facing:
+            testing_question = (
+                QuestionBuilder()
+                .ask("What testing is required for this ticket?")
+                .header("Testing")
+                .add_option(
+                    "Comprehensive",
+                    "Unit tests, integration tests, and e2e tests required",
+                )
+                .add_option(
+                    "Standard",
+                    "Unit tests and integration tests for critical paths",
+                )
+                .add_option(
+                    "Basic",
+                    "Unit tests for core functionality only",
+                )
+                .build()
+            )
+        else:
+            testing_question = (
+                QuestionBuilder()
+                .ask("What testing is required for this ticket?")
+                .header("Testing")
+                .add_option(
+                    "Unit tests",
+                    "Unit tests covering core functionality",
+                )
+                .add_option(
+                    "Integration tests",
+                    "Integration tests for component interactions",
+                )
+                .add_option(
+                    "Manual testing",
+                    "Manual verification sufficient for now",
+                )
+                .build()
+            )
+        questions.append(testing_question)
+
+        # Question 2: Documentation requirements
+        if is_user_facing or ticket_type == "feature":
+            docs_question = (
+                QuestionBuilder()
+                .ask("What documentation is needed?")
+                .header("Docs")
+                .add_option(
+                    "Full documentation",
+                    "API docs, user guide, and code comments",
+                )
+                .add_option(
+                    "API docs only",
+                    "Document public interfaces and usage examples",
+                )
+                .add_option(
+                    "Code comments",
+                    "Inline comments for complex logic only",
+                )
+                .add_option(
+                    "None",
+                    "Code is self-documenting, no additional docs needed",
+                )
+                .build()
+            )
+            questions.append(docs_question)
+
+        return QuestionSet(questions)
+
+
+class TicketDependencyTemplate(ConditionalTemplate):
+    """Template for handling ticket dependencies and blocking issues.
+
+    Asks about:
+    - How to handle blocked tickets
+    - Whether to wait or work around dependencies
+    - Parallel work strategies
+
+    Context Parameters:
+        blocked_tickets (int): Number of tickets currently blocked
+        blocking_type (str): Type of blocker (technical, external, approval)
+
+    Example:
+        >>> template = TicketDependencyTemplate(
+        ...     blocked_tickets=2,
+        ...     blocking_type="external"
+        ... )
+        >>> question_set = template.build()
+    """
+
+    def __init__(
+        self,
+        blocked_tickets: int = 0,
+        blocking_type: str | None = None,
+        **context,
+    ):
+        """Initialize ticket dependency template.
+
+        Args:
+            blocked_tickets: Number of blocked tickets
+            blocking_type: Type of blocker (technical, external, approval, etc.)
+            **context: Additional context values
+        """
+        super().__init__(
+            blocked_tickets=blocked_tickets, blocking_type=blocking_type, **context
+        )
+
+    def build(self) -> QuestionSet:
+        """Build dependency handling questions.
+
+        Returns:
+            QuestionSet with dependency questions
+        """
+        blocked_tickets = self.get_context("blocked_tickets", 0)
+        blocking_type = self.get_context("blocking_type")
+
+        questions: list[StructuredQuestion] = []
+
+        # Question about handling blockers
+        if blocked_tickets > 0:
+            if blocking_type == "external":
+                blocker_question = (
+                    QuestionBuilder()
+                    .ask("How should we handle external dependencies?")
+                    .header("Blockers")
+                    .add_option(
+                        "Wait for unblock",
+                        "Pause blocked tickets until external dependency resolves",
+                    )
+                    .add_option(
+                        "Mock and continue",
+                        "Create mocks/stubs to continue development",
+                    )
+                    .add_option(
+                        "Work around",
+                        "Find alternative implementation to avoid dependency",
+                    )
+                    .build()
+                )
+            else:
+                blocker_question = (
+                    QuestionBuilder()
+                    .ask("How should we handle blocked tickets?")
+                    .header("Blockers")
+                    .add_option(
+                        "Resolve blockers first",
+                        "Prioritize unblocking tickets before continuing",
+                    )
+                    .add_option(
+                        "Parallel work",
+                        "Work on unblocked tickets while resolving blockers",
+                    )
+                    .build()
+                )
+            questions.append(blocker_question)
+
+        # Default question if no specific blockers
+        if not questions:
+            dependency_question = (
+                QuestionBuilder()
+                .ask("How should we manage ticket dependencies?")
+                .header("Dependencies")
+                .add_option(
+                    "Strict ordering",
+                    "Maintain strict dependency order, wait for prerequisites",
+                )
+                .add_option(
+                    "Flexible approach",
+                    "Start dependent work in parallel with preparation work",
+                )
+                .build()
+            )
+            questions.append(dependency_question)
+
+        return QuestionSet(questions)

claude_mpm/ticket_wrapper.py

@@ -7,7 +7,6 @@ that was moved to the scripts directory.
 """
 
 import sys
-import os
 from pathlib import Path
 
 # Add scripts directory to path so we can import the ticket module
@@ -20,10 +19,11 @@ try:
 except ImportError:
     # Fallback if direct import fails
     import importlib.util
+
     ticket_path = scripts_dir / "ticket.py"
     spec = importlib.util.spec_from_file_location("ticket", ticket_path)
     ticket_module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(ticket_module)
     main = ticket_module.main
 
-__all__ = ["main"]
+__all__ = ["main"]

claude_mpm/tools/__init__.py

@@ -0,0 +1,10 @@
+"""
+Tools package for Claude MPM.
+
+This package contains utility tools and debugging modules for Claude MPM,
+including code analysis tools, SocketIO debugging utilities, and other
+development helpers.
+
+This __init__.py file is required to make this directory recognizable as a
+Python package by setuptools for proper distribution and imports.
+"""

claude_mpm/tools/__main__.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""
+Code Tree Analyzer CLI Module
+==============================
+
+WHY: Provides command-line interface for the code tree analyzer,
+allowing it to be run as a subprocess from the dashboard.
+
+DESIGN DECISIONS:
+- Support JSON streaming output for real-time event processing
+- Provide both file output and stdout streaming modes
+- Include comprehensive error handling and logging
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .code_tree_analyzer import CodeTreeAnalyzer
+
+
+def parse_arguments():
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Analyze code structure and emit events"
+    )
+
+    parser.add_argument(
+        "--path", type=str, required=True, help="Directory path to analyze"
+    )
+
+    parser.add_argument(
+        "--languages",
+        type=str,
+        help="Comma-separated list of languages to include (e.g., python,javascript)",
+    )
+
+    parser.add_argument(
+        "--max-depth", type=int, help="Maximum directory depth to traverse"
+    )
+
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        help="Patterns to ignore (can be specified multiple times)",
+    )
+
+    parser.add_argument(
+        "--emit-events", action="store_true", help="Enable Socket.IO event emission"
+    )
+
+    parser.add_argument(
+        "--output-format",
+        choices=["json", "json-stream", "summary"],
+        default="summary",
+        help="Output format (default: summary)",
+    )
+
+    parser.add_argument(
+        "--output-file", type=str, help="Output file path (stdout if not specified)"
+    )
+
+    parser.add_argument(
+        "--cache-dir", type=str, help="Directory for caching analysis results"
+    )
+
+    return parser.parse_args()
+
+
+def emit_json_event(event_type: str, data: dict, file=None):
+    """Emit a JSON event to stdout or file.
+
+    Args:
+        event_type: Type of event
+        data: Event data
+        file: Output file handle (stdout if None)
+    """
+    event = {"type": event_type, "data": data}
+
+    output = json.dumps(event)
+    if file:
+        file.write(output + "\n")
+        file.flush()
+    else:
+        print(output, flush=True)
+
+
+def main():
+    """Main entry point for the analyzer CLI."""
+    args = parse_arguments()
+
+    # Parse path
+    path = Path(args.path).resolve()
+    if not path.exists():
+        emit_json_event(
+            "code:analysis:error", {"message": f"Path does not exist: {args.path}"}
+        )
+        sys.exit(1)
+
+    if not path.is_dir():
+        emit_json_event(
+            "code:analysis:error", {"message": f"Path is not a directory: {args.path}"}
+        )
+        sys.exit(1)
+
+    # Parse languages
+    languages = None
+    if args.languages:
+        languages = [lang.strip() for lang in args.languages.split(",")]
+
+    # Parse cache directory
+    cache_dir = None
+    if args.cache_dir:
+        cache_dir = Path(args.cache_dir)
+
+    # Open output file if specified
+    output_file = None
+    if args.output_file:
+        try:
+            output_file = Path(args.output_file).open("w")
+        except Exception as e:
+            emit_json_event(
+                "code:analysis:error", {"message": f"Failed to open output file: {e}"}
+            )
+            sys.exit(1)
+
+    try:
+        # Create analyzer
+        analyzer = CodeTreeAnalyzer(emit_events=args.emit_events, cache_dir=cache_dir)
+
+        # Emit start event for JSON stream format
+        if args.output_format == "json-stream":
+            emit_json_event(
+                "code:analysis:start",
+                {
+                    "path": str(path),
+                    "languages": languages,
+                    "max_depth": args.max_depth,
+                },
+                output_file,
+            )
+
+        # Run analysis
+        result = analyzer.analyze_directory(
+            directory=path,
+            languages=languages,
+            ignore_patterns=args.ignore,
+            max_depth=args.max_depth,
+        )
+
+        # Output results based on format
+        if args.output_format == "json":
+            # Full JSON output
+            output = json.dumps(result, indent=2, default=str)
+            if output_file:
+                output_file.write(output)
+            else:
+                print(output)
+
+        elif args.output_format == "json-stream":
+            # Streaming JSON events (already emitted during analysis)
+            emit_json_event(
+                "code:analysis:complete",
+                {"path": str(path), "stats": result.get("stats", {})},
+                output_file,
+            )
+
+        else:  # summary
+            # Human-readable summary
+            stats = result.get("stats", {})
+            summary = f"""
+Code Analysis Summary
+=====================
+Path: {path}
+Files processed: {stats.get("files_processed", 0)}
+Total nodes: {stats.get("total_nodes", 0)}
+Classes: {stats.get("classes", 0)}
+Functions: {stats.get("functions", 0)}
+Imports: {stats.get("imports", 0)}
+Languages: {", ".join(stats.get("languages", []))}
+Average complexity: {stats.get("avg_complexity", 0):.2f}
+Duration: {stats.get("duration", 0):.2f}s
+"""
+            if output_file:
+                output_file.write(summary)
+            else:
+                print(summary)
+
+    except KeyboardInterrupt:
+        emit_json_event(
+            "code:analysis:cancelled",
+            {"message": "Analysis cancelled by user"},
+            output_file,
+        )
+        sys.exit(130)
+
+    except Exception as e:
+        emit_json_event("code:analysis:error", {"message": str(e)}, output_file)
+        sys.exit(1)
+
+    finally:
+        if output_file:
+            output_file.close()
+
+
+if __name__ == "__main__":
+    main()

claude_mpm/tools/code_tree_analyzer/__init__.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""
+Code Tree Analyzer
+==================
+
+Analyzes source code using AST to extract structure and metrics,
+supporting multiple languages and emitting incremental events for visualization.
+
+This module has been refactored from a single 1,825-line file into focused,
+maintainable components while preserving complete backward compatibility.
+
+Public API:
+-----------
+- CodeTreeAnalyzer: Main analyzer class
+- CodeNode: Data structure for code nodes
+- GitignoreManager: Gitignore pattern matching
+- PythonAnalyzer: Python AST analysis
+- MultiLanguageAnalyzer: Multi-language support
+
+Example Usage:
+--------------
+    from claude_mpm.tools.code_tree_analyzer import CodeTreeAnalyzer
+
+    analyzer = CodeTreeAnalyzer(emit_events=True)
+    result = analyzer.analyze_directory(Path("/path/to/code"))
+    print(result['stats'])
+"""
+
+# Public API - Backward compatible imports
+from .core import CodeTreeAnalyzer
+from .gitignore import GitignoreManager
+from .models import CodeNode
+from .multilang_analyzer import MultiLanguageAnalyzer
+from .python_analyzer import PythonAnalyzer
+
+__all__ = [
+    "CodeNode",
+    "CodeTreeAnalyzer",
+    "GitignoreManager",
+    "MultiLanguageAnalyzer",
+    "PythonAnalyzer",
+]
+
+# Version info
+__version__ = "2.0.0"  # Major refactoring while maintaining API compatibility