solokit 0.1.1__py3-none-any.whl

solokit/session/briefing/git_context.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+Git context and status checking.
+Part of the briefing module decomposition.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+from solokit.core.command_runner import CommandRunner
+from solokit.core.constants import GIT_QUICK_TIMEOUT
+from solokit.core.error_handlers import log_errors
+from solokit.core.exceptions import ErrorCode, GitError, SystemError
+from solokit.core.logging_config import get_logger
+from solokit.core.output import get_output
+from solokit.core.types import GitStatus, WorkItemStatus
+
+logger = get_logger(__name__)
+output = get_output()
+
+
+class GitContext:
+    """Handle git status and branch information."""
+
+    def __init__(self) -> None:
+        """Initialize git context handler."""
+        self.runner = CommandRunner(default_timeout=GIT_QUICK_TIMEOUT)
+
+    @log_errors()
+    def check_git_status(self) -> dict[str, Any]:
+        """Check git status for session start.
+
+        Returns:
+            Dict with keys: clean (bool), status (str), branch (str or None)
+
+        Raises:
+            GitError: If git command fails
+            NotAGitRepoError: If not in a git repository
+            SystemError: If git workflow import or execution fails
+        """
+        try:
+            # Import git workflow from new location
+            from solokit.git.integration import GitWorkflow
+
+            workflow = GitWorkflow()
+            is_clean: bool
+            status_msg: str
+            is_clean, status_msg = workflow.check_git_status()  # type: ignore[misc]
+            current_branch = workflow.get_current_branch()
+
+            return {"clean": is_clean, "status": status_msg, "branch": current_branch}
+        except ImportError as e:
+            raise SystemError(
+                message="Failed to import GitWorkflow",
+                code=ErrorCode.IMPORT_FAILED,
+                context={"module": "solokit.git.integration", "error": str(e)},
+                remediation="Ensure git integration module is properly installed",
+                cause=e,
+            ) from e
+        except GitError:
+            # Re-raise GitError as-is (already standardized)
+            raise
+        except Exception as e:
+            # Wrap unexpected errors
+            raise GitError(
+                message=f"Failed to check git status: {e}",
+                code=ErrorCode.GIT_COMMAND_FAILED,
+                context={"error": str(e)},
+                remediation="Check git installation and repository state",
+                cause=e,
+            ) from e
+
+    @log_errors()
+    def determine_git_branch_final_status(self, branch_name: str, git_info: dict) -> str:
+        """Determine the final status of a git branch by inspecting actual git state.
+
+        Args:
+            branch_name: Name of the git branch
+            git_info: Git info dict from work item
+
+        Returns:
+            One of: "merged", "pr_created", "pr_closed", "ready_for_pr", "deleted"
+
+        Raises:
+            GitError: If git commands fail critically
+            SystemError: If JSON parsing or other operations fail
+        """
+        parent_branch = git_info.get("parent_branch", "main")
+
+        try:
+            # Check 1: Is branch merged?
+            result = self.runner.run(["git", "branch", "--merged", parent_branch])
+            if result.success and branch_name in result.stdout:
+                logger.debug(f"Branch {branch_name} is merged to {parent_branch}")
+                return GitStatus.MERGED.value
+
+            # Check 2: Does PR exist? (requires gh CLI)
+            result = self.runner.run(
+                [
+                    "gh",
+                    "pr",
+                    "list",
+                    "--head",
+                    branch_name,
+                    "--state",
+                    "all",
+                    "--json",
+                    "number,state",
+                ]
+            )
+            if result.success and result.stdout.strip():
+                try:
+                    prs = json.loads(result.stdout)
+                    if prs:
+                        pr = prs[0]  # Get first/most recent PR
+                        pr_state = pr.get("state", "").upper()
+
+                        if pr_state == "MERGED":
+                            logger.debug(f"Branch {branch_name} has merged PR")
+                            return GitStatus.MERGED.value
+                        elif pr_state == "CLOSED":
+                            logger.debug(f"Branch {branch_name} has closed (unmerged) PR")
+                            return GitStatus.PR_CLOSED.value
+                        elif pr_state == "OPEN":
+                            logger.debug(f"Branch {branch_name} has open PR")
+                            return GitStatus.PR_CREATED.value
+                except json.JSONDecodeError as e:
+                    # Log but don't fail - gh CLI output may be malformed
+                    logger.debug(f"Error parsing PR JSON: {e}")
+                    # Continue to check branch existence
+            else:
+                logger.debug("gh CLI not available or no PRs found")
+
+            # Check 3: Does branch still exist locally?
+            result = self.runner.run(["git", "show-ref", "--verify", f"refs/heads/{branch_name}"])
+            if result.success:
+                logger.debug(f"Branch {branch_name} exists locally")
+                # Branch exists locally, no PR found
+                return GitStatus.READY_FOR_PR.value
+
+            # Check 4: Does branch exist remotely?
+            result = self.runner.run(["git", "ls-remote", "--heads", "origin", branch_name])
+            if result.success and result.stdout.strip():
+                logger.debug(f"Branch {branch_name} exists remotely")
+                # Branch exists remotely, no PR found
+                return GitStatus.READY_FOR_PR.value
+
+            # Branch doesn't exist and no PR found
+            logger.debug(f"Branch {branch_name} not found locally or remotely")
+            return GitStatus.DELETED.value
+
+        except GitError:
+            # Re-raise GitError from CommandRunner
+            raise
+        except Exception as e:
+            # Wrap unexpected errors
+            raise GitError(
+                message=f"Failed to determine git branch status for '{branch_name}': {e}",
+                code=ErrorCode.GIT_COMMAND_FAILED,
+                context={
+                    "branch_name": branch_name,
+                    "parent_branch": parent_branch,
+                    "error": str(e),
+                },
+                remediation="Check git installation and repository state",
+                cause=e,
+            ) from e
+
+    @log_errors()
+    def finalize_previous_work_item_git_status(
+        self, work_items_data: dict, current_work_item_id: str
+    ) -> Optional[str]:
+        """Finalize git status for previous completed work item when starting a new one.
+
+        This handles the case where:
+        - Previous work item was completed
+        - User performed git operations externally (pushed, created PR, merged)
+        - Starting a new work item (not resuming the previous one)
+
+        Args:
+            work_items_data: Loaded work items data
+            current_work_item_id: ID of work item being started
+
+        Returns:
+            Previous work item ID if finalized, None otherwise
+
+        Raises:
+            GitError: If git operations fail
+            SystemError: If file operations fail
+        """
+        work_items = work_items_data.get("work_items", {})
+
+        # Find previously active work item
+        previous_work_item = None
+        previous_work_item_id = None
+
+        for wid, wi in work_items.items():
+            # Skip current work item
+            if wid == current_work_item_id:
+                continue
+
+            # Find work item with git branch in "in_progress" status
+            git_info = wi.get("git", {})
+            if git_info.get("status") == GitStatus.IN_PROGRESS.value:
+                # Only finalize if work item itself is completed
+                if wi.get("status") == WorkItemStatus.COMPLETED.value:
+                    previous_work_item = wi
+                    previous_work_item_id = wid
+                    break
+
+        if not previous_work_item:
+            # No previous work item to finalize
+            logger.debug("No previous work item with stale git status found")
+            return None
+
+        git_info = previous_work_item.get("git", {})
+        branch_name = git_info.get("branch")
+
+        if not branch_name:
+            logger.debug(f"Previous work item {previous_work_item_id} has no git branch")
+            return None
+
+        logger.info(f"Finalizing git status for completed work item: {previous_work_item_id}")
+
+        try:
+            # Inspect actual git state
+            final_status = self.determine_git_branch_final_status(branch_name, git_info)
+
+            # Update git status
+            work_items[previous_work_item_id]["git"]["status"] = final_status
+
+            # Save updated work items
+            work_items_file = Path(".session/tracking/work_items.json")
+            try:
+                with open(work_items_file, "w") as f:
+                    json.dump(work_items_data, f, indent=2)
+            except OSError as e:
+                raise SystemError(
+                    message=f"Failed to save work items file: {work_items_file}",
+                    code=ErrorCode.FILE_OPERATION_FAILED,
+                    context={
+                        "file_path": str(work_items_file),
+                        "work_item_id": previous_work_item_id,
+                        "error": str(e),
+                    },
+                    remediation="Check file permissions and disk space",
+                    cause=e,
+                ) from e
+
+            logger.info(
+                "Updated git status for %s: in_progress → %s",
+                previous_work_item_id,
+                final_status,
+            )
+            output.success(
+                f"Finalized git status for previous work item: "
+                f"{previous_work_item_id} → {final_status}"
+            )
+
+            return previous_work_item_id
+
+        except GitError:
+            # Re-raise GitError from determine_git_branch_final_status
+            raise
+        except SystemError:
+            # Re-raise SystemError from file operations
+            raise
+        except Exception as e:
+            # Wrap unexpected errors
+            raise SystemError(
+                message=f"Failed to finalize git status for work item '{previous_work_item_id}': {e}",
+                code=ErrorCode.FILE_OPERATION_FAILED,
+                context={
+                    "work_item_id": previous_work_item_id,
+                    "current_work_item_id": current_work_item_id,
+                    "branch_name": branch_name,
+                    "error": str(e),
+                },
+                remediation="Check work items data integrity and git repository state",
+                cause=e,
+            ) from e

solokit/session/briefing/learning_loader.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Learning loading and relevance scoring.
+Part of the briefing module decomposition.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from solokit.core.constants import MAX_SPEC_KEYWORDS
+from solokit.core.exceptions import FileOperationError
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+class LearningLoader:
+    """Load and score learnings based on relevance."""
+
+    def __init__(self, session_dir: Path | None = None):
+        """Initialize learning loader.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.learnings_file = self.session_dir / "tracking" / "learnings.json"
+
+    def load_learnings(self) -> dict[str, Any]:
+        """Load learnings from tracking file.
+
+        Returns:
+            Learnings data structure
+
+        Raises:
+            FileOperationError: If file read or JSON parsing fails
+        """
+        if not self.learnings_file.exists():
+            return {"learnings": []}
+
+        try:
+            with open(self.learnings_file) as f:
+                return json.load(f)  # type: ignore[no-any-return]
+        except json.JSONDecodeError as e:
+            raise FileOperationError(
+                operation="parse",
+                file_path=str(self.learnings_file),
+                details=f"Invalid JSON format: {e.msg} at line {e.lineno}, column {e.colno}",
+                cause=e,
+            )
+        except OSError as e:
+            raise FileOperationError(
+                operation="read",
+                file_path=str(self.learnings_file),
+                details=str(e),
+                cause=e,
+            )
+
+    def get_relevant_learnings(
+        self, learnings_data: dict, work_item: dict, spec_content: str = ""
+    ) -> list[dict]:
+        """Get learnings relevant to this work item using multi-factor scoring.
+
+        Enhancement #11 Phase 4: Uses intelligent scoring algorithm instead of
+        simple tag matching. Considers keyword matching, type-based relevance,
+        recency weighting, and category bonuses.
+
+        Args:
+            learnings_data: Full learnings.json data structure
+            work_item: Work item dictionary with title, type, tags
+            spec_content: Optional spec content for keyword extraction
+
+        Returns:
+            Top 10 scored learnings
+        """
+        # Flatten all learnings from categories structure
+        all_learnings = []
+        categories = learnings_data.get("categories", {})
+
+        # Handle both old format (learnings list) and new format (categories dict)
+        if not categories and "learnings" in learnings_data:
+            # Old format compatibility
+            all_learnings = learnings_data.get("learnings", [])
+            for learning in all_learnings:
+                if "category" not in learning:
+                    learning["category"] = "general"
+        else:
+            # New format with categories
+            for category, learnings in categories.items():
+                for learning in learnings:
+                    learning_copy = learning.copy()
+                    learning_copy["category"] = category
+                    all_learnings.append(learning_copy)
+
+        if not all_learnings:
+            return []
+
+        # Extract keywords from work item
+        title_keywords = self._extract_keywords(work_item.get("title", ""))
+        spec_keywords = self._extract_keywords(spec_content[:MAX_SPEC_KEYWORDS])
+        work_type = work_item.get("type", "")
+        work_tags = set(work_item.get("tags", []))
+
+        scored = []
+        for learning in all_learnings:
+            score: float = 0
+            content_lower = learning.get("content", "").lower()
+            context_lower = learning.get("context", "").lower()
+            learning_tags = set(learning.get("tags", []))
+            category = learning.get("category", "general")
+
+            # 1. Keyword matching (title and spec)
+            content_keywords = self._extract_keywords(content_lower)
+            title_matches = len(title_keywords & content_keywords)
+            spec_matches = len(spec_keywords & content_keywords)
+            score += title_matches * 3  # Title match is worth more
+            score += spec_matches * 1.5
+
+            # 2. Type-based matching
+            if work_type in content_lower or work_type in context_lower:
+                score += 5
+
+            # 3. Tag matching (legacy support)
+            tag_overlap = len(work_tags & learning_tags)
+            score += tag_overlap * 2
+
+            # 4. Category bonuses
+            category_bonuses = {
+                "best_practices": 3,
+                "patterns": 2,
+                "gotchas": 2,
+                "architecture": 2,
+            }
+            score += category_bonuses.get(category, 0)
+
+            # 5. Recency weighting (decay over time)
+            created_at = learning.get("created_at", "")
+            if created_at:
+                days_ago = self._calculate_days_ago(created_at)
+                if days_ago < 7:
+                    score += 3  # Very recent
+                elif days_ago < 30:
+                    score += 2  # Recent
+                elif days_ago < 90:
+                    score += 1  # Moderately recent
+
+            # Only include if score > 0
+            if score > 0:
+                scored.append((score, learning))
+
+        # Sort by score (descending) and return top 10
+        scored.sort(key=lambda x: x[0], reverse=True)
+        return [learning for score, learning in scored[:10]]
+
+    def _extract_keywords(self, text: str) -> set[str]:
+        """Extract meaningful keywords from text (lowercase, >3 chars).
+
+        Args:
+            text: Text to extract keywords from
+
+        Returns:
+            Set of lowercase keywords longer than 3 characters
+        """
+        words = re.findall(r"\b\w+\b", text.lower())
+        # Filter stop words and short words
+        stop_words = {
+            "the",
+            "this",
+            "that",
+            "with",
+            "from",
+            "have",
+            "will",
+            "for",
+            "and",
+            "or",
+            "not",
+            "but",
+            "was",
+            "are",
+            "been",
+        }
+        return {w for w in words if len(w) > 3 and w not in stop_words}
+
+    def _calculate_days_ago(self, timestamp: str) -> int:
+        """Calculate days since timestamp.
+
+        Args:
+            timestamp: ISO format timestamp string
+
+        Returns:
+            Number of days ago (defaults to 365 if parsing fails)
+
+        Note:
+            Returns 365 (considered "old") if timestamp is empty or invalid.
+            This is intentional to avoid breaking the scoring algorithm.
+        """
+        if not timestamp:
+            return 365  # Empty timestamp considered old
+
+        try:
+            ts = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            delta = datetime.now() - ts
+            return delta.days
+        except (ValueError, TypeError) as e:
+            logger.debug(f"Failed to parse timestamp '{timestamp}': {e}. Treating as old learning.")
+            return 365  # Default to old if parsing fails

solokit/session/briefing/milestone_builder.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""
+Milestone context building.
+Part of the briefing module decomposition.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from solokit.core.logging_config import get_logger
+from solokit.core.types import WorkItemStatus
+
+logger = get_logger(__name__)
+
+
+class MilestoneBuilder:
+    """Build milestone context for briefings."""
+
+    def __init__(self, session_dir: Path | None = None):
+        """Initialize milestone builder.
+
+        Args:
+            session_dir: Path to .session directory (defaults to .session)
+        """
+        self.session_dir = session_dir or Path(".session")
+        self.work_items_file = self.session_dir / "tracking" / "work_items.json"
+
+    def load_milestone_context(self, work_item: dict) -> dict | None:
+        """Load milestone context for briefing.
+
+        Args:
+            work_item: Work item dictionary
+
+        Returns:
+            Milestone context dict or None if not in a milestone
+        """
+        milestone_name = work_item.get("milestone")
+        if not milestone_name:
+            return None
+
+        if not self.work_items_file.exists():
+            return None
+
+        with open(self.work_items_file) as f:
+            data = json.load(f)
+
+        milestones = data.get("milestones", {})
+        milestone = milestones.get(milestone_name)
+
+        if not milestone:
+            return None
+
+        # Calculate progress
+        items = data.get("work_items", {})
+        milestone_items = [
+            {**item, "id": item_id}
+            for item_id, item in items.items()
+            if item.get("milestone") == milestone_name
+        ]
+
+        total = len(milestone_items)
+        completed = sum(
+            1 for item in milestone_items if item["status"] == WorkItemStatus.COMPLETED.value
+        )
+        percent = int((completed / total) * 100) if total > 0 else 0
+
+        return {
+            "name": milestone_name,
+            "title": milestone["title"],
+            "description": milestone["description"],
+            "target_date": milestone.get("target_date", ""),
+            "progress": percent,
+            "total_items": total,
+            "completed_items": completed,
+            "milestone_items": milestone_items,
+        }