roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/sync/three_way_merger.py

@@ -0,0 +1,178 @@
+"""Three-way merge logic for intelligent sync conflict resolution.
+
+Implements the core algorithm: base vs local vs remote comparison
+to automatically resolve most conflicts without data loss.
+"""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+class MergeStatus(StrEnum):
+    """Result of merging a field."""
+
+    CLEAN = "clean"  # Auto-resolved, no conflict
+    CONFLICT = "conflict"  # Both sides changed differently
+
+
+@dataclass
+class FieldMergeResult:
+    """Result of merging a single field."""
+
+    value: Any
+    status: MergeStatus
+    reason: str  # Why this decision was made
+
+    def is_conflict(self) -> bool:
+        """Check if this is a conflict."""
+        return self.status == MergeStatus.CONFLICT
+
+
+class ThreeWayMerger:
+    """Implements three-way merge logic.
+
+    Given base, local, and remote versions of a field, intelligently
+    determines the merged value using this algorithm:
+
+    - If only local changed: take local
+    - If only remote changed: take remote
+    - If both changed the same way: take either (no conflict)
+    - If neither changed: take either (no conflict)
+    - If both changed differently: CONFLICT (needs resolution)
+    """
+
+    def merge_field(
+        self,
+        field_name: str,
+        base: Any,
+        local: Any,
+        remote: Any,
+    ) -> FieldMergeResult:
+        """Merge a single field using three-way logic.
+
+        Args:
+            field_name: Name of the field (for debugging)
+            base: The agreed-upon value from last sync
+            local: Current local value
+            remote: Current remote value
+
+        Returns:
+            FieldMergeResult with merged value and status
+        """
+        # Case 1: Neither changed (everything stayed at base)
+        if local == base and remote == base:
+            return FieldMergeResult(
+                value=local,
+                status=MergeStatus.CLEAN,
+                reason=f"{field_name}: no changes",
+            )
+
+        # Case 2: Only local changed (remote stayed at base)
+        if local != base and remote == base:
+            return FieldMergeResult(
+                value=local,
+                status=MergeStatus.CLEAN,
+                reason=f"{field_name}: only local changed",
+            )
+
+        # Case 3: Only remote changed (local stayed at base)
+        if remote != base and local == base:
+            return FieldMergeResult(
+                value=remote,
+                status=MergeStatus.CLEAN,
+                reason=f"{field_name}: only remote changed",
+            )
+
+        # Case 4: Both changed, but to the same value
+        if local == remote:
+            return FieldMergeResult(
+                value=local,
+                status=MergeStatus.CLEAN,
+                reason=f"{field_name}: both changed to same value",
+            )
+
+        # Case 5: Both changed differently - TRUE CONFLICT
+        return FieldMergeResult(
+            value=None,  # Can't auto-resolve
+            status=MergeStatus.CONFLICT,
+            reason=f"{field_name}: both sides changed differently (base={base}, local={local}, remote={remote})",
+        )
+
+    def merge_issue(
+        self,
+        issue_id: str,
+        base: dict[str, Any],
+        local: dict[str, Any],
+        remote: dict[str, Any],
+    ) -> tuple[dict[str, Any], list[str]]:
+        """Merge all fields of an issue.
+
+        Returns:
+            (merged_fields, list_of_conflicted_field_names)
+
+        Note: Conflicted fields are NOT included in merged_fields.
+        They must be resolved separately by ConflictResolver.
+        """
+        merged = {}
+        conflicts = []
+
+        # Get all field names from all three versions
+        all_fields = set(base.keys()) | set(local.keys()) | set(remote.keys())
+
+        for field in all_fields:
+            result = self.merge_field(
+                field,
+                base.get(field),
+                local.get(field),
+                remote.get(field),
+            )
+
+            if result.is_conflict():
+                conflicts.append(field)
+                # Don't include conflicted fields in merged
+                # They'll be handled by ConflictResolver
+            else:
+                merged[field] = result.value
+
+        return merged, conflicts
+
+    def merge_issues(
+        self,
+        issues: dict[str, dict[str, Any]],
+        base_issues: dict[str, dict[str, Any]],
+        local_issues: dict[str, dict[str, Any]],
+        remote_issues: dict[str, dict[str, Any]],
+    ) -> tuple[dict[str, tuple[dict, list[str]]], list[str]]:
+        """Merge multiple issues.
+
+        Returns:
+            (issue_results, deleted_issues)
+
+        where issue_results[issue_id] = (merged_fields, conflict_fields)
+        and deleted_issues is a list of issues removed on remote
+        """
+        results = {}
+        deleted = []
+
+        # Get all issue IDs from all three versions
+        all_issues = (
+            set(base_issues.keys())
+            | set(local_issues.keys())
+            | set(remote_issues.keys())
+        )
+
+        for issue_id in all_issues:
+            base = base_issues.get(issue_id, {})
+            local = local_issues.get(issue_id, {})
+            remote = remote_issues.get(issue_id, {})
+
+            # If issue was deleted remotely and not modified locally, skip it
+            if not remote and base and not local:
+                deleted.append(issue_id)
+                continue
+
+            merged, conflicts = self.merge_issue(issue_id, base, local, remote)
+            results[issue_id] = (merged, conflicts)
+
+        return results, deleted

roadmap/core/services/utils/__init__.py

@@ -0,0 +1 @@
+"""Package initialization file."""

roadmap/core/services/utils/configuration_service.py

@@ -0,0 +1,113 @@
+"""Configuration management service for roadmap application.
+
+Consolidates settings and credentials management into a single service layer,
+providing unified access to application configuration and secrets.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from roadmap.core.interfaces import CredentialProvider
+from roadmap.settings import settings
+
+logger = structlog.get_logger()
+
+
+class ConfigurationService:
+    """Service for managing application configuration and credentials."""
+
+    def __init__(self, credential_provider: CredentialProvider | None = None):
+        """Initialize configuration service.
+
+        Args:
+            credential_provider: Optional credential provider implementation.
+                                If None, defaults to infrastructure CredentialManager.
+        """
+        if credential_provider is None:
+            from roadmap.infrastructure.security.credentials import CredentialManager
+
+            credential_provider = CredentialManager()
+
+        self.credential_manager = credential_provider
+        self._settings = settings
+
+    # ==================== Configuration Access ====================
+
+    def get_setting(self, key: str, default: Any = None) -> Any:
+        """Get a configuration setting by key.
+
+        Args:
+            key: Configuration key (dot notation supported, e.g. 'database.path')
+            default: Default value if setting not found
+
+        Returns:
+            Configuration value or default
+        """
+        try:
+            return self._settings.get(key, default)
+        except Exception as e:
+            logger.debug(
+                "config_get_failed",
+                operation="get_config",
+                key=key,
+                error=str(e),
+                action="Returning default value",
+            )
+            return default
+
+    def get_github_config(self) -> dict[str, Any]:
+        """Get GitHub integration configuration.
+
+        Returns:
+            GitHub configuration dictionary
+        """
+        return {
+            "enabled": self.get_setting("github.enabled", False),
+            "repo": self.get_setting("github.repo", ""),
+            "sync_labels": self.get_setting("github.sync_labels", True),
+        }
+
+    def get_sync_config(self) -> dict[str, Any]:
+        """Get sync operation configuration.
+
+        Returns:
+            Sync configuration dictionary including duplicate detection thresholds
+        """
+        return {
+            "enable_duplicate_detection": self.get_setting(
+                "sync.enable_duplicate_detection", True
+            ),
+            "duplicate_title_threshold": self.get_setting(
+                "sync.duplicate_title_threshold", 0.90
+            ),
+            "duplicate_content_threshold": self.get_setting(
+                "sync.duplicate_content_threshold", 0.85
+            ),
+            "duplicate_auto_resolve_threshold": self.get_setting(
+                "sync.duplicate_auto_resolve_threshold", 0.95
+            ),
+        }
+
+    # ==================== Credential Management ====================
+
+    def get_github_token(self) -> str | None:
+        """Retrieve GitHub token securely.
+
+        Returns:
+            GitHub token if found, None otherwise
+        """
+        return self.credential_manager.get_token()
+
+    # ==================== Configuration Paths ====================
+
+    def get_config_paths(self) -> dict[str, Path]:
+        """Get configuration file paths.
+
+        Returns:
+            Dictionary of configuration file paths
+        """
+        from roadmap.settings import get_config_paths
+
+        return get_config_paths()

roadmap/core/services/utils/critical_path_calculator.py

@@ -0,0 +1,418 @@
+"""Critical path analysis for issue dependencies.
+
+Calculates which issues are on the critical path and impact project timeline.
+"""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+
+from roadmap.core.domain.issue import Issue
+from roadmap.core.domain.milestone import Milestone
+
+
+@dataclass
+class PathNode:
+    """Represents an issue in the critical path analysis."""
+
+    issue_id: str
+    issue_title: str
+    duration_hours: float
+    dependencies: list[str] = field(default_factory=list)
+    start_date: datetime | None = None
+    end_date: datetime | None = None
+    slack_time: float = 0.0  # Time available before blocking other tasks
+    is_critical: bool = False
+
+
+@dataclass
+class CriticalPathResult:
+    """Results from critical path analysis."""
+
+    critical_path: list[PathNode]
+    total_duration: float
+    critical_issue_ids: list[str]
+    blocking_issues: dict[str, list[str]]  # issue_id -> list of blocked issue_ids
+    project_end_date: datetime | None = None
+    issues_by_criticality: dict[str, list[str]] = field(default_factory=dict)
+
+
+class CriticalPathCalculator:
+    """Calculates critical path for issues based on dependencies."""
+
+    def __init__(self):
+        """Initialize calculator."""
+        pass
+
+    def calculate_critical_path(
+        self, issues: list[Issue], milestone: Milestone | None = None
+    ) -> CriticalPathResult:
+        """Calculate critical path from issues with dependencies.
+
+        Args:
+            issues: List of issues to analyze
+            milestone: Optional milestone context for date calculations
+
+        Returns:
+            CriticalPathResult with critical path information
+        """
+        if not issues:
+            return CriticalPathResult(
+                critical_path=[],
+                total_duration=0.0,
+                critical_issue_ids=[],
+                blocking_issues={},
+            )
+
+        # Build dependency graph
+        graph = self._build_dependency_graph(issues)
+
+        # Calculate earliest start/end dates
+        node_data = self._calculate_schedule(issues, graph)
+
+        # Find critical path
+        critical_path = self._find_critical_path(node_data, graph)
+
+        # Analyze blocking relationships
+        blocking_issues = self._analyze_blocking(issues)
+
+        # Calculate slack time
+        self._calculate_slack(node_data, critical_path)
+
+        # Determine project end date
+        project_end_date = self._calculate_project_end_date(node_data, milestone)
+
+        return CriticalPathResult(
+            critical_path=critical_path,
+            total_duration=sum(node.duration_hours for node in critical_path),
+            critical_issue_ids=[node.issue_id for node in critical_path],
+            blocking_issues=blocking_issues,
+            project_end_date=project_end_date,
+            issues_by_criticality=self._group_by_criticality(issues, critical_path),
+        )
+
+    def _build_dependency_graph(self, issues: list[Issue]) -> dict[str, list[str]]:
+        """Build dependency graph from issues.
+
+        Args:
+            issues: List of issues
+
+        Returns:
+            Dictionary mapping issue_id to list of dependent issue_ids
+        """
+        graph = {issue.id: issue.depends_on or [] for issue in issues}
+        return graph
+
+    def _calculate_schedule(
+        self, issues: list[Issue], graph: dict[str, list[str]]
+    ) -> dict[str, PathNode]:
+        """Calculate earliest start and end times.
+
+        Args:
+            issues: List of issues
+            graph: Dependency graph
+
+        Returns:
+            Dictionary mapping issue_id to PathNode
+        """
+        nodes = {}
+        for issue in issues:
+            duration = self._estimate_duration(issue)
+            nodes[issue.id] = PathNode(
+                issue_id=issue.id,
+                issue_title=issue.title,
+                duration_hours=duration,
+                dependencies=graph.get(issue.id, []),
+            )
+
+        # Calculate earliest start/end times using topological sort
+        start_times = {}
+        visiting = set()  # Track nodes currently being processed to detect cycles
+
+        def calculate_start_time(issue_id: str) -> float:
+            if issue_id in start_times:
+                return start_times[issue_id]
+
+            # Detect circular dependencies
+            if issue_id in visiting:
+                # Return 0 for circular refs (they shouldn't exist, but graceful fallback)
+                return 0.0
+
+            visiting.add(issue_id)
+
+            try:
+                dependencies = graph.get(issue_id, [])
+                if not dependencies:
+                    start_times[issue_id] = 0.0
+                    return 0.0
+
+                # Max end time of all dependencies
+                max_end_time = 0.0
+                for dep_id in dependencies:
+                    if dep_id in nodes:
+                        dep_start = calculate_start_time(dep_id)
+                        dep_duration = nodes[dep_id].duration_hours
+                        max_end_time = max(max_end_time, dep_start + dep_duration)
+
+                start_times[issue_id] = max_end_time
+                return max_end_time
+            finally:
+                visiting.discard(issue_id)
+
+        # Calculate all start times
+        for issue_id in nodes:
+            start_time = calculate_start_time(issue_id)
+            nodes[issue_id].start_date = datetime.now(UTC) + timedelta(hours=start_time)
+            nodes[issue_id].end_date = datetime.now(UTC) + timedelta(
+                hours=start_time + nodes[issue_id].duration_hours
+            )
+
+        return nodes
+
+    def _find_critical_path(
+        self, nodes: dict[str, PathNode], graph: dict[str, list[str]]
+    ) -> list[PathNode]:
+        """Find the critical path (longest duration path through dependencies).
+
+        Args:
+            nodes: Dictionary of nodes with schedule info
+            graph: Dependency graph
+
+        Returns:
+            List of PathNode objects on critical path, ordered by dependency
+        """
+        if not nodes:
+            return []
+
+        # Find leaf nodes (no blocks)
+        leaf_nodes = [
+            issue_id
+            for issue_id, _ in nodes.items()
+            if not any(issue_id in graph.get(other_id, []) for other_id in nodes)
+        ]
+
+        if not leaf_nodes:
+            # If no clear leaf, use nodes with latest end dates
+            leaf_nodes = sorted(
+                nodes.keys(),
+                key=lambda x: nodes[x].end_date or datetime.now(UTC),
+                reverse=True,
+            )[:1]
+
+        # Trace back from leaf nodes to find longest path
+        critical_paths = []
+
+        for leaf_id in leaf_nodes:
+            path = self._trace_path_backward(leaf_id, nodes, graph)
+            critical_paths.append(path)
+
+        # Return longest path
+        critical_path = max(critical_paths, key=lambda p: len(p), default=[])
+
+        # Mark critical nodes
+        for node in critical_path:
+            node.is_critical = True
+
+        return critical_path
+
+    def _trace_path_backward(
+        self, issue_id: str, nodes: dict[str, PathNode], graph: dict[str, list[str]]
+    ) -> list[PathNode]:
+        """Trace path backward from a node to root dependencies.
+
+        Args:
+            issue_id: Starting issue ID
+            nodes: Node dictionary
+            graph: Dependency graph
+
+        Returns:
+            List of nodes in dependency chain
+        """
+        path = []
+        current_id = issue_id
+        visited = set()  # Track visited nodes to prevent infinite loops
+
+        while current_id in nodes:
+            # Detect circular dependencies
+            if current_id in visited:
+                break
+
+            visited.add(current_id)
+            path.append(nodes[current_id])
+            dependencies = graph.get(current_id, [])
+
+            if not dependencies:
+                break
+
+            # Follow the dependency with longest duration
+            current_id = max(
+                dependencies,
+                key=lambda d: nodes.get(d, PathNode("", "", 0)).duration_hours,
+            )
+
+        return list(reversed(path))
+
+    def _estimate_duration(self, issue: Issue) -> float:
+        """Estimate duration from issue estimated_hours field.
+
+        Args:
+            issue: Issue to estimate
+
+        Returns:
+            Duration in hours
+        """
+        if not issue.estimated_hours:
+            return 4.0  # Default 4 hours
+
+        return float(issue.estimated_hours)
+
+    def _calculate_slack(
+        self, nodes: dict[str, PathNode], critical_path: list[PathNode]
+    ) -> None:
+        """Calculate slack time for non-critical paths.
+
+        Args:
+            nodes: Dictionary of all nodes
+            critical_path: List of critical path nodes
+        """
+        # Critical path nodes have no slack
+        critical_ids = {node.issue_id for node in critical_path}
+
+        if critical_path:
+            max_end_time = max(
+                (node.end_date or datetime.now(UTC)) for node in critical_path
+            )
+
+            for node_id, node in nodes.items():
+                if node_id not in critical_ids and node.end_date:
+                    slack_hours = (max_end_time - node.end_date).total_seconds() / 3600
+                    node.slack_time = max(0.0, slack_hours)
+
+    def _calculate_project_end_date(
+        self,
+        nodes: dict[str, PathNode],
+        milestone: Milestone | None = None,
+    ) -> datetime | None:
+        """Calculate expected project completion date.
+
+        Args:
+            nodes: Dictionary of nodes
+            milestone: Optional milestone with due date
+
+        Returns:
+            Expected project end date
+        """
+        if not nodes:
+            return milestone.due_date if milestone else None
+
+        # Project ends when all critical path items complete
+        latest_end = max(
+            (node.end_date for node in nodes.values() if node.end_date),
+            default=None,
+        )
+
+        if latest_end and milestone and milestone.due_date:
+            return min(latest_end, milestone.due_date)
+
+        return latest_end or (milestone.due_date if milestone else None)
+
+    def _analyze_blocking(self, issues: list[Issue]) -> dict[str, list[str]]:
+        """Analyze which issues block others.
+
+        Args:
+            issues: List of issues
+
+        Returns:
+            Dictionary mapping issue_id to list of blocked issue_ids
+        """
+        blocking = {}
+
+        for issue in issues:
+            if issue.blocks:
+                blocking[issue.id] = issue.blocks
+
+        return blocking
+
+    def _group_by_criticality(
+        self, issues: list[Issue], critical_path: list[PathNode]
+    ) -> dict[str, list[str]]:
+        """Group issues by criticality level.
+
+        Args:
+            issues: List of all issues
+            critical_path: List of critical path nodes
+
+        Returns:
+            Dictionary with criticality groups
+        """
+        critical_ids = {node.issue_id for node in critical_path}
+        blocking_issues = set()
+        blocked_issues = set()
+
+        for issue in issues:
+            if issue.blocks:
+                blocking_issues.add(issue.id)
+            if issue.depends_on:
+                blocked_issues.add(issue.id)
+
+        return {
+            "critical": list(critical_ids),
+            "blocking": list(blocking_issues),
+            "blocked": list(blocked_issues),
+            "independent": [
+                issue.id
+                for issue in issues
+                if issue.id not in critical_ids
+                and issue.id not in blocking_issues
+                and issue.id not in blocked_issues
+            ],
+        }
+
+    def find_blocking_issues(
+        self, issues: list[Issue], target_issue_id: str
+    ) -> list[Issue]:
+        """Find all issues blocking a specific issue.
+
+        Args:
+            issues: List of all issues
+            target_issue_id: ID of issue to check
+
+        Returns:
+            List of issues blocking the target
+        """
+        issue_map = {issue.id: issue for issue in issues}
+        target = issue_map.get(target_issue_id)
+
+        if not target or not target.depends_on:
+            return []
+
+        blocking = []
+        for dep_id in target.depends_on:
+            if dep_id in issue_map:
+                blocking.append(issue_map[dep_id])
+
+        return blocking
+
+    def find_blocked_issues(
+        self, issues: list[Issue], blocker_issue_id: str
+    ) -> list[Issue]:
+        """Find all issues blocked by a specific issue.
+
+        Args:
+            issues: List of all issues
+            blocker_issue_id: ID of blocking issue
+
+        Returns:
+            List of issues blocked by the blocker
+        """
+        issue_map = {issue.id: issue for issue in issues}
+        blocker = issue_map.get(blocker_issue_id)
+
+        if not blocker or not blocker.blocks:
+            return []
+
+        blocked = []
+        for blocked_id in blocker.blocks:
+            if blocked_id in issue_map:
+                blocked.append(issue_map[blocked_id])
+
+        return blocked