roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/persistence/parser/issue.py

@@ -0,0 +1,245 @@
+"""Parser for issue markdown files."""
+
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from roadmap.common.datetime_parser import parse_datetime
+from roadmap.common.utils.timezone_utils import now_utc
+from roadmap.core.domain import Issue, IssueType, Priority, Status
+
+from ..persistence import enhanced_persistence
+from .frontmatter import FrontmatterParser
+
+
+class IssueParser:
+    """Parser specifically for issue markdown files."""
+
+    @staticmethod
+    def _parse_datetime_field(frontmatter: dict, field_name: str) -> None:
+        """Parse a datetime field in frontmatter if present and string."""
+        if field_name in frontmatter and isinstance(frontmatter[field_name], str):
+            frontmatter[field_name] = parse_datetime(frontmatter[field_name], "file")
+
+    @staticmethod
+    def _parse_enum_field(
+        frontmatter: dict, field_name: str, enum_class, file_path: Path
+    ) -> None:
+        """Parse enum field with validation."""
+        if field_name not in frontmatter:
+            return
+
+        try:
+            frontmatter[field_name] = enum_class(frontmatter[field_name])
+        except ValueError as e:
+            valid_values = [v.value for v in enum_class]
+            raise ValueError(
+                f"Invalid {field_name} '{frontmatter[field_name]}' in {file_path}. "
+                f"Valid values are: {', '.join(valid_values)}"
+            ) from e
+
+    @staticmethod
+    def _ensure_list_fields(frontmatter: dict) -> None:
+        """Ensure dependency fields are lists."""
+        if "depends_on" not in frontmatter:
+            frontmatter["depends_on"] = []
+        if "blocks" not in frontmatter:
+            frontmatter["blocks"] = []
+
+    @classmethod
+    def parse_issue_file(cls, file_path: Path) -> Issue:
+        """Parse an issue markdown file and return an Issue object."""
+        frontmatter, content = FrontmatterParser.parse_file(file_path)
+
+        # Parse date fields
+        cls._parse_datetime_field(frontmatter, "created")
+        cls._parse_datetime_field(frontmatter, "updated")
+        cls._parse_datetime_field(frontmatter, "actual_start_date")
+        cls._parse_datetime_field(frontmatter, "actual_end_date")
+        cls._parse_datetime_field(frontmatter, "handoff_date")
+
+        # Parse enum fields with validation
+        cls._parse_enum_field(frontmatter, "priority", Priority, file_path)
+        cls._parse_enum_field(frontmatter, "status", Status, file_path)
+        cls._parse_enum_field(frontmatter, "issue_type", IssueType, file_path)
+
+        # Ensure list fields exist
+        cls._ensure_list_fields(frontmatter)
+
+        # Map legacy "description" field to "content" if present
+        if "description" in frontmatter and "content" not in frontmatter:
+            frontmatter["content"] = frontmatter.pop("description")
+        else:
+            # Otherwise use the body content
+            frontmatter["content"] = content
+
+        # If headline is not provided, use first line of content as fallback
+        if "headline" not in frontmatter or not frontmatter["headline"]:
+            first_line = content.split("\n")[0] if content else ""
+            frontmatter["headline"] = first_line[:100]  # Limit to 100 chars
+
+        return Issue(**frontmatter)
+
+    @classmethod
+    def save_issue_file(
+        cls, issue: Issue, file_path: Path, sync_metadata: dict | None = None
+    ) -> None:
+        """Save an Issue object to a markdown file.
+
+        Args:
+            issue: Issue object to save
+            file_path: Path to write the file to
+            sync_metadata: Optional sync metadata to include in frontmatter
+        """
+        frontmatter = issue.model_dump(exclude={"content", "file_path"})
+
+        # Add sync_metadata if provided
+        if sync_metadata:
+            FrontmatterParser.update_sync_metadata(frontmatter, sync_metadata)
+
+        FrontmatterParser.serialize_file(frontmatter, issue.content, file_path)
+
+    @classmethod
+    def load_sync_metadata(cls, file_path: Path) -> dict | None:
+        """Load sync_metadata from an issue file without parsing the full issue.
+
+        Args:
+            file_path: Path to the issue file
+
+        Returns:
+            Sync metadata dictionary or None if not present
+        """
+        frontmatter, _ = FrontmatterParser.parse_file(file_path)
+        return FrontmatterParser.extract_sync_metadata(frontmatter)
+
+    @classmethod
+    def update_issue_sync_metadata(cls, file_path: Path, sync_metadata: dict) -> None:
+        """Update only the sync_metadata in an issue file without parsing the full Issue.
+
+        This is useful for updating sync state without deserializing and re-serializing
+        the entire Issue object.
+
+        Args:
+            file_path: Path to the issue file
+            sync_metadata: Sync metadata to set
+        """
+        frontmatter, content = FrontmatterParser.parse_file(file_path)
+        FrontmatterParser.update_sync_metadata(frontmatter, sync_metadata)
+        FrontmatterParser.serialize_file(frontmatter, content, file_path)
+
+    @classmethod
+    def _validate_enum_field(
+        cls, field_name: str, value: str | None, enum_class
+    ) -> tuple[bool, Any, str | None]:
+        """Validate and convert enum field. Returns (success, value, error_message)."""
+        if not value:
+            return True, None, None
+
+        try:
+            return True, enum_class(value), None
+        except ValueError:
+            valid_values = [e.value for e in enum_class]
+            error_msg = (
+                f"Invalid {field_name}: {value}. Valid: {', '.join(valid_values)}"
+            )
+            return False, None, error_msg
+
+    @classmethod
+    def _extract_issue_dates(
+        cls, data: dict
+    ) -> tuple[datetime, datetime, datetime | None]:
+        """Extract and parse date fields from data."""
+        now = now_utc()
+        created = cls._parse_datetime(data.get("created")) or now
+        updated = cls._parse_datetime(data.get("updated")) or now
+        due_date = cls._parse_datetime(data.get("due_date"))
+        return created, updated, due_date
+
+    @classmethod
+    def _build_issue_from_data(
+        cls, data: dict, file_path: Path
+    ) -> tuple[bool, Issue | None, str | None]:
+        """Build Issue object from validated data. Returns (success, issue, error_message)."""
+        # Validate priority
+        success, priority, error = cls._validate_enum_field(
+            "priority", data.get("priority"), Priority
+        )
+        if not success:
+            return False, None, f"{error} in {file_path}"
+        priority = priority or Priority.MEDIUM
+
+        # Validate status
+        success, status, error = cls._validate_enum_field(
+            "status", data.get("status"), Status
+        )
+        if not success:
+            return False, None, f"{error} in {file_path}"
+        status = status or Status.TODO
+
+        # Validate issue_type
+        success, _, error = cls._validate_enum_field(
+            "issue_type", data.get("issue_type"), IssueType
+        )
+        if not success:
+            return False, None, f"{error} in {file_path}"
+
+        # Extract dates
+        created, updated, due_date = cls._extract_issue_dates(data)
+
+        try:
+            issue = Issue(
+                id=data.get("id") or str(uuid.uuid4())[:8],
+                title=data.get("title") or "Untitled Issue",
+                priority=priority,
+                status=status,
+                assignee=data.get("assignee"),
+                milestone=data.get("milestone"),
+                labels=data.get("labels", []),
+                created=created,
+                updated=updated,
+                due_date=due_date,
+                content=data.get("content", ""),
+            )
+            return True, issue, None
+        except Exception as e:
+            return False, None, f"Error creating Issue: {e}"
+
+    @classmethod
+    def parse_issue_file_safe(
+        cls, file_path: Path
+    ) -> tuple[bool, Issue | None, str | None]:
+        """Safely parse an issue file with enhanced validation and recovery.
+
+        Returns:
+            (success, issue, error_message)
+        """
+        is_valid, result = enhanced_persistence.safe_load_with_validation(
+            file_path, "issue"
+        )
+
+        if not is_valid:
+            # result is a string error message
+            return False, None, str(result)
+
+        try:
+            # Convert the validated data to an Issue
+            # At this point, result must be a dict since is_valid is True
+            data = result if isinstance(result, dict) else {}
+            return cls._build_issue_from_data(data, file_path)
+        except Exception as e:
+            return False, None, f"Error processing issue file: {e}"
+
+    @classmethod
+    def save_issue_file_safe(cls, issue: Issue, file_path: Path) -> tuple[bool, str]:
+        """Safely save an issue file with automatic backup."""
+        try:
+            cls.save_issue_file(issue, file_path)
+            return True, "Issue saved successfully"
+        except Exception as e:
+            return False, f"Error saving issue: {e}"
+
+    @classmethod
+    def _parse_datetime(cls, value: Any) -> datetime | None:
+        """Parse datetime from various formats with timezone awareness."""
+        return parse_datetime(value, source_type="file", assumed_timezone="UTC")

roadmap/adapters/persistence/parser/milestone.py

@@ -0,0 +1,146 @@
+"""Parser for milestone markdown files."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from roadmap.common.datetime_parser import parse_datetime
+from roadmap.common.utils.timezone_utils import now_utc
+from roadmap.core.domain import Milestone, MilestoneStatus
+
+from ..persistence import enhanced_persistence
+from .frontmatter import FrontmatterParser
+
+
+class MilestoneParser:
+    """Parser specifically for milestone markdown files."""
+
+    @classmethod
+    def parse_milestone_file(cls, file_path: Path) -> Milestone:
+        """Parse a milestone markdown file and return a Milestone object."""
+        frontmatter, content = FrontmatterParser.parse_file(file_path)
+
+        # Convert string dates back to datetime objects
+        for date_field in ["created", "updated", "due_date"]:
+            if date_field in frontmatter and isinstance(frontmatter[date_field], str):
+                frontmatter[date_field] = parse_datetime(
+                    frontmatter[date_field], "file"
+                )
+
+        # Backward-compatibility: some historical files may be missing `name`.
+        # Use filename stem so list/view commands remain consistent with disk state.
+        if not frontmatter.get("name"):
+            frontmatter["name"] = file_path.stem
+
+        # Convert string enums back to enum objects with validation
+        if "status" in frontmatter:
+            try:
+                frontmatter["status"] = MilestoneStatus(frontmatter["status"])
+            except ValueError as e:
+                valid_statuses = [s.value for s in MilestoneStatus]
+                raise ValueError(
+                    f"Invalid status '{frontmatter['status']}' in {file_path}. "
+                    f"Valid status values are: {', '.join(valid_statuses)}"
+                ) from e
+
+        # Map legacy "description" field to "content" if present
+        if "description" in frontmatter and "content" not in frontmatter:
+            frontmatter["content"] = frontmatter.pop("description")
+        else:
+            # Otherwise use the body content
+            frontmatter["content"] = content
+
+        # If headline is not provided, use first line of content as fallback
+        if "headline" not in frontmatter or not frontmatter["headline"]:
+            first_line = content.split("\n")[0] if content else ""
+            frontmatter["headline"] = first_line[:100]  # Limit to 100 chars
+
+        return Milestone(**frontmatter)
+
+    @classmethod
+    def save_milestone_file(cls, milestone: Milestone, file_path: Path) -> None:
+        """Save a Milestone object to a markdown file."""
+        frontmatter = milestone.model_dump(exclude={"content", "file_path"})
+        FrontmatterParser.serialize_file(frontmatter, milestone.content, file_path)
+
+    @classmethod
+    def _build_milestone_from_data(
+        cls, data: dict, file_path: Path
+    ) -> tuple[bool, Milestone | None, str | None]:
+        """Build Milestone object from parsed data.
+
+        Args:
+            data: Parsed milestone data
+            file_path: Path to milestone file (for error reporting)
+
+        Returns:
+            (success, milestone, error_message)
+        """
+        try:
+            # Handle datetime fields - set defaults if None
+            now = now_utc()
+            created = cls._parse_datetime(data.get("created")) or now
+            updated = cls._parse_datetime(data.get("updated")) or now
+            due_date = cls._parse_datetime(data.get("due_date"))
+
+            milestone = Milestone(
+                name=data.get("name") or "Untitled Milestone",
+                content=data.get("description", ""),
+                status=MilestoneStatus(data.get("status"))
+                if data.get("status")
+                else MilestoneStatus.OPEN,
+                created=created,
+                updated=updated,
+                due_date=due_date,
+            )
+            return True, milestone, None
+        except ValueError as e:
+            # Check if it's an enum validation error
+            if "status" in str(e):
+                valid_statuses = [s.value for s in MilestoneStatus]
+                return (
+                    False,
+                    None,
+                    f"Invalid status in {file_path}: {e}. Valid values: {', '.join(valid_statuses)}",
+                )
+            return False, None, f"Error creating Milestone object: {e}"
+        except Exception as e:
+            return False, None, f"Error creating Milestone object: {e}"
+
+    @classmethod
+    def parse_milestone_file_safe(
+        cls, file_path: Path
+    ) -> tuple[bool, Milestone | None, str | None]:
+        """Safely parse a milestone file with enhanced validation and recovery.
+
+        Returns:
+            (success, milestone, error_message)
+        """
+        is_valid, result = enhanced_persistence.safe_load_with_validation(
+            file_path, "milestone"
+        )
+
+        if not is_valid:
+            # result is a string error message
+            return False, None, str(result)
+
+        # Convert the validated data to a Milestone
+        # At this point, result must be a dict since is_valid is True
+        data = result if isinstance(result, dict) else {}
+        return cls._build_milestone_from_data(data, file_path)
+
+    @classmethod
+    def save_milestone_file_safe(
+        cls, milestone: Milestone, file_path: Path
+    ) -> tuple[bool, str]:
+        """Safely save a milestone file with automatic backup."""
+        try:
+            cls.save_milestone_file(milestone, file_path)
+            return True, "Milestone saved successfully"
+        except Exception as e:
+            return False, f"Error saving milestone: {e}"
+
+    @classmethod
+    def _parse_datetime(cls, value: Any) -> datetime | None:
+        """Parse datetime from various formats with timezone awareness."""
+        return parse_datetime(value, source_type="file", assumed_timezone="UTC")

roadmap/adapters/persistence/parser/project.py

@@ -0,0 +1,106 @@
+"""Parser for project markdown files."""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from roadmap.common.datetime_parser import parse_datetime
+from roadmap.common.utils.timezone_utils import now_utc
+from roadmap.core.domain import Priority, Project, ProjectStatus
+
+from .frontmatter import FrontmatterParser
+
+
+class ProjectParser:
+    """Parser for project markdown files."""
+
+    @classmethod
+    def parse_project_file(cls, file_path: Path) -> Project:
+        """Parse a project file and return a Project instance."""
+        frontmatter, content = FrontmatterParser.parse_file(file_path)
+
+        # Extract ID from frontmatter, or from filename if not present
+        project_id = frontmatter.get("id", "")
+        if not project_id:
+            # Extract ID from filename (format: {id}-{name}.md)
+            filename_stem = file_path.stem
+            if "-" in filename_stem:
+                project_id = filename_stem.split("-", 1)[0]
+
+        # Convert frontmatter to Project model
+        project = Project(
+            id=project_id,
+            name=frontmatter.get("name", ""),
+            headline=frontmatter.get("headline", ""),
+            status=ProjectStatus(frontmatter.get("status", "planning")),
+            priority=Priority(frontmatter.get("priority", "medium")),
+            owner=frontmatter.get("owner"),
+            start_date=cls._parse_datetime(frontmatter.get("start_date")),
+            target_end_date=cls._parse_datetime(frontmatter.get("target_end_date")),
+            actual_end_date=cls._parse_datetime(frontmatter.get("actual_end_date")),
+            created=cls._parse_datetime(frontmatter.get("created")) or now_utc(),
+            updated=cls._parse_datetime(frontmatter.get("updated")) or now_utc(),
+            milestones=frontmatter.get("milestones", []),
+            estimated_hours=frontmatter.get("estimated_hours"),
+            actual_hours=frontmatter.get("actual_hours"),
+            content=content,
+            calculated_progress=frontmatter.get("calculated_progress"),
+            last_progress_update=cls._parse_datetime(
+                frontmatter.get("last_progress_update")
+            ),
+            projected_end_date=cls._parse_datetime(
+                frontmatter.get("projected_end_date")
+            ),
+            schedule_variance=frontmatter.get("schedule_variance"),
+            completion_velocity=frontmatter.get("completion_velocity"),
+            risk_level=frontmatter.get("risk_level", "low"),
+        )
+
+        return project
+
+    @classmethod
+    def save_project_file(cls, project: Project, file_path: Path) -> None:
+        """Save a project to a markdown file."""
+        # Create frontmatter from project data
+        frontmatter = {
+            "id": project.id,
+            "name": project.name,
+            "headline": project.headline,
+            "status": project.status.value,
+            "priority": project.priority.value,
+            "owner": project.owner,
+            "start_date": project.start_date.isoformat()
+            if project.start_date
+            else None,
+            "target_end_date": project.target_end_date.isoformat()
+            if project.target_end_date
+            else None,
+            "actual_end_date": project.actual_end_date.isoformat()
+            if project.actual_end_date
+            else None,
+            "created": project.created.isoformat(),
+            "updated": project.updated.isoformat(),
+            "milestones": project.milestones,
+            "estimated_hours": project.estimated_hours,
+            "actual_hours": project.actual_hours,
+            "calculated_progress": project.calculated_progress,
+            "last_progress_update": project.last_progress_update.isoformat()
+            if project.last_progress_update
+            else None,
+            "projected_end_date": project.projected_end_date.isoformat()
+            if project.projected_end_date
+            else None,
+            "schedule_variance": project.schedule_variance,
+            "completion_velocity": project.completion_velocity,
+            "risk_level": project.risk_level.value,
+        }
+
+        # Remove None values
+        frontmatter = {k: v for k, v in frontmatter.items() if v is not None}
+
+        FrontmatterParser.serialize_file(frontmatter, project.content, file_path)
+
+    @classmethod
+    def _parse_datetime(cls, value: Any) -> datetime | None:
+        """Parse datetime from various formats with timezone awareness."""
+        return parse_datetime(value, source_type="file", assumed_timezone="UTC")