gobby 0.2.5__py3-none-any.whl

gobby/tasks/tdd.py

@@ -0,0 +1,352 @@
+"""
+TDD sandwich pattern utilities for task expansion.
+
+This module provides shared logic for applying the TDD (Test-Driven Development)
+sandwich pattern to task expansions. The sandwich wraps implementation tasks:
+- ONE [TDD] task at the start (RED phase - write failing tests)
+- Original tasks renamed with [IMPL] prefix (GREEN phase - make tests pass)
+- ONE [REF] task at the end (BLUE phase - refactor while keeping tests green)
+
+Used by both MCP expand_task tool and CLI expand command.
+"""
+
+import logging
+import re
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gobby.storage.task_dependencies import TaskDependencyManager
+    from gobby.storage.tasks import LocalTaskManager
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "TDD_PREFIXES",
+    "TDD_SKIP_PATTERNS",
+    "TDD_CRITERIA_RED",
+    "TDD_CRITERIA_BLUE",
+    "TDD_PARENT_CRITERIA",
+    "TDD_CATEGORIES",
+    "should_skip_tdd",
+    "should_skip_expansion",
+    "apply_tdd_sandwich",
+    "build_expansion_context",
+]
+
+# TDD triplet prefixes - used for both skip detection and triplet creation
+TDD_PREFIXES = ("[TDD]", "[IMPL]", "[REF]")
+
+# Task categories that should get TDD treatment
+TDD_CATEGORIES = ("code", "config")
+
+# Patterns for tasks that should skip TDD transformation (case-insensitive)
+TDD_SKIP_PATTERNS = (
+    # New TDD prefixes (already in triplet form)
+    r"^\[TDD\]",
+    r"^\[IMPL\]",
+    r"^\[REF\]",
+    # Legacy TDD prefixes (backwards compatibility)
+    r"^Write tests for:",
+    r"^Implement:",
+    r"^Refactor:",
+    # Deletion tasks (simple operations, no tests needed)
+    r"^Delete\b",
+    r"^Remove\b",
+    # Documentation updates
+    r"^Update.*README",
+    r"^Update.*documentation",
+    r"^Update.*docs\b",
+    # Config file updates
+    r"^Update.*\.toml\b",
+    r"^Update.*\.yaml\b",
+    r"^Update.*\.yml\b",
+    r"^Update.*\.json\b",
+    r"^Update.*\.env\b",
+    r"^Update.*config",
+)
+
+# TDD validation criteria templates per phase
+TDD_CRITERIA_RED = """## Deliverable
+- [ ] Tests written that define expected behavior
+- [ ] Tests fail when run (no implementation yet)
+- [ ] Test coverage addresses acceptance criteria from parent task
+"""
+
+TDD_CRITERIA_BLUE = """## Deliverable
+- [ ] All tests continue to pass
+- [ ] Code refactored for clarity and maintainability
+- [ ] No new functionality added (refactor only)
+- [ ] Unrelated bugs discovered during refactor logged as new bug tasks
+
+**Note:** If you discover bugs outside your scope during refactoring, create bug tasks
+for them rather than fixing them now.
+"""
+
+TDD_PARENT_CRITERIA = """## Deliverable
+- [ ] All child tasks completed
+"""
+
+
+def should_skip_tdd(title: str) -> bool:
+    """
+    Check if a task should skip TDD transformation based on its title.
+
+    Tasks are skipped if they match any TDD_SKIP_PATTERNS:
+    - Already TDD triplet tasks ([TDD], [IMPL], [REF] prefixes)
+    - Legacy TDD prefixes (Write tests for:, Implement:, Refactor:)
+    - Deletion tasks (Delete X, Remove Y)
+    - Documentation updates (Update README, Update docs)
+    - Config file updates (Update pyproject.toml, Update .env)
+
+    Args:
+        title: The task title to check
+
+    Returns:
+        True if the task should skip TDD transformation, False otherwise
+    """
+    for pattern in TDD_SKIP_PATTERNS:
+        if re.search(pattern, title, re.IGNORECASE):
+            return True
+    return False
+
+
+def should_skip_expansion(title: str, is_expanded: bool, force: bool = False) -> tuple[bool, str]:
+    """
+    Check if a task should be skipped from expansion.
+
+    Tasks are skipped if:
+    - Already expanded (is_expanded=True) unless force=True
+    - Title starts with TDD prefixes ([TDD], [IMPL], [REF]) - these are atomic tasks
+
+    Args:
+        title: The task title to check
+        is_expanded: Whether the task's is_expanded flag is set
+        force: Whether to force expansion even if already expanded
+
+    Returns:
+        Tuple of (should_skip: bool, reason: str)
+        reason is empty string if should_skip is False
+    """
+    # Check for TDD prefixes - these tasks should never be expanded
+    for prefix in TDD_PREFIXES:
+        if title.startswith(prefix):
+            return True, f"TDD task ({prefix})"
+
+    # Check if already expanded
+    if is_expanded and not force:
+        return True, "already expanded"
+
+    return False, ""
+
+
+async def apply_tdd_sandwich(
+    task_manager: "LocalTaskManager",
+    dep_manager: "TaskDependencyManager",
+    parent_task_id: str,
+    impl_task_ids: list[str],
+    refactor_task_ids: list[str] | None = None,
+) -> dict[str, Any]:
+    """Apply TDD sandwich pattern to a parent task's children.
+
+    Creates a "sandwich" structure where implementation tasks are wrapped:
+    - ONE [TDD] task at the start (RED phase - write failing tests for all impls)
+    - Original child tasks renamed with [IMPL] prefix (GREEN phase)
+    - Intermediate [REF] tasks (refactor-category subtasks) depend on all [IMPL]s
+    - ONE final [REF] task at the end (BLUE phase - refactor everything)
+
+    Dependencies are wired:
+    - All [IMPL] tasks are blocked by the [TDD] task
+    - Intermediate [REF] tasks are blocked by all [IMPL] tasks
+    - Final [REF] task is blocked by [TDD], all [IMPL]s, and intermediate [REF]s
+
+    Args:
+        task_manager: LocalTaskManager instance for task CRUD
+        dep_manager: TaskDependencyManager instance for dependency wiring
+        parent_task_id: The parent task ID being expanded
+        impl_task_ids: List of implementation task IDs (the original children)
+        refactor_task_ids: List of refactor-category task IDs (optional)
+
+    Returns:
+        Dict with:
+        - success: True if sandwich was applied
+        - tasks_created: Number of tasks created (2: TDD + REF)
+        - test_task_id: ID of the created TDD task
+        - refactor_task_id: ID of the created REF task
+        - impl_task_count: Number of impl tasks wrapped
+        - intermediate_refactor_count: Number of intermediate refactor tasks processed
+        Or error info if failed
+    """
+    parent = task_manager.get_task(parent_task_id)
+    if not parent:
+        return {"success": False, "error": f"Parent task not found: {parent_task_id}"}
+
+    if not impl_task_ids:
+        return {"success": False, "error": "No implementation tasks to wrap"}
+
+    # Skip if already TDD-applied
+    if parent.is_tdd_applied:
+        return {"success": False, "skipped": True, "reason": "already_applied"}
+
+    try:
+        # Build list of impl task titles for TDD task context
+        impl_titles = []
+        for impl_id in impl_task_ids:
+            impl_task = task_manager.get_task(impl_id)
+            if impl_task:
+                impl_titles.append(f"- {impl_task.title}")
+        impl_list = "\n".join(impl_titles) if impl_titles else "- (implementation tasks)"
+
+        # 1. Create ONE Test Task (Red phase) - tests for all implementations
+        test_task = task_manager.create_task(
+            title=f"[TDD] Write failing tests for {parent.title}",
+            description=(
+                f"Write failing tests for: {parent.title}\n\n"
+                "## Implementation tasks to cover:\n"
+                f"{impl_list}\n\n"
+                "RED phase of TDD - define expected behavior before implementation."
+            ),
+            project_id=parent.project_id,
+            parent_task_id=parent.id,
+            task_type="task",
+            priority=parent.priority,
+            validation_criteria=TDD_CRITERIA_RED,
+            category="test",
+        )
+
+        # 2. Add [IMPL] prefix to all implementation tasks and wire dependencies
+        for impl_id in impl_task_ids:
+            impl_task = task_manager.get_task(impl_id)
+            if impl_task and not impl_task.title.startswith("[IMPL]"):
+                task_manager.update_task(impl_id, title=f"[IMPL] {impl_task.title}")
+            try:
+                dep_manager.add_dependency(impl_id, test_task.id, "blocks")
+            except ValueError:
+                pass  # Dependency already exists
+
+        # 3. Add [REF] prefix to intermediate refactor tasks and wire dependencies
+        # These are refactor-category subtasks from the expansion (not the final [REF])
+        intermediate_refactor_ids: list[str] = []
+        for ref_id in refactor_task_ids or []:
+            ref_task = task_manager.get_task(ref_id)
+            if ref_task and not ref_task.title.startswith("[REF]"):
+                task_manager.update_task(ref_id, title=f"[REF] {ref_task.title}")
+            intermediate_refactor_ids.append(ref_id)
+            # Each intermediate [REF] depends on all [IMPL] tasks
+            for impl_id in impl_task_ids:
+                try:
+                    dep_manager.add_dependency(ref_id, impl_id, "blocks")
+                except ValueError:
+                    pass  # Dependency already exists
+
+        # 5. Create ONE final Refactor Task (Blue phase) - refactor after all impls done
+        refactor_task = task_manager.create_task(
+            title=f"[REF] Refactor and verify {parent.title}",
+            description=(
+                f"Refactor implementations in: {parent.title}\n\n"
+                "BLUE phase of TDD - clean up while keeping tests green."
+            ),
+            project_id=parent.project_id,
+            parent_task_id=parent.id,
+            task_type="task",
+            priority=parent.priority,
+            validation_criteria=TDD_CRITERIA_BLUE,
+            category="code",
+        )
+
+        # 6. Wire final refactor to be blocked by TDD, all impls, and intermediate refs
+        # REFACTOR depends on TDD (must complete testing before refactoring)
+        try:
+            dep_manager.add_dependency(refactor_task.id, test_task.id, "blocks")
+        except ValueError:
+            pass  # Dependency already exists
+
+        # REFACTOR depends on all impl tasks
+        for impl_id in impl_task_ids:
+            try:
+                dep_manager.add_dependency(refactor_task.id, impl_id, "blocks")
+            except ValueError:
+                pass  # Dependency already exists
+
+        # REFACTOR depends on all intermediate refactor tasks (if any)
+        for ref_id in intermediate_refactor_ids:
+            try:
+                dep_manager.add_dependency(refactor_task.id, ref_id, "blocks")
+            except ValueError:
+                pass  # Dependency already exists
+
+        # Mark parent as TDD-applied
+        task_manager.update_task(
+            parent.id,
+            is_tdd_applied=True,
+            validation_criteria=TDD_PARENT_CRITERIA,
+        )
+
+        return {
+            "success": True,
+            "tasks_created": 2,  # TDD + final REF (impl tasks already existed)
+            "test_task_id": test_task.id,
+            "refactor_task_id": refactor_task.id,
+            "impl_task_count": len(impl_task_ids),
+            "intermediate_refactor_count": len(intermediate_refactor_ids),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}
+
+
+def build_expansion_context(
+    expansion_context_json: str | None,
+    user_context: str | None,
+) -> str | None:
+    """
+    Build context for expansion by merging stored data with user context.
+
+    If the task has expansion_context (legacy enrichment data), parse it and
+    include research findings, validation criteria, and complexity info.
+
+    Args:
+        expansion_context_json: JSON string from task.expansion_context (may be None)
+        user_context: User-provided context string (may be None)
+
+    Returns:
+        Merged context string, or None if no context available
+    """
+    import json
+
+    enrichment_parts: list[str] = []
+
+    # Parse stored expansion_context (legacy enrichment data)
+    if expansion_context_json:
+        try:
+            enrichment_data = json.loads(expansion_context_json)
+
+            # Include research findings
+            if research := enrichment_data.get("research_findings"):
+                enrichment_parts.append(f"## Research Findings\n{research}")
+
+            # Include validation criteria
+            if validation := enrichment_data.get("validation_criteria"):
+                enrichment_parts.append(f"## Validation Criteria\n{validation}")
+
+            # Include complexity info
+            complexity_level = enrichment_data.get("complexity_level")
+            subtask_count = enrichment_data.get("suggested_subtask_count")
+            if complexity_level or subtask_count:
+                complexity_info = []
+                if complexity_level:
+                    complexity_info.append(f"Complexity level: {complexity_level}")
+                if subtask_count:
+                    complexity_info.append(f"Suggested subtask count: {subtask_count}")
+                enrichment_parts.append("## Complexity Analysis\n" + "\n".join(complexity_info))
+
+        except (json.JSONDecodeError, TypeError):
+            # Legacy or plain text context - preserve it as raw text
+            enrichment_parts.append(f"## Legacy Expansion Context\n{expansion_context_json}")
+
+    # Add user-provided context
+    if user_context:
+        enrichment_parts.append(f"## Additional Context\n{user_context}")
+
+    # Return merged context or None
+    if enrichment_parts:
+        return "\n\n".join(enrichment_parts)
+    return None

gobby/tasks/tree_builder.py

@@ -0,0 +1,263 @@
+"""
+Task tree builder module.
+
+Creates task hierarchies from JSON tree structures. Simpler alternative
+to TaskHierarchyBuilder which parses markdown.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from gobby.storage.tasks import LocalTaskManager
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TreeBuildResult:
+    """Result of building a task tree."""
+
+    tasks_created: int
+    epic_ref: str | None  # Short ref for the root task (e.g., "#42")
+    task_refs: list[str]  # All created task refs
+    errors: list[str]  # Any errors encountered
+
+
+class TaskTreeBuilder:
+    """Builds task trees from JSON structures.
+
+    Creates tasks with parent-child relationships and wires dependencies
+    between siblings based on `depends_on` references.
+
+    Example tree:
+        {
+            "title": "Epic Title",
+            "task_type": "epic",
+            "children": [
+                {
+                    "title": "Phase 1",
+                    "children": [
+                        {"title": "Task A", "category": "code"},
+                        {"title": "Task B", "category": "code", "depends_on": ["Task A"]}
+                    ]
+                }
+            ]
+        }
+    """
+
+    def __init__(
+        self,
+        task_manager: LocalTaskManager,
+        project_id: str,
+        session_id: str | None = None,
+    ) -> None:
+        """Initialize the builder.
+
+        Args:
+            task_manager: LocalTaskManager instance for creating tasks
+            project_id: Project ID for created tasks
+            session_id: Optional session ID for tracking
+        """
+        self.task_manager = task_manager
+        self.project_id = project_id
+        self.session_id = session_id
+        self._title_to_id: dict[str, str] = {}  # Map title -> task_id for dependency resolution
+        self._sibling_index_map: dict[
+            str | None, dict[int, str]
+        ] = {}  # parent_id -> {sibling_index -> task_id}
+        self._created_tasks: list[str] = []
+        self._errors: list[str] = []
+
+    def build(self, tree: dict[str, Any]) -> TreeBuildResult:
+        """Build task tree from JSON structure.
+
+        Args:
+            tree: JSON tree with title, task_type, children, etc.
+
+        Returns:
+            TreeBuildResult with created task refs
+        """
+        self._title_to_id = {}
+        self._sibling_index_map = {}
+        self._created_tasks = []
+        self._errors = []
+
+        # Create the root task
+        root_id = self._create_node(tree, parent_task_id=None, sibling_index=0)
+
+        # Wire dependencies after all tasks are created
+        self._wire_dependencies(tree)
+
+        # Get short refs for all created tasks
+        task_refs = []
+        epic_ref = None
+        for task_id in self._created_tasks:
+            task = self.task_manager.get_task(task_id)
+            if task and task.seq_num:
+                ref = f"#{task.seq_num}"
+                task_refs.append(ref)
+                if task_id == root_id:
+                    epic_ref = ref
+
+        return TreeBuildResult(
+            tasks_created=len(self._created_tasks),
+            epic_ref=epic_ref,
+            task_refs=task_refs,
+            errors=self._errors,
+        )
+
+    def get_id_for_title(self, title: str) -> str | None:
+        """Get the task ID for a given title.
+
+        Args:
+            title: The task title to look up
+
+        Returns:
+            The task ID if found, None otherwise
+        """
+        return self._title_to_id.get(title)
+
+    def _create_node(
+        self,
+        node: dict[str, Any],
+        parent_task_id: str | None,
+        sibling_index: int = 0,
+    ) -> str | None:
+        """Create a task node and its children recursively.
+
+        Args:
+            node: Task node dict with title, children, etc.
+            parent_task_id: ID of parent task (None for root)
+            sibling_index: Index of this node among its siblings (for numeric dependency refs)
+
+        Returns:
+            Created task ID, or None if creation failed
+        """
+        title = node.get("title")
+        if not title:
+            self._errors.append("Node missing required 'title' field")
+            return None
+
+        # Extract task fields
+        task_type = node.get("task_type", "task")
+        description = node.get("description")
+        priority = node.get("priority", 2)
+        category = node.get("category")
+        labels = node.get("labels", [])
+        validation_criteria = node.get("validation_criteria")
+        requires_user_review = node.get("requires_user_review", False)
+
+        try:
+            # Create the task
+            task = self.task_manager.create_task(
+                title=title,
+                project_id=self.project_id,
+                task_type=task_type,
+                parent_task_id=parent_task_id,
+                description=description,
+                priority=priority,
+                category=category,
+                labels=labels,
+                validation_criteria=validation_criteria,
+                requires_user_review=requires_user_review,
+                created_in_session_id=self.session_id,
+            )
+
+            self._created_tasks.append(task.id)
+
+            # Check for duplicate titles (warn but continue for partial functionality)
+            if title in self._title_to_id:
+                existing_id = self._title_to_id[title]
+                self._errors.append(
+                    f"Duplicate task title '{title}': conflicts with existing task {existing_id}"
+                )
+            self._title_to_id[title] = task.id
+
+            # Track sibling index for numeric dependency references
+            if parent_task_id not in self._sibling_index_map:
+                self._sibling_index_map[parent_task_id] = {}
+            self._sibling_index_map[parent_task_id][sibling_index] = task.id
+
+            logger.debug(f"Created task {task.id} (#{task.seq_num}): {title}")
+
+            # Create children with their sibling indices
+            children = node.get("children", [])
+            for i, child in enumerate(children):
+                self._create_node(child, parent_task_id=task.id, sibling_index=i)
+
+            return task.id
+
+        except Exception as e:
+            self._errors.append(f"Failed to create task '{title}': {e}")
+            return None
+
+    def _wire_dependencies(self, tree: dict[str, Any]) -> None:
+        """Wire dependencies after all tasks are created.
+
+        Resolves `depends_on` references to task IDs. Supports:
+        - Title strings: `"depends_on": ["Task A"]` → lookup in _title_to_id
+        - Numeric indices: `"depends_on": [0]` → lookup sibling by index
+
+        Args:
+            tree: The original tree structure
+        """
+        from gobby.storage.task_dependencies import TaskDependencyManager
+
+        dep_manager = TaskDependencyManager(self.task_manager.db)
+
+        def process_node(node: dict[str, Any], parent_task_id: str | None) -> None:
+            title = node.get("title")
+            depends_on = node.get("depends_on", [])
+
+            if title and depends_on and title in self._title_to_id:
+                task_id = self._title_to_id[title]
+
+                for dep in depends_on:
+                    blocker_id: str | None = None
+                    dep_display: str = str(dep)  # For error messages
+
+                    if isinstance(dep, int):
+                        # Numeric index - look up sibling by index
+                        sibling_map = self._sibling_index_map.get(parent_task_id, {})
+                        blocker_id = sibling_map.get(dep)
+                        if blocker_id is None:
+                            self._errors.append(f"Sibling index {dep} not found for task '{title}'")
+                            continue
+                    elif isinstance(dep, str):
+                        # Title string - look up by title
+                        blocker_id = self._title_to_id.get(dep)
+                        if blocker_id is None:
+                            self._errors.append(f"Dependency not found: '{dep}' for task '{title}'")
+                            continue
+                    else:
+                        self._errors.append(
+                            f"Invalid dependency type {type(dep).__name__} for task '{title}'"
+                        )
+                        continue
+
+                    try:
+                        dep_manager.add_dependency(
+                            task_id=task_id,
+                            depends_on=blocker_id,
+                            dep_type="blocks",
+                        )
+                        logger.debug(f"Added dependency: {title} depends on {dep_display}")
+                    except ValueError as e:
+                        # Ignore duplicate dependency errors
+                        if "already exists" not in str(e):
+                            self._errors.append(
+                                f"Failed to add dependency {title} -> {dep_display}: {e}"
+                            )
+
+            # Get this node's task_id to pass as parent for children
+            node_task_id = self._title_to_id.get(title) if title else None
+
+            # Process children
+            for child in node.get("children", []):
+                process_node(child, parent_task_id=node_task_id)
+
+        process_node(tree, parent_task_id=None)