roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/utils/dependency_analyzer.py

@@ -0,0 +1,360 @@
+"""Dependency analysis service for detecting issues in issue relationships.
+
+Analyzes depends_on and blocks relationships to detect:
+- Circular dependencies (A → B → A)
+- Broken references (pointing to non-existent issues)
+- Self-dependencies (issue depends on itself)
+- Orphaned blockers (issue blocks non-existent issue)
+- Deep dependency chains (chains > 5 levels)
+"""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from roadmap.common.logging import get_logger
+from roadmap.common.logging.error_logging import (
+    log_error_with_context,
+)
+from roadmap.common.observability.instrumentation import traced
+from roadmap.core.domain.issue import Issue
+
+logger = get_logger(__name__)
+
+
+class DependencyIssueType(StrEnum):
+    """Types of dependency issues that can be found."""
+
+    CIRCULAR = "circular_dependency"
+    BROKEN = "broken_dependency"
+    SELF = "self_dependency"
+    ORPHANED_BLOCKER = "orphaned_blocker"
+    DEEP_CHAIN = "deep_dependency_chain"
+    MISSING_BIDIRECTIONAL = "missing_bidirectional"
+
+
+@dataclass
+class DependencyIssue:
+    """A problem found in issue dependencies."""
+
+    issue_id: str
+    issue_type: DependencyIssueType
+    message: str
+    affected_issues: list[str] = field(default_factory=list)
+    chain_length: int | None = None  # For deep chain issues
+    severity: str = "warning"  # error, warning, info
+
+    def __post_init__(self):
+        """Set severity based on issue type."""
+        if self.issue_type == DependencyIssueType.CIRCULAR:
+            self.severity = "error"
+        elif self.issue_type == DependencyIssueType.BROKEN:
+            self.severity = "error"
+        elif self.issue_type == DependencyIssueType.SELF:
+            self.severity = "error"
+        elif self.issue_type == DependencyIssueType.ORPHANED_BLOCKER:
+            self.severity = "warning"
+        elif self.issue_type == DependencyIssueType.DEEP_CHAIN:
+            self.severity = "info"
+        elif self.issue_type == DependencyIssueType.MISSING_BIDIRECTIONAL:
+            self.severity = "warning"
+
+
+@dataclass
+class DependencyAnalysisResult:
+    """Result of analyzing all dependencies."""
+
+    total_issues: int
+    issues_with_dependencies: int
+    issues_with_problems: int
+    problems: list[DependencyIssue] = field(default_factory=list)
+    circular_chains: list[list[str]] = field(
+        default_factory=list
+    )  # Lists of issue IDs forming cycles
+
+    @property
+    def is_healthy(self) -> bool:
+        """Check if all dependencies are healthy."""
+        return (
+            not any(p.severity == "error" for p in self.problems)
+            and not self.circular_chains
+        )
+
+    @property
+    def error_count(self) -> int:
+        """Count of critical errors."""
+        return len([p for p in self.problems if p.severity == "error"]) + len(
+            self.circular_chains
+        )
+
+    @property
+    def warning_count(self) -> int:
+        """Count of warnings."""
+        return len([p for p in self.problems if p.severity == "warning"])
+
+    @property
+    def info_count(self) -> int:
+        """Count of informational issues."""
+        return len([p for p in self.problems if p.severity == "info"])
+
+
+class DependencyAnalyzer:
+    """Analyzes issue dependency relationships for problems."""
+
+    def __init__(self):
+        """Initialize the analyzer."""
+        self._issue_map: dict[str, Issue] = {}
+        self._analyzed = False
+
+    @traced("analyze_dependencies")
+    def analyze(self, issues: list[Issue]) -> DependencyAnalysisResult:
+        """Analyze all dependencies in the issue set.
+
+        Args:
+            issues: List of all issues in the system
+
+        Returns:
+            DependencyAnalysisResult with all problems found
+        """
+        try:
+            self._issue_map = {issue.id: issue for issue in issues}
+            self._analyzed = True
+
+            result = DependencyAnalysisResult(
+                total_issues=len(issues),
+                issues_with_dependencies=sum(
+                    1 for i in issues if i.depends_on or i.blocks
+                ),
+                issues_with_problems=0,
+            )
+
+            # Check all issues
+            for issue in issues:
+                self._check_issue_dependencies(issue, result)
+
+            result.issues_with_problems = len({p.issue_id for p in result.problems})
+
+            return result
+        except Exception as e:
+            log_error_with_context(
+                e,
+                operation="analyze_dependencies",
+                entity_type="Issue",
+                additional_context={"total_issues": len(issues)},
+            )
+            raise
+
+    def _check_depends_on_links(
+        self, issue: Issue, result: DependencyAnalysisResult
+    ) -> None:
+        """Check the depends_on list for self-deps, broken refs, and missing bidirectional links."""
+        for dep_id in issue.depends_on or []:
+            if dep_id == issue.id:
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.SELF,
+                        message="Issue depends on itself",
+                        affected_issues=[dep_id],
+                    )
+                )
+                continue
+            if dep_id not in self._issue_map:
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.BROKEN,
+                        message=f"Depends on non-existent issue {dep_id}",
+                        affected_issues=[dep_id],
+                    )
+                )
+                continue
+            dep_issue = self._issue_map[dep_id]
+            if issue.id not in (dep_issue.blocks or []):
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.MISSING_BIDIRECTIONAL,
+                        message=f"Depends on {dep_id} but {dep_id} does not list this as a blocker",
+                        affected_issues=[dep_id],
+                    )
+                )
+
+    def _check_blocks_links(
+        self, issue: Issue, result: DependencyAnalysisResult
+    ) -> None:
+        """Check the blocks list for self-blocks, orphaned refs, and missing bidirectional links."""
+        for blocked_id in issue.blocks or []:
+            if blocked_id == issue.id:
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.SELF,
+                        message="Issue blocks itself",
+                        affected_issues=[blocked_id],
+                    )
+                )
+                continue
+            if blocked_id not in self._issue_map:
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.ORPHANED_BLOCKER,
+                        message=f"Blocks non-existent issue {blocked_id}",
+                        affected_issues=[blocked_id],
+                    )
+                )
+                continue
+            blocked_issue = self._issue_map[blocked_id]
+            if issue.id not in (blocked_issue.depends_on or []):
+                result.problems.append(
+                    DependencyIssue(
+                        issue_id=issue.id,
+                        issue_type=DependencyIssueType.MISSING_BIDIRECTIONAL,
+                        message=f"Blocks {blocked_id} but {blocked_id} does not list this as a dependency",
+                        affected_issues=[blocked_id],
+                    )
+                )
+
+    def _check_chain_and_cycles(
+        self, issue: Issue, result: DependencyAnalysisResult
+    ) -> None:
+        """Check for deep dependency chains and circular dependencies."""
+        if not issue.depends_on:
+            return
+        max_depth = self._find_max_chain_depth(issue.id, set(), 0)
+        if max_depth > 5:
+            result.problems.append(
+                DependencyIssue(
+                    issue_id=issue.id,
+                    issue_type=DependencyIssueType.DEEP_CHAIN,
+                    message=f"Deep dependency chain ({max_depth} levels)",
+                    affected_issues=issue.depends_on,
+                    chain_length=max_depth,
+                )
+            )
+        for dep_id in issue.depends_on:
+            cycle = self._find_cycle_from(dep_id, issue.id, set())
+            if cycle:
+                cycle_list = sorted(list(cycle) + [issue.id])
+                if cycle_list not in result.circular_chains:
+                    result.circular_chains.append(cycle_list)
+                    result.problems.append(
+                        DependencyIssue(
+                            issue_id=issue.id,
+                            issue_type=DependencyIssueType.CIRCULAR,
+                            message=f"Circular dependency detected: {' → '.join(cycle_list)} → {issue.id}",
+                            affected_issues=cycle_list,
+                        )
+                    )
+
+    def _check_issue_dependencies(
+        self, issue: Issue, result: DependencyAnalysisResult
+    ) -> None:
+        """Check all dependency relationships for a single issue."""
+        self._check_depends_on_links(issue, result)
+        self._check_blocks_links(issue, result)
+        self._check_chain_and_cycles(issue, result)
+
+    def _find_cycle_from(
+        self, current_id: str, target_id: str, visited: set[str]
+    ) -> set[str] | None:
+        """Find if there's a path from current_id back to target_id.
+
+        Args:
+            current_id: ID to start searching from
+            target_id: ID we're trying to reach (forming a cycle)
+            visited: IDs already visited in this search
+
+        Returns:
+            Set of IDs in the cycle if found, None otherwise
+        """
+        if current_id not in self._issue_map:
+            return None
+
+        if current_id in visited:
+            return None  # Already visited this node, not our cycle
+
+        if current_id == target_id:
+            return {current_id}  # Found the cycle!
+
+        visited.add(current_id)
+        issue = self._issue_map[current_id]
+
+        # Check all issues this one depends on
+        for dep_id in issue.depends_on or []:
+            result = self._find_cycle_from(dep_id, target_id, visited.copy())
+            if result:
+                result.add(current_id)
+                return result
+
+        return None
+
+    def _find_max_chain_depth(
+        self, current_id: str, visited: set[str], depth: int
+    ) -> int:
+        """Find the maximum dependency chain depth from current issue.
+
+        Args:
+            current_id: Issue ID to start from
+            visited: Set of visited IDs (to avoid infinite loops)
+            depth: Current depth in the chain
+
+        Returns:
+            Maximum chain depth found
+        """
+        if current_id not in self._issue_map:
+            return depth
+
+        if current_id in visited:
+            return depth  # Cycle detected, return current depth
+
+        visited.add(current_id)
+        issue = self._issue_map[current_id]
+
+        if not issue.depends_on:
+            return depth  # No further dependencies
+
+        # Find the maximum depth through any dependency
+        max_depth = depth
+        for dep_id in issue.depends_on:
+            depth_through_dep = self._find_max_chain_depth(
+                dep_id, visited.copy(), depth + 1
+            )
+            max_depth = max(max_depth, depth_through_dep)
+
+        return max_depth
+
+    @traced("get_issues_affecting")
+    def get_issues_affecting(self, issue_id: str) -> list[str]:
+        """Get all issues that this one affects through dependency chain.
+
+        Args:
+            issue_id: The issue to start from
+
+        Returns:
+            List of issue IDs that would be affected if this issue changes
+        """
+        if issue_id not in self._issue_map:
+            return []
+
+        affected = set()
+        self._collect_affected(issue_id, affected)
+        return sorted(affected)
+
+    def _collect_affected(self, issue_id: str, affected: set[str]):
+        """Recursively collect all issues affected by this one.
+
+        An issue is affected if this one blocks it (directly or indirectly).
+        """
+        if not self._analyzed:
+            return
+
+        # Find all issues that depend on this one (it affects them)
+        if issue_id in self._issue_map:
+            issue = self._issue_map[issue_id]
+            for blocked_id in issue.blocks or []:
+                if blocked_id in self._issue_map:
+                    if blocked_id not in affected:
+                        affected.add(blocked_id)
+                        # Recursively get issues affected by the blocked issue
+                        self._collect_affected(blocked_id, affected)

roadmap/core/services/utils/field_conflict_detector.py

@@ -0,0 +1,126 @@
+"""Detects field-level conflicts between local and remote issues.
+
+Extracted from SyncStateComparator to separate conflict detection logic.
+"""
+
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.core.domain.issue import Issue
+from roadmap.core.services.sync.sync_conflict_resolver import ConflictField
+
+logger = get_logger(__name__)
+
+
+class FieldConflictDetector:
+    """Detects field-level conflicts between local and remote issues."""
+
+    def __init__(self, fields_to_sync: list[str] | None = None):
+        """Initialize with fields to check for conflicts.
+
+        Args:
+            fields_to_sync: List of field names to check for conflicts
+        """
+        self.fields_to_sync = fields_to_sync or [
+            "status",
+            "priority",
+            "content",
+            "labels",
+            "assignee",
+        ]
+
+    def detect_field_conflicts(
+        self, local_issue: Issue, remote_issue: Any, extractors: dict | None = None
+    ) -> list[ConflictField]:
+        """Detect which fields differ between local and remote issues.
+
+        Args:
+            local_issue: Local Issue object
+            remote_issue: Remote issue object or dict
+            extractors: Optional dict of field→extractor function mappings
+
+        Returns:
+            List of ConflictField objects for conflicting fields
+        """
+        conflicting_fields = []
+
+        if extractors is None:
+            extractors = {}
+
+        for field in self.fields_to_sync:
+            try:
+                # Get local value
+                local_value = self._get_field_value(local_issue, field)
+
+                # Get remote value
+                remote_value = self._get_field_value(remote_issue, field)
+
+                # Check for conflict
+                if local_value != remote_value:
+                    conflict_field = ConflictField(
+                        field_name=field,
+                        local_value=local_value,
+                        remote_value=remote_value,
+                        local_updated=getattr(local_issue, "updated", None),
+                        remote_updated=getattr(remote_issue, "updated_at", None),
+                    )
+                    conflicting_fields.append(conflict_field)
+                    logger.debug(
+                        "conflict_detected_in_field",
+                        field=field,
+                        local_value=str(local_value)[:100],
+                        remote_value=str(remote_value)[:100],
+                    )
+
+            except Exception as e:
+                logger.warning(
+                    "conflict_detection_error",
+                    field=field,
+                    error=str(e),
+                )
+                continue
+
+        return conflicting_fields
+
+    @staticmethod
+    def _get_field_value(obj: Any, field: str) -> Any:
+        """Get field value from object (handles dict and objects).
+
+        Args:
+            obj: Object or dict to extract field from
+            field: Field name
+
+        Returns:
+            Field value, or None if not found
+        """
+        if obj is None:
+            return None
+
+        try:
+            if isinstance(obj, dict):
+                return obj.get(field)
+
+            # Handle enums (e.g., Status enum)
+            value = getattr(obj, field, None)
+            if value is None:
+                return None
+
+            # If it's an enum with .value, use that
+            if hasattr(value, "value"):
+                return value.value
+
+            # Handle special cases
+            if field == "labels" and isinstance(value, list):
+                return sorted(value) if value else []
+
+            return value
+
+        except Exception as e:
+            logger.debug(
+                "normalize_field_value_failed",
+                operation="normalize_field_value",
+                error=str(e),
+                action="Returning None",
+            )
+            return None

roadmap/core/services/utils/remote_fetcher.py

@@ -0,0 +1,202 @@
+"""Remote data fetching with retry logic and request management."""
+
+import time
+from collections.abc import Iterable
+from typing import Any
+
+from structlog import get_logger
+
+from roadmap.core.services.utils.retry_policy import RetryPolicy
+
+logger = get_logger(__name__)
+
+
+class RemoteFetcher:
+    """Utility for fetching remote issue data via an adapter.
+
+    Adds retry/backoff logic and basic rate-limit handling to adapter calls.
+    Prefer batch APIs (`pull_issues`) when available; fall back to
+    per-item APIs (`pull_issue`) otherwise.
+    """
+
+    DEFAULT_RETRY_POLICY = RetryPolicy(max_retries=3, base_delay=0.5, factor=2.0)
+
+    @staticmethod
+    def _handle_rate_limit_from_response(resp: Any) -> float:
+        """Inspect a response-like object for rate-limit headers and return sleep seconds.
+
+        Returns 0.0 if no rate-limit sleep is required. If the response exposes
+        `headers` or `raw_response` with `X-RateLimit-Remaining` and
+        `X-RateLimit-Reset`, this will compute the seconds until reset.
+        """
+        try:
+            from collections.abc import Mapping
+
+            headers = None
+            if isinstance(resp, Mapping):
+                headers = resp.get("headers")
+            else:
+                headers = getattr(resp, "headers", None)
+                if headers is None:
+                    raw = getattr(resp, "raw_response", None)
+                    if isinstance(raw, Mapping):
+                        headers = raw.get("headers")
+                    else:
+                        headers = getattr(raw, "headers", None)
+
+            if not headers or not isinstance(headers, Mapping):
+                return 0.0
+
+            remaining = headers.get("X-RateLimit-Remaining") or headers.get(
+                "x-ratelimit-remaining"
+            )
+            reset = headers.get("X-RateLimit-Reset") or headers.get("x-ratelimit-reset")
+            if remaining is not None and str(remaining) == "0" and reset:
+                try:
+                    reset_ts = int(reset)
+                    now_ts = int(time.time())
+                    wait = max(0, reset_ts - now_ts)
+                    return float(wait)
+                except Exception as e:
+                    logger.debug(
+                        "reset_time_parsing_failed",
+                        operation="parse_reset_time",
+                        reset_value=str(reset),
+                        error=str(e),
+                        action="Using default wait time 0",
+                    )
+                    return 0.0
+        except Exception as e:
+            logger.debug(
+                "rate_limit_check_failed",
+                operation="check_rate_limit",
+                error=str(e),
+                action="Assuming no rate limit",
+            )
+            return 0.0
+        return 0.0
+
+    @staticmethod
+    def fetch_issue(
+        adapter: Any, issue_id: str, retry_policy: RetryPolicy | None = None
+    ) -> Any:
+        """Fetch a single issue from remote adapter with retry logic.
+
+        Args:
+            adapter: Remote adapter instance with pull_issue method.
+            issue_id: The issue ID to fetch.
+            retry_policy: Optional custom retry policy.
+
+        Returns:
+            The fetched issue or None if fetch fails.
+        """
+        if adapter is None:
+            return None
+
+        rp = retry_policy or RemoteFetcher.DEFAULT_RETRY_POLICY
+
+        for attempt in range(1, rp.max_retries + 1):
+            try:
+                if hasattr(adapter, "pull_issue"):
+                    result = adapter.pull_issue(issue_id)
+                    # Check for rate-limit hints
+                    sleep_for = RemoteFetcher._handle_rate_limit_from_response(result)
+                    if sleep_for and sleep_for > 0:
+                        logger.info(
+                            "remote_rate_limited",
+                            issue_id=issue_id,
+                            wait_seconds=sleep_for,
+                        )
+                        time.sleep(sleep_for)
+                    return result
+                return None
+            except Exception as e:
+                logger.warning(
+                    "remote_fetch_issue_error",
+                    issue_id=issue_id,
+                    attempt=attempt,
+                    error=str(e),
+                    severity="infrastructure",
+                )
+                if attempt == rp.max_retries:
+                    logger.error(
+                        "remote_fetch_issue_failed",
+                        issue_id=issue_id,
+                        attempts=attempt,
+                        severity="infrastructure",
+                    )
+                    return None
+                # Backoff
+                delay = rp.get_backoff_delay(attempt)
+                logger.info(
+                    "remote_fetch_retry",
+                    issue_id=issue_id,
+                    attempt=attempt + 1,
+                    delay=delay,
+                )
+                time.sleep(delay)
+
+        return None
+
+    @staticmethod
+    def fetch_issues(
+        adapter: Any, issue_ids: Iterable[str], retry_policy: RetryPolicy | None = None
+    ) -> list[Any]:
+        """Fetch multiple issues from remote adapter with retry logic.
+
+        Args:
+            adapter: Remote adapter instance with pull_issue method.
+            issue_ids: Iterable of issue IDs to fetch.
+            retry_policy: Optional custom retry policy.
+
+        Returns:
+            List of fetched issues.
+        """
+        if adapter is None:
+            return []
+
+        rp = retry_policy or RemoteFetcher.DEFAULT_RETRY_POLICY
+
+        ids = list(issue_ids)
+        if not ids:
+            return []
+
+        # Try batch API first with retries
+        if hasattr(adapter, "pull_issues"):
+            for attempt in range(1, rp.max_retries + 1):
+                try:
+                    result = adapter.pull_issues(ids)
+                    # If adapter returns report-like object, inspect for rate-limit
+                    sleep_for = RemoteFetcher._handle_rate_limit_from_response(result)
+                    if sleep_for and sleep_for > 0:
+                        logger.info(
+                            "remote_rate_limited_batch",
+                            count=len(ids),
+                            wait_seconds=sleep_for,
+                        )
+                        time.sleep(sleep_for)
+                    return result or []
+                except Exception as e:
+                    logger.warning(
+                        "remote_fetch_issues_error",
+                        attempt=attempt,
+                        error=str(e),
+                        severity="infrastructure",
+                    )
+                    if attempt == rp.max_retries:
+                        logger.error(
+                            "remote_fetch_issues_failed",
+                            attempts=attempt,
+                            severity="infrastructure",
+                        )
+                        break
+                    delay = rp.get_backoff_delay(attempt)
+                    logger.info("remote_fetch_retry", attempt=attempt + 1, delay=delay)
+                    time.sleep(delay)
+
+        # Fallback to individual calls with retries per-item
+        results: list[Any] = []
+        for i in ids:
+            res = RemoteFetcher.fetch_issue(adapter, i, retry_policy=rp)
+            results.append(res)
+        return results