roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/health/issue_health_scanner.py

@@ -0,0 +1,263 @@
+"""Issue-specific health scanner extracted from EntityHealthScanner.
+
+This contains the logic that was previously embedded inside
+`entity_health_scanner.EntityHealthScanner` for scanning `Issue` objects.
+"""
+
+from typing import Any
+
+from roadmap.common.constants import Status
+from roadmap.common.logging import get_logger
+from roadmap.common.observability.instrumentation import traced
+from roadmap.core.domain.comment import Comment
+from roadmap.core.domain.issue import Issue
+from roadmap.core.services.health.health_models import (
+    EntityHealthReport,
+    EntityType,
+    HealthIssue,
+    HealthSeverity,
+)
+
+logger = get_logger(__name__)
+
+
+class IssueHealthScanner:
+    """Scan a single issue for health problems (extracted implementations)."""
+
+    def __init__(self, core: Any = None):
+        """Initialize IssueHealthScanner.
+
+        Args:
+            core: Core roadmap instance.
+        """
+        self.core = core
+
+    @traced("scan_issue")
+    def scan_issue(self, issue: Issue) -> EntityHealthReport:
+        """Scan an issue and return its health report.
+
+        Args:
+            issue: Issue to scan for health problems.
+
+        Returns:
+            Health report for the scanned issue.
+        """
+        report = EntityHealthReport(
+            entity_id=issue.id,
+            entity_type=EntityType.ISSUE,
+            entity_title=issue.title,
+            status=issue.status.value,
+        )
+
+        self._check_issue_description(issue, report)
+        self._check_issue_comments(issue, report)
+        self._check_issue_estimates(issue, report)
+        self._check_issue_dates(issue, report)
+        self._check_issue_assignee(issue, report)
+        self._check_issue_progress(issue, report)
+        self._check_issue_status_consistency(issue, report)
+
+        return report
+
+    def _check_issue_description(self, issue: Issue, report: EntityHealthReport):
+        if not issue.content or not issue.content.strip():
+            report.issues.append(
+                HealthIssue(
+                    code="missing_description",
+                    message="Issue has no description or content",
+                    severity=HealthSeverity.INFO,
+                    category="content",
+                )
+            )
+
+    def _check_issue_comments(self, issue: Issue, report: EntityHealthReport):
+        if not issue.comments:
+            return
+
+        errors = self._validate_comment_thread(issue.comments)
+        for error_msg in errors:
+            if "Duplicate" in error_msg:
+                code = "duplicate_comment_id"
+                severity = HealthSeverity.ERROR
+            elif "circular" in error_msg.lower():
+                code = "circular_comment_reference"
+                severity = HealthSeverity.ERROR
+            elif "datetime" in error_msg:
+                code = "invalid_comment_datetime"
+                severity = HealthSeverity.ERROR
+            elif "Empty" in error_msg:
+                code = "empty_comment_body"
+                severity = HealthSeverity.WARNING
+            elif "author" in error_msg.lower():
+                code = "missing_comment_author"
+                severity = HealthSeverity.WARNING
+            else:
+                code = "invalid_comment"
+                severity = HealthSeverity.WARNING
+
+            report.issues.append(
+                HealthIssue(
+                    code=code,
+                    message=error_msg,
+                    severity=severity,
+                    category="content",
+                    details={"comment_count": len(issue.comments)},
+                )
+            )
+
+    def _check_issue_estimates(self, issue: Issue, report: EntityHealthReport):
+        if issue.status not in (Status.IN_PROGRESS, Status.CLOSED):
+            return
+
+        if issue.estimated_hours is None:
+            report.issues.append(
+                HealthIssue(
+                    code="missing_estimate",
+                    message=f"Issue is {issue.status.value} but has no time estimate",
+                    severity=HealthSeverity.INFO,
+                    category="structure",
+                )
+            )
+        elif issue.estimated_hours <= 0:
+            report.issues.append(
+                HealthIssue(
+                    code="invalid_estimate",
+                    message=f"Estimated hours must be positive, got {issue.estimated_hours}",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                    details={"estimated_hours": issue.estimated_hours},
+                )
+            )
+
+    def _check_issue_dates(self, issue: Issue, report: EntityHealthReport):
+        if issue.actual_start_date and issue.actual_end_date:
+            if issue.actual_start_date > issue.actual_end_date:
+                report.issues.append(
+                    HealthIssue(
+                        code="invalid_date_range",
+                        message="Start date is after end date",
+                        severity=HealthSeverity.ERROR,
+                        category="structure",
+                        details={
+                            "actual_start_date": issue.actual_start_date.isoformat(),
+                            "actual_end_date": issue.actual_end_date.isoformat(),
+                        },
+                    )
+                )
+
+        if issue.due_date and issue.actual_end_date:
+            if issue.actual_end_date > issue.due_date:
+                report.issues.append(
+                    HealthIssue(
+                        code="missed_due_date",
+                        message=f"Issue completed after due date ({issue.due_date.date()})",
+                        severity=HealthSeverity.INFO,
+                        category="structure",
+                        details={
+                            "due_date": issue.due_date.isoformat(),
+                            "completed_date": issue.actual_end_date.isoformat(),
+                        },
+                    )
+                )
+
+    def _check_issue_assignee(self, issue: Issue, report: EntityHealthReport):
+        if issue.previous_assignee and not issue.handoff_date:
+            report.issues.append(
+                HealthIssue(
+                    code="missing_handoff_date",
+                    message=f"Issue was handed off from {issue.previous_assignee} but no handoff date recorded",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                    details={"previous_assignee": issue.previous_assignee},
+                )
+            )
+
+    def _check_issue_progress(self, issue: Issue, report: EntityHealthReport):
+        if issue.progress_percentage is not None:
+            if not (0 <= issue.progress_percentage <= 100):
+                report.issues.append(
+                    HealthIssue(
+                        code="invalid_progress_percentage",
+                        message=f"Progress must be 0-100, got {issue.progress_percentage}",
+                        severity=HealthSeverity.ERROR,
+                        category="structure",
+                        details={"progress_percentage": issue.progress_percentage},
+                    )
+                )
+
+        if issue.status == Status.CLOSED and issue.progress_percentage != 100:
+            report.issues.append(
+                HealthIssue(
+                    code="inconsistent_completion",
+                    message=f"Issue marked Done but only {issue.progress_percentage or 0}% complete",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                    details={"progress_percentage": issue.progress_percentage},
+                )
+            )
+
+    def _check_issue_status_consistency(self, issue: Issue, report: EntityHealthReport):
+        if issue.status == Status.CLOSED and not issue.actual_end_date:
+            report.issues.append(
+                HealthIssue(
+                    code="missing_completion_date",
+                    message="Issue marked Done but has no actual end date recorded",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                )
+            )
+
+        if issue.actual_start_date and issue.status == Status.TODO:
+            report.issues.append(
+                HealthIssue(
+                    code="inconsistent_status",
+                    message="Issue has a start date but status is still TODO",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                    details={"actual_start_date": issue.actual_start_date.isoformat()},
+                )
+            )
+
+    @staticmethod
+    def _validate_comment_thread(comments: list[Comment]) -> list[str]:
+        errors = []
+        comment_ids = set()
+
+        for comment in comments:
+            if comment.id in comment_ids:
+                errors.append(f"Duplicate comment ID: {comment.id}")
+            comment_ids.add(comment.id)
+
+            if not comment.body or not comment.body.strip():
+                errors.append(f"Comment {comment.id}: Empty comment body")
+
+            if not comment.author or not comment.author.strip():
+                errors.append(f"Comment {comment.id}: Missing comment author")
+
+            # best-effort datetime sanity check
+            try:
+                _ = comment.created_at
+            except Exception:
+                errors.append(
+                    f"Comment {comment.id}: created_at is not a valid datetime"
+                )
+
+        for comment in comments:
+            if comment.in_reply_to:
+                visited = set()
+                current_id = comment.in_reply_to
+                while current_id:
+                    if current_id in visited:
+                        errors.append(
+                            f"Comment {comment.id}: Circular reference in reply chain"
+                        )
+                        break
+                    visited.add(current_id)
+                    current_comment = next(
+                        (c for c in comments if c.id == current_id), None
+                    )
+                    current_id = (
+                        current_comment.in_reply_to if current_comment else None
+                    )
+
+        return errors

roadmap/core/services/helpers/__init__.py

@@ -0,0 +1,18 @@
+"""Helper utilities for sync and core services.
+
+DEPRECATED: This module is deprecated. Import directly from status_change_service instead.
+Example: from roadmap.core.services.status_change_service import parse_status_change
+"""
+
+# Backward compatibility re-exports
+from roadmap.core.services.status_change_service import (
+    extract_issue_status_update,
+    extract_milestone_status_update,
+    parse_status_change,
+)
+
+__all__ = [
+    "parse_status_change",
+    "extract_issue_status_update",
+    "extract_milestone_status_update",
+]

roadmap/core/services/helpers/status_change_helpers.py

@@ -0,0 +1,88 @@
+"""Status change parsing and extraction helpers for sync operations.
+
+This module provides utilities for parsing and extracting information from
+status change strings in the format "old_status -> new_status".
+"""
+
+from typing import Any
+
+
+def parse_status_change(change_str: str) -> str | None:
+    """Parse and validate change string in format 'old -> new'.
+
+    Args:
+        change_str: Change string in format "old -> new"
+
+    Returns:
+        The new status string (stripped), or None if format is invalid
+    """
+    if not isinstance(change_str, str) or " -> " not in change_str:
+        return None
+
+    try:
+        parts = change_str.split(" -> ")
+        if len(parts) != 2:
+            return None
+        return parts[1].strip()
+    except (IndexError, AttributeError):
+        return None
+
+
+def extract_issue_status_update(
+    status_change: str,
+) -> dict[str, Any] | None:
+    """Extract and validate issue status update from change string.
+
+    Args:
+        status_change: Change string in format "old -> new"
+
+    Returns:
+        Dict with 'github_state' and 'status_enum', or None if invalid
+    """
+    from roadmap.common.constants import Status
+
+    new_status = parse_status_change(status_change)
+    if new_status is None:
+        return None
+
+    try:
+        # Validate that it's a valid status
+        status_enum = Status(new_status)
+        # Map local status to GitHub state (closed -> closed, others -> open)
+        github_state = "closed" if new_status == Status.CLOSED.value else "open"
+        return {
+            "github_state": github_state,
+            "status_enum": status_enum,
+        }
+    except (ValueError, KeyError):
+        # Invalid status - skip the update
+        return None
+
+
+def extract_milestone_status_update(
+    status_change: str,
+) -> dict[str, Any] | None:
+    """Extract and validate milestone status update from change string.
+
+    Args:
+        status_change: Change string in format "old -> new"
+
+    Returns:
+        Dict with 'github_state' and 'status_enum', or None if invalid
+    """
+    from roadmap.common.constants import MilestoneStatus
+
+    new_status = parse_status_change(status_change)
+    if new_status is None:
+        return None
+
+    github_state = "closed" if new_status == "closed" else "open"
+
+    try:
+        status_enum = MilestoneStatus(new_status)
+        return {
+            "github_state": github_state,
+            "status_enum": status_enum,
+        }
+    except (ValueError, KeyError):
+        return None

roadmap/core/services/initialization/__init__.py

@@ -0,0 +1,19 @@
+"""Initialization service utilities and domain logic.
+
+Provides utilities for project initialization workflow including locks,
+manifests, validation, and orchestration.
+"""
+
+from roadmap.core.services.initialization.utils import (
+    InitializationLock,
+    InitializationManifest,
+)
+from roadmap.core.services.initialization.validator import InitializationValidator
+from roadmap.core.services.initialization.workflow import InitializationWorkflow
+
+__all__ = [
+    "InitializationLock",
+    "InitializationManifest",
+    "InitializationValidator",
+    "InitializationWorkflow",
+]

roadmap/core/services/initialization/utils.py

@@ -0,0 +1,104 @@
+"""Utility classes for initialization workflow."""
+
+import json
+import os
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+
+import structlog
+
+from roadmap.common.console import get_console
+
+logger = structlog.get_logger()
+
+console = get_console()
+
+
+class InitializationLock:
+    """Manages initialization lockfile to prevent concurrent inits."""
+
+    def __init__(self, lock_path: Path):
+        """Initialize InitializationLock.
+
+        Args:
+            lock_path: Path to the lock file.
+        """
+        self.lock_path = lock_path
+
+    def acquire(self) -> bool:
+        """Acquire the lock. Returns False if already locked."""
+        if self.lock_path.exists():
+            return False
+        try:
+            self.lock_path.write_text(
+                f"pid:{os.getpid()}\nstarted:{datetime.now(UTC).isoformat()}\n"
+            )
+            return True
+        except Exception as e:
+            logger.debug("lockfile_creation_failed", error=str(e), action="create_lock")
+            console.print(
+                "⚠️  Could not create init lockfile; proceeding with care",
+                style="yellow",
+            )
+            return True  # Continue anyway
+
+    def release(self) -> None:
+        """Release the lock."""
+        try:
+            if self.lock_path.exists():
+                self.lock_path.unlink()
+        except Exception as e:
+            logger.debug("lockfile_release_failed", error=str(e), action="release_lock")
+
+
+class InitializationManifest:
+    """Tracks created files/directories for potential rollback."""
+
+    def __init__(self, manifest_file: Path):
+        """Initialize InitializationManifest.
+
+        Args:
+            manifest_file: Path to the manifest file.
+        """
+        self.manifest_file = manifest_file
+        self.data: dict[str, list] = {"created": []}
+
+    def add_path(self, path: Path) -> None:
+        """Add a path to the manifest."""
+        if path.exists():
+            self.data["created"].append(str(path))
+            self._save()
+
+    def _save(self) -> None:
+        """Save manifest to disk (best effort)."""
+        try:
+            self.manifest_file.write_text(json.dumps(self.data))
+        except Exception as e:
+            logger.debug("manifest_save_failed", error=str(e), action="save_manifest")
+
+    def rollback(self) -> None:
+        """Remove all paths tracked in the manifest."""
+        if not self.manifest_file.exists():
+            return
+
+        try:
+            data = json.loads(self.manifest_file.read_text())
+            for p in data.get("created", []):
+                try:
+                    ppath = Path(p)
+                    if ppath.is_file():
+                        ppath.unlink()
+                    elif ppath.is_dir():
+                        shutil.rmtree(ppath)
+                except Exception as e:
+                    logger.debug(
+                        "manifest_item_removal_failed",
+                        path=p,
+                        error=str(e),
+                        action="remove_item",
+                    )
+        except Exception as e:
+            logger.debug(
+                "manifest_rollback_failed", error=str(e), action="rollback_manifest"
+            )

roadmap/core/services/initialization/validator.py

@@ -0,0 +1,78 @@
+"""Validation utilities for initialization workflow."""
+
+from pathlib import Path
+from typing import Any
+
+from roadmap.common.console import get_console
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+console = get_console()
+
+
+class InitializationValidator:
+    """Validates initialization prerequisites and results."""
+
+    @staticmethod
+    def check_existing_roadmap(
+        core: RoadmapCore, force: bool
+    ) -> tuple[bool, str | None]:
+        """Check if roadmap already exists.
+
+        Returns:
+            Tuple of (should_continue, error_message)
+        """
+        roadmap_path = core.roadmap_dir
+
+        # Check if roadmap path exists as a file (not a directory)
+        if roadmap_path.exists() and not roadmap_path.is_dir():
+            return False, f"Roadmap path exists but is not a directory: {roadmap_path}"
+
+        if not core.is_initialized():
+            return True, None
+
+        # If force is true, we'll be doing a full reset
+        if force:
+            return True, None
+
+        # If roadmap exists but force is not specified, we allow init to continue
+        # to update config/metadata without destroying existing data
+        return True, None
+
+    @staticmethod
+    def validate_lockfile(lock_path: Path) -> tuple[bool, str | None]:
+        """Check for concurrent initialization."""
+        if lock_path.exists():
+            return (
+                False,
+                "Initialization already in progress (lockfile present). Try again later.",
+            )
+        return True, None
+
+    @staticmethod
+    def post_init_validate(
+        core: RoadmapCore, name: str, project_info: dict[str, Any] | None
+    ) -> bool:
+        """Validate initialization results.
+
+        Returns:
+            True if validation passed, False if warnings were found
+        """
+        warnings = []
+
+        # Check core directories
+        if not core.roadmap_dir.exists():
+            warnings.append(f"Roadmap directory {name}/ not found")
+        if not core.config_file.exists():
+            warnings.append("Config file not created")
+
+        # Check project if one was supposed to be created
+        if project_info and not core.projects_dir.exists():
+            warnings.append("Projects directory not created")
+
+        if warnings:
+            console.print("⚠️  Validation warnings:", style="yellow")
+            for warning in warnings:
+                console.print(f"  - {warning}", style="yellow")
+            return False
+
+        return True