roadmap-cli 0.1.1__py3-none-any.whl

roadmap/core/services/health/entity_health_scanner.py

@@ -0,0 +1,460 @@
+"""Entity-level health scanning service.
+
+Provides detailed diagnostics on individual entities (Issues, Milestones, Projects)
+including validation of descriptions, comments, dependencies, and other metadata.
+"""
+
+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.domain.milestone import Milestone
+from roadmap.core.domain.project import Project
+
+# Re-export shared models for backward compatibility
+from roadmap.core.services.health.health_models import (
+    EntityHealthReport,
+    EntityType,
+    HealthIssue,
+    HealthSeverity,
+)
+from roadmap.core.services.health.issue_health_scanner import IssueHealthScanner
+
+logger = get_logger(__name__)
+
+
+class EntityHealthScanner:
+    """Scans entities for health issues.
+
+    Checks for:
+    - Missing or empty descriptions
+    - Malformed or empty comments
+    - Circular dependencies
+    - Broken dependencies (referencing non-existent entities)
+    - Missing estimates (when required by milestone)
+    - Due date issues (overdue, unrealistic)
+    - Assignee issues (unassigned when expected, previous_assignee mismatch)
+    - Progress tracking issues (inconsistent progress state)
+    """
+
+    def __init__(self, core: Any = None):
+        """Initialize the scanner.
+
+        Args:
+            core: Optional Core object with access to entities. If not provided,
+                  the scanner can still work on individual entities passed to methods.
+        """
+        self.core = core
+        self._entity_cache: dict[str, Any] = {}  # Cache of entity_id -> entity
+
+    @traced("scan_issue")
+    def scan_issue(self, issue: Issue) -> EntityHealthReport:
+        """Delegate issue scanning to the extracted `IssueHealthScanner`.
+
+        This keeps the original public API while the implementation lives in
+        `issue_health_scanner.IssueHealthScanner` for easier maintenance.
+        """
+        scanner = IssueHealthScanner(core=self.core)
+        return scanner.scan_issue(issue)
+
+    @traced("scan_milestone")
+    def scan_milestone(self, milestone: Milestone) -> EntityHealthReport:
+        """Scan a single milestone for health problems.
+
+        Args:
+            milestone: The milestone to scan
+
+        Returns:
+            EntityHealthReport with all issues found
+        """
+        report = EntityHealthReport(
+            entity_id=milestone.name,
+            entity_type=EntityType.MILESTONE,
+            entity_title=milestone.name,
+            status=milestone.status.value if milestone.status else "unknown",
+        )
+
+        # Check description/content
+        if not milestone.content or not milestone.content.strip():
+            report.issues.append(
+                HealthIssue(
+                    code="missing_content",
+                    message="Milestone has no content",
+                    severity=HealthSeverity.WARNING,
+                    category="content",
+                )
+            )
+
+        # Check dates
+        if milestone.created and milestone.due_date:
+            if milestone.created > milestone.due_date:
+                report.issues.append(
+                    HealthIssue(
+                        code="invalid_date_range",
+                        message=f"Created date ({milestone.created.date()}) is after due date ({milestone.due_date.date()})",
+                        severity=HealthSeverity.ERROR,
+                        category="structure",
+                        details={
+                            "created_date": milestone.created.isoformat(),
+                            "due_date": milestone.due_date.isoformat(),
+                        },
+                    )
+                )
+
+        # Check progress
+        if (
+            milestone.calculated_progress is not None
+            and milestone.status == Status.CLOSED
+        ):
+            if milestone.calculated_progress != 100:
+                report.issues.append(
+                    HealthIssue(
+                        code="inconsistent_completion",
+                        message=f"Milestone marked Done but only {milestone.calculated_progress}% complete",
+                        severity=HealthSeverity.WARNING,
+                        category="structure",
+                        details={"calculated_progress": milestone.calculated_progress},
+                    )
+                )
+
+        return report
+
+    @traced("scan_project")
+    def scan_project(self, project: Project) -> EntityHealthReport:
+        """Scan a single project for health problems.
+
+        Args:
+            project: The project to scan
+
+        Returns:
+            EntityHealthReport with all issues found
+        """
+        report = EntityHealthReport(
+            entity_id=project.id,
+            entity_type=EntityType.PROJECT,
+            entity_title=project.name,
+            status=project.status.value if project.status else "unknown",
+        )
+
+        # Check description/content
+        if not project.content or not project.content.strip():
+            report.issues.append(
+                HealthIssue(
+                    code="missing_content",
+                    message="Project has no content",
+                    severity=HealthSeverity.WARNING,
+                    category="content",
+                )
+            )
+
+        # Check owner
+        if not project.owner or not project.owner.strip():
+            report.issues.append(
+                HealthIssue(
+                    code="missing_owner",
+                    message="Project has no owner assigned",
+                    severity=HealthSeverity.WARNING,
+                    category="structure",
+                )
+            )
+
+        return report
+
+    def scan_all(self) -> list[EntityHealthReport]:
+        """Scan all issues, milestones, and projects.
+
+        Requires core to be initialized.
+
+        Returns:
+            List of EntityHealthReport objects for all entities
+
+        Raises:
+            RuntimeError: If core is not initialized
+        """
+        if not self.core:
+            raise RuntimeError(
+                "Core must be initialized to scan all entities. "
+                "Pass core to constructor or call scan_issue/milestone/project directly."
+            )
+
+        reports = []
+
+        # Scan all issues
+        try:
+            all_issues = self._list_entities("issues", "issue_repository")
+            for issue in all_issues:
+                reports.append(self.scan_issue(issue))
+        except Exception as e:
+            logger.error("error_scanning_issues", error=str(e), severity="system_error")
+
+        # Scan all milestones
+        try:
+            all_milestones = self._list_entities("milestones", "milestone_repository")
+            for milestone in all_milestones:
+                reports.append(self.scan_milestone(milestone))
+        except Exception as e:
+            logger.error(
+                "error_scanning_milestones", error=str(e), severity="system_error"
+            )
+
+        # Scan all projects
+        try:
+            all_projects = self._list_entities("projects", "project_repository")
+            for project in all_projects:
+                reports.append(self.scan_project(project))
+        except Exception as e:
+            logger.error(
+                "error_scanning_projects", error=str(e), severity="system_error"
+            )
+
+        return reports
+
+    def _list_entities(self, coordinator_attr: str, repository_attr: str) -> list[Any]:
+        """List entities using coordinator API first, with legacy fallback.
+
+        Args:
+            coordinator_attr: Coordinator attribute name on core (e.g., "issues")
+            repository_attr: Legacy repository attribute name on core
+
+        Returns:
+            List of entities
+
+        Raises:
+            AttributeError: If neither API is available
+        """
+        coordinator = getattr(self.core, coordinator_attr, None)
+        if coordinator is not None and hasattr(coordinator, "list"):
+            return coordinator.list()
+
+        repository = getattr(self.core, repository_attr, None)
+        if repository is not None and hasattr(repository, "list"):
+            return repository.list()
+
+        raise AttributeError(
+            f"Core has neither '{coordinator_attr}.list()' nor '{repository_attr}.list()'"
+        )
+
+    # Private methods for individual checks
+
+    def _check_issue_description(self, issue: Issue, report: EntityHealthReport):
+        """Check issue description/content."""
+        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):
+        """Check issue comments for problems."""
+        if not issue.comments:
+            return
+
+        errors = self._validate_comment_thread(issue.comments)
+        for error_msg in errors:
+            # Parse error message to determine severity and code
+            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):
+        """Check issue estimation."""
+        # Only warn about missing estimates for in-progress or done issues
+        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):
+        """Check issue date consistency."""
+        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):
+        """Check issue assignee consistency."""
+        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):
+        """Check issue progress tracking."""
+        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},
+                    )
+                )
+
+        # Check progress vs status consistency
+        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):
+        """Check overall status consistency."""
+        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]:
+        """Validate comment threads for errors.
+
+        Returns list of error messages found.
+        """
+        errors = []
+        comment_ids = set()
+
+        for comment in comments:
+            # Check for duplicate IDs
+            if comment.id in comment_ids:
+                errors.append(f"Duplicate comment ID: {comment.id}")
+            comment_ids.add(comment.id)
+
+            # Check for empty body
+            if not comment.body or not comment.body.strip():
+                errors.append(f"Comment {comment.id}: Empty comment body")
+
+            # Check for empty author
+            if not comment.author or not comment.author.strip():
+                errors.append(f"Comment {comment.id}: Missing comment author")
+
+            # Check for invalid datetime fields
+            if not isinstance(comment.created_at, type(comment.created_at)):
+                errors.append(
+                    f"Comment {comment.id}: created_at is not a valid datetime"
+                )
+
+        # Check for circular references in reply chains
+        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)
+                    # Find the comment this replies to
+                    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/health/file_repair_service.py

@@ -0,0 +1,193 @@
+"""Service for repairing malformed YAML in issue files."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+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
+
+logger = get_logger(__name__)
+
+
+class FileRepairResult:
+    """Result of file repair operation."""
+
+    def __init__(self):
+        """Initialize FileRepairResult."""
+        self.fixed_files: list[str] = []
+        self.errors: list[str] = []
+
+    def add_fixed(self, file_rel: str) -> None:
+        """Record a fixed file."""
+        self.fixed_files.append(file_rel)
+
+    def add_error(self, file_rel: str) -> None:
+        """Record a file that couldn't be fixed."""
+        self.errors.append(file_rel)
+
+
+class FileRepairService:
+    """Repairs common malformed YAML issues in issue files."""
+
+    @traced("repair_files")
+    def repair_files(
+        self, issues_dir: Path, malformed_files: list[str], dry_run: bool = False
+    ) -> FileRepairResult:
+        """Fix common malformed YAML issues in issue files.
+
+        Args:
+            issues_dir: Directory containing issue files
+            malformed_files: List of relative paths to malformed files
+            dry_run: If True, don't write changes to disk
+
+        Returns:
+            FileRepairResult with fixed_files and errors lists
+        """
+        result = FileRepairResult()
+
+        for file_rel in malformed_files:
+            file_path = issues_dir / file_rel
+
+            try:
+                content = file_path.read_text(encoding="utf-8")
+
+                # Extract frontmatter
+                if not content.startswith("---"):
+                    result.add_error(file_rel)
+                    continue
+
+                parts = content.split("---", 2)
+                if len(parts) < 3:
+                    result.add_error(file_rel)
+                    continue
+
+                frontmatter_str, markdown_content = parts[1], parts[2]
+
+                # Parse and fix common issues
+                try:
+                    frontmatter = yaml.safe_load(frontmatter_str)
+                    if not isinstance(frontmatter, dict):
+                        result.add_error(file_rel)
+                        continue
+                except yaml.YAMLError:
+                    result.add_error(file_rel)
+                    continue
+
+                # Fix git_commits and git_branches
+                self._normalize_git_data(frontmatter)
+
+                # Reconstruct the file
+                fixed_frontmatter = yaml.dump(
+                    frontmatter, default_flow_style=False, sort_keys=False
+                )
+                fixed_content = f"---\n{fixed_frontmatter}---\n{markdown_content}"
+
+                if not dry_run:
+                    try:
+                        file_path.write_text(fixed_content, encoding="utf-8")
+                    except Exception as write_error:
+                        log_error_with_context(
+                            write_error,
+                            operation="write_repaired_file",
+                            entity_type="File",
+                            entity_id=file_rel,
+                        )
+                        result.add_error(file_rel)
+                        logger.warning(
+                            "Failed to write repaired file",
+                            file=file_rel,
+                            error=str(write_error),
+                            severity="operational",
+                        )
+                        continue
+
+                result.add_fixed(file_rel)
+                logger.info("Fixed malformed file", file=file_rel)
+
+            except Exception as e:
+                log_error_with_context(
+                    e,
+                    operation="repair_file",
+                    entity_type="File",
+                    entity_id=file_rel,
+                )
+                result.add_error(file_rel)
+                logger.warning(
+                    "Failed to fix file",
+                    file=file_rel,
+                    error=str(e),
+                    severity="operational",
+                )
+
+        return result
+
+    @staticmethod
+    @staticmethod
+    def _fix_git_commits(frontmatter: dict[str, Any]) -> None:
+        """Fix git_commits list format.
+
+        Converts list of strings to list of dicts with 'hash' key.
+
+        Args:
+            frontmatter: Frontmatter dict to fix
+        """
+        if "git_commits" not in frontmatter or not isinstance(
+            frontmatter["git_commits"], list
+        ):
+            return
+
+        fixed_commits = []
+        for commit in frontmatter["git_commits"]:
+            if isinstance(commit, str):
+                # Convert string commit hash to dict
+                fixed_commits.append({"hash": commit})
+            else:
+                fixed_commits.append(commit)
+        frontmatter["git_commits"] = fixed_commits
+
+    @staticmethod
+    def _fix_git_branches(frontmatter: dict[str, Any]) -> None:
+        """Fix git_branches list format.
+
+        Converts list of dicts to list of strings.
+
+        Args:
+            frontmatter: Frontmatter dict to fix
+        """
+        if "git_branches" not in frontmatter or not isinstance(
+            frontmatter["git_branches"], list
+        ):
+            return
+
+        fixed_branches = []
+        for branch in frontmatter["git_branches"]:
+            if isinstance(branch, dict):
+                # Convert dict to string - prefer 'name' field
+                if "name" in branch:
+                    fixed_branches.append(branch["name"])
+                elif isinstance(branch, str):
+                    fixed_branches.append(branch)
+                else:
+                    fixed_branches.append(str(branch))
+            elif isinstance(branch, str):
+                fixed_branches.append(branch)
+            else:
+                # Convert any other type to string
+                fixed_branches.append(str(branch))
+        frontmatter["git_branches"] = fixed_branches
+
+    @staticmethod
+    def _normalize_git_data(frontmatter: dict[str, Any]) -> None:
+        """Normalize git_commits and git_branches in frontmatter.
+
+        Fixes:
+        - git_commits: list of strings → list of dicts with 'hash' key
+        - git_branches: list of dicts → list of strings
+        """
+        FileRepairService._fix_git_commits(frontmatter)
+        FileRepairService._fix_git_branches(frontmatter)