roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/validators/orphaned_issues_validator.py

@@ -0,0 +1,142 @@
+"""Validator for orphaned issues."""
+
+from pathlib import Path
+
+from roadmap.common.logging import get_logger
+from roadmap.core.domain.issue import Status
+from roadmap.core.services.validator_base import HealthStatus
+
+logger = get_logger(__name__)
+
+
+class OrphanedIssuesValidator:
+    """Validator for orphaned issues (in wrong folder based on milestone)."""
+
+    @staticmethod
+    def scan_for_orphaned_issues(core) -> list[dict]:
+        """Scan for issues in wrong folder (not matching their milestone).
+
+        Returns a list of misplaced issue dicts with id, title, and details.
+        """
+        misplaced = []
+
+        try:
+            issues_dir = Path(".roadmap/issues").resolve()
+            archive_dir = Path(".roadmap/archive/issues").resolve()
+
+            if not issues_dir.exists():
+                return misplaced
+
+            # Scan all issues
+            for issue in core.issues.list():
+                # Determine expected folder
+                expected_folder = OrphanedIssuesValidator._get_expected_folder(issue)
+
+                # Find actual folder
+                actual_folder = OrphanedIssuesValidator._find_issue_folder(
+                    issue.id, issues_dir, archive_dir
+                )
+
+                # Issue is misplaced if:
+                # 1. It's at root level (actual_folder == issues_dir)
+                # 2. Or it's in wrong folder (actual_folder != expected_folder)
+                if actual_folder:
+                    if actual_folder == issues_dir or actual_folder != expected_folder:
+                        misplaced.append(
+                            {
+                                "id": issue.id,
+                                "title": issue.title,
+                                "milestone": issue.milestone or "(none)",
+                                "current_folder": str(actual_folder),
+                                "expected_folder": str(expected_folder),
+                            }
+                        )
+
+        except Exception as e:
+            logger.debug("scan_orphaned_issues_error", error=str(e))
+
+        return misplaced
+
+    @staticmethod
+    def check_orphaned_issues(core) -> tuple[str, str]:
+        """Check for orphaned issues.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            misplaced = OrphanedIssuesValidator.scan_for_orphaned_issues(core)
+
+            if not misplaced:
+                logger.debug("health_check_orphaned_issues", status="none")
+                return HealthStatus.HEALTHY, "No orphaned issues found"
+
+            count = len(misplaced)
+            message = (
+                f"⚠️ {count} orphaned issue(s) found (in wrong folder): "
+                "These issues are not in the folder matching their milestone"
+            )
+            logger.warning(
+                "health_check_orphaned_issues", count=count, severity="operational"
+            )
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.debug("health_check_orphaned_issues_failed", error=str(e))
+            return HealthStatus.HEALTHY, "Could not check for orphaned issues"
+
+    @staticmethod
+    def _get_expected_folder(issue) -> Path:
+        """Determine expected folder for an issue.
+
+        Args:
+            issue: Issue object
+
+        Returns:
+            Path to expected folder
+        """
+        # Closed issues go to archive
+        base_path = (
+            Path(".roadmap/archive/issues").resolve()
+            if issue.status == Status.CLOSED
+            else Path(".roadmap/issues").resolve()
+        )
+
+        # If no milestone, assign to backlog
+        milestone = issue.milestone or "backlog"
+
+        return base_path / milestone
+
+    @staticmethod
+    def _find_issue_folder(
+        issue_id: str, issues_dir: Path, archive_dir: Path
+    ) -> Path | None:
+        """Find the actual folder containing an issue.
+
+        Args:
+            issue_id: Issue ID to find
+            issues_dir: Path to .roadmap/issues
+            archive_dir: Path to .roadmap/archive/issues
+
+        Returns:
+            Path to folder containing the issue, or None if at root level
+        """
+        # Check if file is at root level (loose file)
+        for file in issues_dir.glob(f"{issue_id}*.md"):
+            if file.is_file():
+                return issues_dir  # Return root to indicate it's loose
+
+        # Check main issues directory subfolders
+        for folder in issues_dir.iterdir():
+            if folder.is_dir():
+                for _ in folder.glob(f"{issue_id}*.md"):
+                    return folder
+
+        # Check archive directory
+        if archive_dir.exists():
+            for folder in archive_dir.iterdir():
+                if folder.is_dir():
+                    for _ in folder.glob(f"{issue_id}*.md"):
+                        return folder
+
+        return None

roadmap/core/services/validators/orphaned_milestones_validator.py

@@ -0,0 +1,85 @@
+"""Validator for orphaned milestones."""
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+logger = get_logger(__name__)
+
+
+class OrphanedMilestonesValidator(BaseValidator):
+    """Validator for orphaned milestones (not assigned to any project)."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the orphaned_milestones check.
+        """
+        return "orphaned_milestones"
+
+    @staticmethod
+    def scan_for_orphaned_milestones(core) -> list[dict]:
+        """Scan for milestones not assigned to any project.
+
+        Returns a list of orphaned milestone dicts with name, description, and details.
+        """
+        orphaned = []
+
+        try:
+            all_milestones = core.milestones.list()
+            all_projects = core.projects.list()
+
+            # Build set of milestone names assigned to projects
+            assigned_milestone_names = set()
+            for project in all_projects:
+                assigned_milestone_names.update(project.milestones)
+
+            # Find milestones not in any project
+            for milestone in all_milestones:
+                if milestone.name not in assigned_milestone_names:
+                    orphaned.append(
+                        {
+                            "name": milestone.name,
+                            "content": milestone.content or "(no description)",
+                            "status": milestone.status.value,
+                            "created": milestone.created.isoformat()
+                            if milestone.created
+                            else None,
+                        }
+                    )
+
+        except Exception as e:
+            logger.debug("scan_orphaned_milestones_error", error=str(e))
+
+        return orphaned
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check for orphaned milestones.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            core = RoadmapCore()
+            orphaned = OrphanedMilestonesValidator.scan_for_orphaned_milestones(core)
+
+            if not orphaned:
+                logger.debug("health_check_orphaned_milestones", status="none")
+                return HealthStatus.HEALTHY, "No orphaned milestones found"
+
+            count = len(orphaned)
+            message = (
+                f"⚠️ {count} orphaned milestone(s) found (not assigned to any project): "
+                "These milestones should be assigned to a project or deleted"
+            )
+            logger.warning(
+                "health_check_orphaned_milestones", count=count, severity="operational"
+            )
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.debug("health_check_orphaned_milestones_failed", error=str(e))
+            return HealthStatus.HEALTHY, "Could not check for orphaned milestones"

roadmap/core/utils/git_remote_parser.py

@@ -0,0 +1,83 @@
+"""Utility for parsing GitHub information from git remote URLs."""
+
+import re
+import subprocess
+from pathlib import Path
+
+from structlog import get_logger
+
+logger = get_logger()
+
+
+def parse_github_remote(remote_url: str | None) -> tuple[str | None, str | None]:
+    """Parse GitHub owner and repo from a git remote URL.
+
+    Supports both SSH and HTTPS formats:
+    - git@github.com:owner/repo.git
+    - https://github.com/owner/repo.git
+    - https://github.com/owner/repo
+
+    Args:
+        remote_url: Git remote URL string or None
+
+    Returns:
+        Tuple of (owner, repo) or (None, None) if not a valid GitHub URL
+    """
+    if not remote_url or "github.com" not in remote_url:
+        return None, None
+
+    # Match SSH format: git@github.com:owner/repo.git
+    ssh_match = re.search(r"github\.com:([^/]+)/([^/.]+)", remote_url)
+    if ssh_match:
+        owner = ssh_match.group(1)
+        repo = ssh_match.group(2)
+        return owner, repo
+
+    # Match HTTPS format: https://github.com/owner/repo.git or https://github.com/owner/repo
+    https_match = re.search(r"github\.com/([^/]+)/([^/.]+)", remote_url)
+    if https_match:
+        owner = https_match.group(1)
+        repo = https_match.group(2)
+        return owner, repo
+
+    return None, None
+
+
+def get_github_from_git_remote(
+    repo_path: Path | None = None,
+) -> tuple[str | None, str | None]:
+    """Auto-detect GitHub owner and repo from git remote origin.
+
+    Args:
+        repo_path: Path to git repository (defaults to current directory)
+
+    Returns:
+        Tuple of (owner, repo) or (None, None) if not detected
+    """
+    try:
+        cwd = str(repo_path) if repo_path else None
+        result = subprocess.run(
+            ["git", "config", "--get", "remote.origin.url"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            cwd=cwd,
+        )
+
+        if result.returncode == 0 and result.stdout.strip():
+            remote_url = result.stdout.strip()
+            owner, repo = parse_github_remote(remote_url)
+
+            if owner and repo:
+                logger.info(
+                    "github_detected_from_remote",
+                    owner=owner,
+                    repo=repo,
+                    remote_url=remote_url,
+                )
+                return owner, repo
+
+    except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+        logger.debug("git_remote_detection_failed", error=str(e))
+
+    return None, None

roadmap/core/utils/github_urls.py

@@ -0,0 +1,66 @@
+"""Utilities for generating GitHub URLs on-demand."""
+
+
+def get_issue_url(owner: str, repo: str, issue_number: int | str) -> str:
+    """Generate a GitHub issue URL.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        issue_number: Issue number
+
+    Returns:
+        Full GitHub issue URL
+    """
+    issue_num = int(issue_number) if isinstance(issue_number, str) else issue_number
+    return f"https://github.com/{owner}/{repo}/issues/{issue_num}"
+
+
+def get_milestone_url(owner: str, repo: str, milestone_number: int | str) -> str:
+    """Generate a GitHub milestone URL.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+        milestone_number: Milestone number
+
+    Returns:
+        Full GitHub milestone URL
+    """
+    milestone_num = (
+        int(milestone_number) if isinstance(milestone_number, str) else milestone_number
+    )
+    return f"https://github.com/{owner}/{repo}/milestone/{milestone_num}"
+
+
+def get_repo_url(owner: str, repo: str) -> str:
+    """Generate a GitHub repository URL.
+
+    Args:
+        owner: Repository owner
+        repo: Repository name
+
+    Returns:
+        Full GitHub repository URL
+    """
+    return f"https://github.com/{owner}/{repo}"
+
+
+def parse_github_number(url: str) -> int | None:
+    """Extract issue/milestone number from a GitHub URL.
+
+    Args:
+        url: GitHub URL (e.g., https://github.com/owner/repo/issues/123)
+
+    Returns:
+        Issue/milestone number, or None if not found
+    """
+    try:
+        # Try to extract number from URL
+        parts = url.rstrip("/").split("/")
+        if parts:
+            last_part = parts[-1]
+            return int(last_part)
+    except (ValueError, IndexError):
+        pass
+    return None

roadmap/domain/validation.py

@@ -0,0 +1,30 @@
+"""Validation utilities for roadmap domain logic."""
+
+from pathlib import Path
+from typing import Any
+
+from roadmap.core.services.validators import (
+    DataIntegrityValidator,
+    DuplicateIssuesValidator,
+    FolderStructureValidator,
+)
+
+# Example utility: validate folder structure
+
+
+def validate_folder_structure(issues_dir: Path, core: Any) -> dict:
+    """Validate folder structure and return issues found."""
+    return FolderStructureValidator.scan_for_folder_structure_issues(issues_dir, core)
+
+
+def find_duplicate_issues(issues_dir: Path) -> dict:
+    """Find duplicate issues by issue ID."""
+    return DuplicateIssuesValidator.scan_for_duplicate_issues(issues_dir)
+
+
+def find_malformed_issue_files(issues_dir: Path) -> dict:
+    """Find malformed issue files (unparseable YAML, etc)."""
+    return DataIntegrityValidator.scan_for_data_integrity_issues(issues_dir)
+
+
+# Add more validation utilities as needed

roadmap/infrastructure/__init__.py

@@ -0,0 +1,55 @@
+"""Infrastructure layer - Coordination, operations, and cross-domain concerns.
+
+This module is organized by concern:
+- coordination/: RoadmapCore, domain coordinators, and operations
+- git/: Git integration and branch linking
+- observability/: Health checks and monitoring
+- validation/: Data validation and GitHub integration
+- security/: Credential management and security concerns
+- maintenance/: Cleanup and maintenance operations
+
+Re-exports common items for backward compatibility.
+"""
+
+# Re-export from coordination for backward compatibility
+from roadmap.infrastructure.coordination.core import RoadmapCore
+from roadmap.infrastructure.coordination.git_coordinator import GitCoordinator
+from roadmap.infrastructure.coordination.initialization import InitializationManager
+from roadmap.infrastructure.coordination.issue_coordinator import IssueCoordinator
+from roadmap.infrastructure.coordination.issue_operations import IssueOperations
+from roadmap.infrastructure.coordination.milestone_coordinator import (
+    MilestoneCoordinator,
+)
+from roadmap.infrastructure.coordination.milestone_operations import MilestoneOperations
+from roadmap.infrastructure.coordination.project_coordinator import ProjectCoordinator
+from roadmap.infrastructure.coordination.project_operations import ProjectOperations
+from roadmap.infrastructure.coordination.team_coordinator import TeamCoordinator
+from roadmap.infrastructure.coordination.user_operations import UserOperations
+from roadmap.infrastructure.coordination.validation_coordinator import (
+    ValidationCoordinator,
+)
+
+# Re-export from git for backward compatibility
+from roadmap.infrastructure.git.git_integration_ops import GitIntegrationOps
+
+# Re-export from observability for backward compatibility
+from roadmap.infrastructure.observability.health import HealthCheck
+from roadmap.infrastructure.observability.health_formatter import HealthStatusFormatter
+
+__all__ = [
+    "RoadmapCore",
+    "GitCoordinator",
+    "InitializationManager",
+    "IssueCoordinator",
+    "IssueOperations",
+    "MilestoneCoordinator",
+    "MilestoneOperations",
+    "ProjectCoordinator",
+    "ProjectOperations",
+    "TeamCoordinator",
+    "UserOperations",
+    "ValidationCoordinator",
+    "GitIntegrationOps",
+    "HealthCheck",
+    "HealthStatusFormatter",
+]

roadmap/infrastructure/coordination/__init__.py

@@ -0,0 +1,8 @@
+"""Coordination layer - Orchestrates domain operations.
+
+This module contains:
+- RoadmapCore: Main facade and service container
+- Domain coordinators: Issue, Milestone, Project, Team, Git, Validation
+- Operations: Concrete implementations of domain operations
+- Initialization: Setup and configuration management
+"""

roadmap/infrastructure/coordination/coordinator_params.py

@@ -0,0 +1,82 @@
+"""Coordinator layer parameter dataclasses.
+
+Consolidates coordinator method parameters into well-structured dataclasses
+for improved API consistency and reduced parameter passing complexity.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from roadmap.core.domain import IssueType, Priority
+
+
+@dataclass
+class IssueCreateParams:
+    """Parameters for creating a new issue through IssueCoordinator."""
+
+    title: str
+    priority: Priority = Priority.MEDIUM
+    issue_type: IssueType = IssueType.OTHER
+    milestone: str | None = None
+    labels: list[str] | None = None
+    assignee: str | None = None
+    estimated_hours: float | None = None
+    depends_on: list[str] | None = None
+    blocks: list[str] | None = None
+
+
+@dataclass
+class IssueListParams:
+    """Parameters for listing issues through IssueCoordinator."""
+
+    milestone: str | None = None
+    status: str | None = None
+    priority: Priority | None = None
+    issue_type: IssueType | None = None
+    assignee: str | None = None
+
+
+@dataclass
+class IssueUpdateParams:
+    """Parameters for updating an issue through IssueCoordinator."""
+
+    issue_id: str
+    updates: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MilestoneCreateParams:
+    """Parameters for creating a new milestone through MilestoneCoordinator."""
+
+    name: str
+    content: str = ""
+    due_date: datetime | None = None
+
+
+@dataclass
+class MilestoneUpdateParams:
+    """Parameters for updating a milestone through MilestoneCoordinator."""
+
+    name: str
+    content: str | None = None
+    due_date: datetime | None = None
+    clear_due_date: bool = False
+    status: str | None = None
+
+
+@dataclass
+class ProjectCreateParams:
+    """Parameters for creating a new project through ProjectCoordinator."""
+
+    name: str
+    content: str = ""
+    milestones: list[str] | None = None
+
+
+@dataclass
+class ProjectUpdateParams:
+    """Parameters for updating a project through ProjectCoordinator."""
+
+    project_id: str
+    updates: dict[str, Any] = field(default_factory=dict)