roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/validators/duplicate_issues_validator.py

@@ -0,0 +1,75 @@
+"""Validator for duplicate issues."""
+
+from collections import defaultdict
+from pathlib import Path
+
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+
+from . import extract_issue_id
+
+
+class DuplicateIssuesValidator(BaseValidator):
+    """Validator for duplicate issues."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the duplicate_issues check.
+        """
+        return "duplicate_issues"
+
+    @staticmethod
+    def scan_for_duplicate_issues(issues_dir: Path) -> dict[str, list[Path]]:
+        """Scan all issue files and identify duplicates by issue ID.
+
+        Returns a dict mapping issue_id -> list of file paths where duplicates exist (2+ occurrences).
+        """
+        issues_by_id = defaultdict(list)
+
+        # Scan all issue markdown files recursively
+        for issue_file in issues_dir.glob("**/*.md"):
+            # Skip backup files
+            if ".backup" in issue_file.name:
+                continue
+
+            issue_id = extract_issue_id(issue_file.name)
+            if issue_id:
+                issues_by_id[issue_id].append(issue_file)
+
+        # Return only duplicates (2+ occurrences)
+        duplicates = {
+            issue_id: files
+            for issue_id, files in issues_by_id.items()
+            if len(files) > 1
+        }
+
+        return duplicates
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check for duplicate issues.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        issues_dir = Path(".roadmap/issues")
+        if not issues_dir.exists():
+            return (
+                HealthStatus.HEALTHY,
+                "Issues directory not found (not initialized yet)",
+            )
+
+        duplicates = DuplicateIssuesValidator.scan_for_duplicate_issues(issues_dir)
+
+        if not duplicates:
+            return HealthStatus.HEALTHY, "No duplicate issues found"
+
+        total_duplicates = sum(len(files) - 1 for files in duplicates.values())
+        message = (
+            f"⚠️ {len(duplicates)} issue ID(s) have duplicates "
+            f"({total_duplicates} duplicate files total): "
+            "Manual cleanup required"
+        )
+        return HealthStatus.DEGRADED, message

roadmap/core/services/validators/duplicate_milestones_validator.py

@@ -0,0 +1,141 @@
+"""Validator for duplicate milestones."""
+
+from collections import defaultdict
+from pathlib import Path
+
+import structlog
+
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+from roadmap.infrastructure.coordination.core import RoadmapCore
+
+logger = structlog.get_logger()
+
+
+class DuplicateMilestonesValidator(BaseValidator):
+    """Validator for duplicate milestones (by name and file)."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the duplicate_milestones check.
+        """
+        return "duplicate_milestones"
+
+    @staticmethod
+    def scan_for_duplicate_files(milestones_dir: Path) -> dict[str, list[Path]]:
+        """Scan all milestone files and identify duplicates by milestone name.
+
+        Returns a dict mapping milestone_name -> list of file paths where duplicates exist (2+ occurrences).
+        """
+        milestones_by_name = defaultdict(list)
+
+        # Scan all milestone markdown files
+        for milestone_file in milestones_dir.glob("*.md"):
+            # Skip backup files
+            if ".backup" in milestone_file.name:
+                continue
+
+            # Extract milestone name from filename (remove .md extension)
+            milestone_name = milestone_file.stem
+            milestones_by_name[milestone_name].append(milestone_file)
+
+        # Return only duplicates (2+ occurrences)
+        duplicates = {
+            name: files for name, files in milestones_by_name.items() if len(files) > 1
+        }
+
+        return duplicates
+
+    @staticmethod
+    def scan_for_duplicate_names(core) -> list[dict]:
+        """Scan for duplicate milestone names in the database.
+
+        Returns a list of duplicate milestone names with count.
+        """
+        duplicates = []
+
+        try:
+            all_milestones = core.milestones.list()
+
+            # Count occurrences of each name
+            name_counts = {}
+            for milestone in all_milestones:
+                name_counts[milestone.name] = name_counts.get(milestone.name, 0) + 1
+
+            # Find duplicates
+            for name, count in name_counts.items():
+                if count > 1:
+                    duplicates.append(
+                        {
+                            "name": name,
+                            "count": count,
+                        }
+                    )
+
+        except Exception as e:
+            logger.debug(
+                "scan_duplicate_names_failed",
+                operation="scan_for_duplicate_names",
+                error=str(e),
+                action="Returning empty duplicates",
+            )
+
+        return duplicates
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check for duplicate milestones (both file and name duplicates).
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        try:
+            milestones_dir = Path(".roadmap/milestones")
+            if not milestones_dir.exists():
+                return (
+                    HealthStatus.HEALTHY,
+                    "Milestones directory not found (not initialized yet)",
+                )
+
+            # Check for file duplicates
+            file_duplicates = DuplicateMilestonesValidator.scan_for_duplicate_files(
+                milestones_dir
+            )
+
+            # Check for name duplicates in database
+            core = RoadmapCore()
+            name_duplicates = DuplicateMilestonesValidator.scan_for_duplicate_names(
+                core
+            )
+
+            issues = []
+            if file_duplicates:
+                total_file_duplicates = sum(
+                    len(files) - 1 for files in file_duplicates.values()
+                )
+                issues.append(
+                    f"{len(file_duplicates)} milestone name(s) have duplicate files "
+                    f"({total_file_duplicates} duplicate files total)"
+                )
+
+            if name_duplicates:
+                issues.append(
+                    f"{len(name_duplicates)} milestone name(s) appear multiple times in database"
+                )
+
+            if not issues:
+                return HealthStatus.HEALTHY, "No duplicate milestones found"
+
+            message = f"⚠️ {'; '.join(issues)}: Manual cleanup required"
+            return HealthStatus.DEGRADED, message
+
+        except Exception as e:
+            logger.debug(
+                "duplicate_milestones_check_failed",
+                operation="perform_check",
+                error=str(e),
+                action="Returning healthy status",
+            )
+            return HealthStatus.HEALTHY, "Could not check for duplicate milestones"

roadmap/core/services/validators/folder_structure_validator.py

@@ -0,0 +1,165 @@
+"""Validator for folder structure and issue placement."""
+
+from pathlib import Path
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+
+from . import extract_issue_id
+
+logger = get_logger(__name__)
+
+
+class FolderStructureValidator(BaseValidator):
+    """Validator for folder structure and issue placement."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the folder_structure check.
+        """
+        return "folder_structure"
+
+    @staticmethod
+    def _check_root_issues(issues_dir: Path, core, misplaced_list: list) -> None:
+        """Check root level issues for milestone placement issues."""
+        for issue_file in issues_dir.glob("*.md"):
+            if ".backup" in issue_file.name:
+                continue
+
+            try:
+                issue_id = extract_issue_id(issue_file.name)
+                if not issue_id:
+                    continue
+
+                issue = core.issue_service.get_issue(issue_id)
+                if issue and issue.milestone:
+                    milestone_folder = issues_dir / issue.milestone
+                    if milestone_folder.exists():
+                        misplaced_list.append(
+                            {
+                                "issue_id": issue.id,
+                                "title": issue.title,
+                                "current_location": str(issue_file),
+                                "assigned_milestone": issue.milestone,
+                                "expected_location": str(
+                                    milestone_folder / issue_file.name
+                                ),
+                            }
+                        )
+            except Exception as e:
+                logger.debug(
+                    "issue_parse_failed",
+                    operation="parse_issue",
+                    file=str(issue_file),
+                    error=str(e),
+                    action="Skipping issue",
+                )
+
+    @staticmethod
+    def _process_milestone_file(
+        issue_file: Path, core, milestone_folder: Path, orphaned_list: list
+    ) -> None:
+        """Process single file in milestone folder for orphaned issues.
+
+        Args:
+            issue_file: File to process
+            core: RoadmapCore instance
+            milestone_folder: Milestone folder path
+            orphaned_list: List to append orphaned issues to
+        """
+        if ".backup" in issue_file.name:
+            return
+
+        try:
+            issue_id = extract_issue_id(issue_file.name)
+            if not issue_id:
+                return
+
+            issue = core.issue_service.get_issue(issue_id)
+            if issue and not issue.milestone:
+                orphaned_list.append(
+                    {
+                        "issue_id": issue.id,
+                        "title": issue.title,
+                        "location": str(issue_file),
+                        "folder": milestone_folder.name,
+                    }
+                )
+        except Exception as e:
+            logger.debug(
+                "milestone_folder_check_failed",
+                operation="check_milestone_folders",
+                error=str(e),
+                action="Continuing to next folder",
+            )
+
+    @staticmethod
+    def _check_milestone_folders(issues_dir: Path, core, orphaned_list: list) -> None:
+        """Check milestone folders for orphaned issues."""
+        for milestone_folder in issues_dir.glob("*/"):
+            if not milestone_folder.is_dir() or milestone_folder.name.startswith("."):
+                continue
+
+            if milestone_folder.name == "backlog":
+                continue
+
+            for issue_file in milestone_folder.glob("*.md"):
+                FolderStructureValidator._process_milestone_file(
+                    issue_file, core, milestone_folder, orphaned_list
+                )
+
+    @staticmethod
+    def scan_for_folder_structure_issues(
+        issues_dir: Path, core
+    ) -> dict[str, list[dict]]:
+        """Verify issues are in correct milestone folders.
+
+        Returns a dict of potential issues:
+        - 'misplaced': Issues in root when they belong in a milestone subfolder
+        - 'orphaned': Issues with milestone assignments but not in milestone folder
+        """
+        misplaced = []
+        orphaned = []
+
+        try:
+            FolderStructureValidator._check_root_issues(issues_dir, core, misplaced)
+            FolderStructureValidator._check_milestone_folders(
+                issues_dir, core, orphaned
+            )
+        except Exception as e:
+            logger.error(
+                "folder_structure_check_failed", error=str(e), severity="system_error"
+            )
+
+        return (
+            {
+                "misplaced": misplaced,
+                "orphaned": orphaned,
+            }
+            if (misplaced or orphaned)
+            else {}
+        )
+
+    @staticmethod
+    def perform_check() -> tuple[str, str]:
+        """Check folder structure and issue placement.
+
+        Note: This validator requires core access but is called without it.
+        For now, return HEALTHY to avoid blocking health checks.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        issues_dir = Path(".roadmap/issues")
+        if not issues_dir.exists():
+            return (
+                HealthStatus.HEALTHY,
+                "Issues directory not found (not initialized yet)",
+            )
+
+        # Simplified check without core access for now
+        # Full check requires core.issue_service which we don't have in this context
+        return HealthStatus.HEALTHY, "Folder structure check (simplified)"

roadmap/core/services/validators/health_status_utils.py

@@ -0,0 +1,28 @@
+"""Health status utilities for validators.
+
+Common utilities for determining overall health status from individual checks.
+"""
+
+from roadmap.core.services.validator_base import HealthStatus
+
+
+def get_overall_status(checks: dict) -> str:
+    """Get overall status from all validation checks.
+
+    Args:
+        checks: Dictionary of check results with (status, message) tuples
+
+    Returns:
+        Overall status: 'healthy', 'degraded', or 'unhealthy'
+    """
+    if not checks:
+        return HealthStatus.UNHEALTHY
+
+    statuses = [status for status, _ in checks.values()]
+
+    if HealthStatus.UNHEALTHY in statuses:
+        return HealthStatus.UNHEALTHY
+    elif HealthStatus.DEGRADED in statuses:
+        return HealthStatus.DEGRADED
+    else:
+        return HealthStatus.HEALTHY

roadmap/core/services/validators/milestone_naming_validator.py

@@ -0,0 +1,146 @@
+"""Validator for milestone naming conventions."""
+
+import re
+from pathlib import Path
+
+
+class MilestoneNamingValidator:
+    """Validates milestone names against naming conventions.
+
+    Convention:
+    - Display names should match safe filenames (no conversion needed)
+    - Allowed characters: alphanumeric, hyphens, underscores
+    - Must start with alphanumeric
+    - Recommended patterns:
+      - Versions: v0-7-0, v0-8-0, v1-0-0 (hyphens, unambiguous)
+      - Sprints: sprint-1, sprint-q1-2025
+      - Phases: phase-1, phase-beta
+      - Releases: release-dec-2025, release-2025-q1
+      - Backlog: backlog
+    """
+
+    # Pattern: alphanumeric, hyphens, underscores. Can contain dots only in version pattern
+    # Examples: v0-7-0, sprint-1, phase-beta, backlog
+    # Note: v070, v080, v100 are deprecated due to ambiguity (v100 = v1.0.0 or v10.0?)
+    VALID_PATTERN = re.compile(
+        r"^[a-zA-Z0-9][a-zA-Z0-9._\-]*[a-zA-Z0-9]$|^[a-zA-Z0-9]$"
+    )
+
+    @staticmethod
+    def is_valid_name(name: str) -> bool:
+        """Check if a milestone name is valid.
+
+        Args:
+            name: The milestone name to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        if not name or len(name) == 0:
+            return False
+
+        # Must match pattern
+        if not MilestoneNamingValidator.VALID_PATTERN.match(name):
+            return False
+
+        # Should not have consecutive hyphens or underscores
+        if "--" in name or "__" in name:
+            return False
+
+        return True
+
+    @staticmethod
+    def get_safe_name(name: str) -> str:
+        """Convert a milestone name to safe filename format.
+
+        Args:
+            name: The milestone name
+
+        Returns:
+            Safe filename version (lowercase, spaces→hyphens, etc.)
+        """
+        # Remove/replace invalid chars
+        safe = "".join(c for c in name if c.isalnum() or c in (".", "-", "_")).strip()
+
+        # Replace spaces with hyphens
+        safe = safe.replace(" ", "-")
+
+        # Lowercase
+        safe = safe.lower()
+
+        return safe
+
+    @staticmethod
+    def validate_with_feedback(name: str) -> tuple[bool, str | None]:
+        """Validate a name and provide feedback.
+
+        Args:
+            name: The milestone name to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+            If valid, error_message is None
+        """
+        if not name:
+            return False, "Milestone name cannot be empty"
+
+        if len(name) > 100:
+            return False, "Milestone name must be 100 characters or less"
+
+        if not MilestoneNamingValidator.VALID_PATTERN.match(name):
+            return False, (
+                "Milestone name must contain only alphanumeric characters, "
+                "hyphens, underscores, and dots. "
+                f"Got: '{name}'. "
+                "Examples: v0-7-0, v1-0-0, sprint-1, phase-beta, backlog"
+            )
+
+        if "--" in name or "__" in name:
+            return (
+                False,
+                "Milestone name cannot contain consecutive hyphens or underscores",
+            )
+
+        # Warn if safe name differs from display name (lossy conversion)
+        safe = MilestoneNamingValidator.get_safe_name(name)
+        if safe != name:
+            return False, (
+                f"Milestone name will be converted to '{safe}' for filesystem. "
+                "To avoid confusion, use the filesystem name directly. "
+                f"Suggested: '{safe}'"
+            )
+
+        return True, None
+
+    @staticmethod
+    def find_naming_conflicts(milestones_dir: Path) -> list[tuple[str, str]]:
+        """Find milestone names that could create naming conflicts.
+
+        Args:
+            milestones_dir: Path to .roadmap/milestones/
+
+        Returns:
+            List of (display_name, safe_name) pairs that might conflict
+        """
+        conflicts = []
+        safe_name_to_display = {}
+
+        if not milestones_dir.exists():
+            return conflicts
+
+        for f in milestones_dir.glob("*.md"):
+            display_name = f.stem
+            safe_name = MilestoneNamingValidator.get_safe_name(display_name)
+
+            if safe_name != display_name:
+                conflicts.append((display_name, safe_name))
+
+            # Check for collision (two different display names → same safe name)
+            if safe_name in safe_name_to_display:
+                other = safe_name_to_display[safe_name]
+                if other != display_name:
+                    conflicts.append((display_name, safe_name))
+            else:
+                safe_name_to_display[safe_name] = display_name
+
+        return conflicts

roadmap/core/services/validators/missing_headlines_validator.py

@@ -0,0 +1,97 @@
+"""Validator for missing headlines in issues, milestones, and projects."""
+
+from roadmap.common.logging import get_logger
+from roadmap.core.services.validator_base import BaseValidator, HealthStatus
+
+logger = get_logger(__name__)
+
+
+class MissingHeadlinesValidator(BaseValidator):
+    """Validator for missing headlines in entities."""
+
+    @staticmethod
+    def get_check_name() -> str:
+        """Get the name of this check.
+
+        Returns:
+            String identifier for the missing_headlines check.
+        """
+        return "missing_headlines"
+
+    @staticmethod
+    def _collect_missing_headline_ids(list_callable, missing_list: list) -> None:
+        """Append IDs of entities with empty headlines to *missing_list*."""
+        try:
+            for entity in list_callable():
+                if not entity.headline or entity.headline.strip() == "":
+                    missing_list.append(entity.id)
+        except (AttributeError, TypeError):
+            pass
+
+    @staticmethod
+    def check_missing_headlines(core) -> tuple[str, str]:
+        """Check for entities with missing or empty headlines.
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        missing_entities: dict[str, list] = {
+            "issues": [],
+            "milestones": [],
+            "projects": [],
+        }
+
+        try:
+            MissingHeadlinesValidator._collect_missing_headline_ids(
+                core.issue_service.list_issues, missing_entities["issues"]
+            )
+            MissingHeadlinesValidator._collect_missing_headline_ids(
+                core.milestone_service.list_milestones, missing_entities["milestones"]
+            )
+            MissingHeadlinesValidator._collect_missing_headline_ids(
+                core.project_service.list_projects, missing_entities["projects"]
+            )
+        except Exception as e:
+            logger.debug("error_checking_headlines", error=str(e))
+            return (
+                HealthStatus.DEGRADED,
+                f"Error checking headlines: {str(e)}",
+            )
+
+        # Count missing headlines
+        total_missing = (
+            len(missing_entities["issues"])
+            + len(missing_entities["milestones"])
+            + len(missing_entities["projects"])
+        )
+
+        if total_missing == 0:
+            return HealthStatus.HEALTHY, "All entities have headlines"
+
+        # Build detailed message
+        parts = []
+        if missing_entities["issues"]:
+            parts.append(f"{len(missing_entities['issues'])} issue(s)")
+        if missing_entities["milestones"]:
+            parts.append(f"{len(missing_entities['milestones'])} milestone(s)")
+        if missing_entities["projects"]:
+            parts.append(f"{len(missing_entities['projects'])} project(s)")
+
+        message = (
+            f"⚠️ {total_missing} entity(ies) missing headlines: {', '.join(parts)}. "
+            "Run 'roadmap fix missing-headlines' to auto-populate from content"
+        )
+        return HealthStatus.DEGRADED, message
+
+    @staticmethod
+    def perform_check(core=None) -> tuple[str, str]:
+        """Check for missing headlines.
+
+        Args:
+            core: RoadmapCore instance (optional, for backward compatibility)
+
+        Returns:
+            Tuple of (status, message) describing the health check result
+        """
+        # For now, return healthy - actual implementation will use core
+        return HealthStatus.HEALTHY, "Headlines validation not yet fully integrated"