roadmap-cli 0.1.1__py3-none-any.whl

roadmap/adapters/persistence/persistence.py

@@ -0,0 +1,288 @@
+"""Enhanced YAML validation utilities for roadmap persistence."""
+
+import shutil
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from roadmap.common.datetime_parser import parse_datetime
+from roadmap.common.utils.file_utils import ensure_directory_exists
+from roadmap.common.validation import validate_frontmatter_structure
+
+
+class YAMLRecoveryManager:
+    """Manages YAML file recovery and validation."""
+
+    def __init__(self, backup_dir: Path | None = None):
+        """Initialize YAMLRecoveryManager.
+
+        Args:
+            backup_dir: Directory for storing backups. Defaults to .roadmap/backups.
+        """
+        self.backup_dir = backup_dir or Path(".roadmap/backups")
+        ensure_directory_exists(self.backup_dir)
+
+    def create_backup(self, file_path: Path) -> Path:
+        """Create a backup of a YAML file before modification."""
+        if not file_path.exists():
+            raise FileNotFoundError(f"Cannot backup non-existent file: {file_path}")
+
+        timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+        backup_name = f"{file_path.stem}_{timestamp}.backup{file_path.suffix}"
+        backup_path = self.backup_dir / backup_name
+
+        shutil.copy2(file_path, backup_path)
+        return backup_path
+
+    def list_backups(self, file_path: Path) -> list[Path]:
+        """List all backups for a specific file."""
+        pattern = f"{file_path.stem}_*.backup{file_path.suffix}"
+        return sorted(self.backup_dir.glob(pattern), reverse=True)
+
+    def validate_yaml_syntax(
+        self, content: str, file_path: Path | None = None
+    ) -> tuple[bool, str | None]:
+        """Validate YAML syntax and return error details if invalid."""
+        try:
+            yaml.safe_load(content)
+            return True, None
+        except yaml.YAMLError as e:
+            error_msg = f"YAML syntax error: {e}"
+            if hasattr(e, "problem_mark") and e.problem_mark:  # type: ignore
+                line_num = e.problem_mark.line + 1  # type: ignore
+                col_num = e.problem_mark.column + 1  # type: ignore
+                error_msg += f" at line {line_num}, column {col_num}"
+            return False, error_msg
+
+    def validate_frontmatter_structure(
+        self, frontmatter: dict[str, Any], expected_type: str
+    ) -> tuple[bool, list[str]]:
+        """Validate frontmatter structure for issues or milestones."""
+        # Use unified validation framework
+        is_valid, errors = validate_frontmatter_structure(frontmatter, expected_type)
+
+        # Add datetime validation (specific to persistence layer)
+        datetime_fields = ["created", "updated", "due_date"]
+        for field in datetime_fields:
+            if field in frontmatter and frontmatter[field] is not None:
+                if isinstance(frontmatter[field], str):
+                    try:
+                        parse_datetime(frontmatter[field], "file")
+                    except ValueError:
+                        errors.append(
+                            f"Invalid datetime format for {field}: {frontmatter[field]}"
+                        )
+                        is_valid = False
+
+        return is_valid, errors
+
+    def attempt_recovery(self, file_path: Path) -> tuple[bool, str | None]:
+        """Attempt to recover a corrupted YAML file."""
+        try:
+            # Try to read the file
+            content = file_path.read_text(encoding="utf-8")
+
+            # Check if it's a frontmatter issue
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    frontmatter_content = parts[1]
+                    markdown_content = parts[2].strip() if len(parts) > 2 else ""
+
+                    # Try to fix common YAML issues
+                    fixed_frontmatter = self._fix_common_yaml_issues(
+                        frontmatter_content
+                    )
+
+                    # Validate the fixed YAML
+                    is_valid, _ = self.validate_yaml_syntax(fixed_frontmatter)
+                    if is_valid:
+                        # Create backup before fixing
+                        self.create_backup(file_path)
+
+                        # Write the fixed content
+                        fixed_content = (
+                            f"---\n{fixed_frontmatter}\n---\n\n{markdown_content}"
+                        )
+                        file_path.write_text(fixed_content, encoding="utf-8")
+                        return True, "File recovered with YAML fixes applied"
+
+            return False, "Could not automatically recover the file"
+
+        except Exception as e:
+            return False, f"Recovery failed: {e}"
+
+    def _is_already_quoted(self, value: str) -> bool:
+        """Check if value is already properly quoted.
+
+        Args:
+            value: Value to check
+
+        Returns:
+            True if value is already quoted
+        """
+        return (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        )
+
+    def _is_yaml_literal(self, value: str) -> bool:
+        """Check if value is a YAML literal (bool, null, number, collection).
+
+        Args:
+            value: Value to check
+
+        Returns:
+            True if value is a YAML literal
+        """
+        return (
+            value in ["true", "false", "null"]
+            or value.isdigit()
+            or value.startswith("[")
+            or value.startswith("{")
+        )
+
+    def _needs_quoting(self, value: str) -> bool:
+        """Check if value contains special YAML characters requiring quoting.
+
+        Args:
+            value: Value to check
+
+        Returns:
+            True if value needs quoting
+        """
+        special_chars = [
+            ":",
+            "#",
+            "@",
+            "`",
+            "|",
+            ">",
+            "*",
+            "&",
+            "!",
+            "%",
+            "{",
+            "}",
+            "[",
+            "]",
+        ]
+        return any(char in value for char in special_chars)
+
+    def _quote_if_needed(self, value: str) -> str:
+        """Quote value if it needs quoting and isn't already quoted.
+
+        Args:
+            value: Value to potentially quote
+
+        Returns:
+            Quoted value if needed, otherwise original value
+        """
+        if value and not (
+            self._is_already_quoted(value) or self._is_yaml_literal(value)
+        ):
+            if self._needs_quoting(value):
+                return f'"{value}"'
+        return value
+
+    def _fix_yaml_line(self, line: str) -> str:
+        """Fix a single YAML line.
+
+        Args:
+            line: Single line of YAML to fix
+
+        Returns:
+            Fixed line
+        """
+        if not line.strip() or line.strip().startswith("#"):
+            return line
+
+        if ":" in line:
+            key, _, value = line.partition(":")
+            value = value.strip()
+            fixed_value = self._quote_if_needed(value)
+            return f"{key}: {fixed_value}"
+
+        return line
+
+    def _fix_common_yaml_issues(self, yaml_content: str) -> str:
+        """Fix common YAML formatting issues."""
+        lines = yaml_content.split("\n")
+        fixed_lines = [self._fix_yaml_line(line) for line in lines]
+        return "\n".join(fixed_lines)
+
+
+class EnhancedYAMLPersistence:
+    """Enhanced YAML persistence with validation and recovery."""
+
+    def __init__(self, recovery_manager: YAMLRecoveryManager | None = None):
+        """Initialize EnhancedYAMLPersistence.
+
+        Args:
+            recovery_manager: YAMLRecoveryManager instance. Defaults to new instance.
+        """
+        self.recovery_manager = recovery_manager or YAMLRecoveryManager()
+
+    def safe_load_with_validation(
+        self, file_path: Path, expected_type: str
+    ) -> tuple[bool, dict[str, Any] | str]:
+        """Safely load and validate a YAML file with recovery options."""
+        try:
+            if not file_path.exists():
+                return False, f"File does not exist: {file_path}"
+
+            content = file_path.read_text(encoding="utf-8")
+
+            # Parse frontmatter
+            if not content.startswith("---"):
+                return False, "File does not contain YAML frontmatter"
+
+            parts = content.split("---", 2)
+            if len(parts) < 3:
+                return False, "Invalid frontmatter format"
+
+            frontmatter_content = parts[1]
+            markdown_content = parts[2].strip()
+
+            # Validate YAML syntax
+            is_valid, error = self.recovery_manager.validate_yaml_syntax(
+                frontmatter_content, file_path
+            )
+            if not is_valid:
+                # Attempt recovery
+                recovered, recovery_msg = self.recovery_manager.attempt_recovery(
+                    file_path
+                )
+                if recovered:
+                    # Retry loading after recovery
+                    return self.safe_load_with_validation(file_path, expected_type)
+                else:
+                    return (
+                        False,
+                        f"YAML validation failed: {error}. Recovery failed: {recovery_msg}",
+                    )
+
+            # Parse YAML
+            loaded = yaml.safe_load(frontmatter_content)
+            frontmatter: dict = loaded if isinstance(loaded, dict) else {}
+
+            # Validate structure
+            is_valid, errors = self.recovery_manager.validate_frontmatter_structure(
+                frontmatter, expected_type
+            )
+            if not is_valid:
+                return False, f"Validation errors: {'; '.join(errors)}"
+
+            # Add content to frontmatter
+            frontmatter["content"] = markdown_content
+
+            return True, frontmatter
+
+        except Exception as e:
+            return False, f"Failed to load file: {e}"
+
+
+# Global instances for easy access
+recovery_manager = YAMLRecoveryManager()
+enhanced_persistence = EnhancedYAMLPersistence(recovery_manager)

roadmap/adapters/persistence/repositories/__init__.py

@@ -0,0 +1,15 @@
+"""Repository classes for persistence layer."""
+
+from .issue_repository import IssueRepository
+from .milestone_repository import MilestoneRepository
+from .project_repository import ProjectRepository
+from .remote_link_repository import RemoteLinkRepository
+from .sync_state_repository import SyncStateRepository
+
+__all__ = [
+    "ProjectRepository",
+    "MilestoneRepository",
+    "IssueRepository",
+    "SyncStateRepository",
+    "RemoteLinkRepository",
+]

roadmap/adapters/persistence/repositories/issue_repository.py

@@ -0,0 +1,223 @@
+"""Repository for issue persistence operations."""
+
+from typing import Any
+
+from roadmap.common.errors import OperationType, safe_operation
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class IssueRepository:
+    """Handles all issue-related database operations."""
+
+    def __init__(self, get_connection, transaction):
+        """Initialize repository with database connection methods.
+
+        Args:
+            get_connection: Callable that returns sqlite3 Connection
+            transaction: Context manager for database transactions
+        """
+        self._get_connection = get_connection
+        self._transaction = transaction
+
+    @safe_operation(OperationType.CREATE, "Issue", include_traceback=True)
+    @safe_operation(OperationType.CREATE, "Issue", include_traceback=True)
+    def create(self, issue_data: dict[str, Any]) -> str:
+        """Create a new issue.
+
+        Args:
+            issue_data: Dictionary with issue fields
+
+        Returns:
+            Issue ID
+        """
+        with self._transaction() as conn:
+            project_id = issue_data.get("project_id")
+            if project_id:
+                exists = conn.execute(
+                    "SELECT 1 FROM projects WHERE id = ?",
+                    (project_id,),
+                ).fetchone()
+                if not exists:
+                    logger.warning(
+                        "issue_create_missing_project",
+                        issue_id=issue_data.get("id"),
+                        project_id=project_id,
+                    )
+                    project_id = None
+
+            milestone_id = issue_data.get("milestone_id")
+            if milestone_id:
+                exists = conn.execute(
+                    "SELECT 1 FROM milestones WHERE id = ?",
+                    (milestone_id,),
+                ).fetchone()
+                if not exists:
+                    logger.warning(
+                        "issue_create_missing_milestone",
+                        issue_id=issue_data.get("id"),
+                        milestone_id=milestone_id,
+                    )
+                    milestone_id = None
+
+            conn.execute(
+                """
+                INSERT INTO issues (id, project_id, milestone_id, title, headline, description, status, priority, issue_type, assignee, estimate_hours, due_date, metadata)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+                (
+                    issue_data["id"],
+                    project_id,
+                    milestone_id,
+                    issue_data.get("title"),
+                    issue_data.get("headline", ""),
+                    issue_data.get("description"),
+                    issue_data.get("status", "open"),
+                    issue_data.get("priority", "medium"),
+                    issue_data.get("issue_type", "task"),
+                    issue_data.get("assignee"),
+                    issue_data.get("estimate_hours"),
+                    issue_data.get("due_date"),
+                    issue_data.get("metadata"),
+                ),
+            )
+
+        logger.info("Created issue", issue_id=issue_data["id"])
+        return issue_data["id"]
+
+    def get(self, issue_id: str) -> dict[str, Any] | None:
+        """Get issue by ID.
+
+        Args:
+            issue_id: Issue identifier
+
+        Returns:
+            Issue data or None if not found
+        """
+        conn = self._get_connection()
+        row = conn.execute("SELECT * FROM issues WHERE id = ?", (issue_id,)).fetchone()
+
+        return dict(row) if row else None
+
+    @safe_operation(OperationType.UPDATE, "Issue")
+    @safe_operation(OperationType.UPDATE, "Issue")
+    def update(self, issue_id: str, updates: dict[str, Any]) -> bool:
+        """Update issue.
+
+        Args:
+            issue_id: Issue identifier
+            updates: Dictionary of fields to update
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not updates:
+            return False
+
+        set_clause = ", ".join(f"{key} = ?" for key in updates.keys())
+        values = list(updates.values()) + [issue_id]
+
+        with self._transaction() as conn:
+            cursor = conn.execute(
+                f"""
+                UPDATE issues SET {set_clause} WHERE id = ?
+            """,
+                values,
+            )
+
+        updated = cursor.rowcount > 0
+        if updated:
+            logger.info(
+                "Updated issue", issue_id=issue_id, updates=list(updates.keys())
+            )
+
+        return updated
+
+    @safe_operation(OperationType.DELETE, "Issue", include_traceback=True)
+    @safe_operation(OperationType.DELETE, "Issue", include_traceback=True)
+    def delete(self, issue_id: str) -> bool:
+        """Delete issue.
+
+        Args:
+            issue_id: Issue identifier
+
+        Returns:
+            True if successful, False otherwise
+        """
+        with self._transaction() as conn:
+            cursor = conn.execute("DELETE FROM issues WHERE id = ?", (issue_id,))
+
+        deleted = cursor.rowcount > 0
+        if deleted:
+            logger.info("Deleted issue", issue_id=issue_id)
+
+        return deleted
+
+    @safe_operation(OperationType.DELETE, "Issue", include_traceback=True)
+    def delete_many(self, issue_ids: list[str]) -> int:
+        """Delete multiple issues in a single transaction.
+
+        Batch delete is much more efficient than deleting one-by-one
+        as it avoids repeated cache invalidations and enumeration.
+
+        Args:
+            issue_ids: List of issue identifiers to delete
+
+        Returns:
+            Number of issues successfully deleted
+        """
+        if not issue_ids:
+            return 0
+
+        with self._transaction() as conn:
+            placeholders = ",".join("?" * len(issue_ids))
+            cursor = conn.execute(
+                f"DELETE FROM issues WHERE id IN ({placeholders})",
+                issue_ids,
+            )
+
+        deleted_count = cursor.rowcount
+        if deleted_count > 0:
+            logger.info(
+                "Deleted multiple issues",
+                count=deleted_count,
+                issue_count=len(issue_ids),
+            )
+
+        return deleted_count
+
+    @safe_operation(OperationType.UPDATE, "Issue")
+    @safe_operation(OperationType.UPDATE, "Issue")
+    def mark_archived(self, issue_id: str, archived: bool = True) -> bool:
+        """Mark an issue as archived or unarchived.
+
+        Args:
+            issue_id: Issue identifier
+            archived: True to archive, False to unarchive
+
+        Returns:
+            True if successful, False otherwise
+        """
+        with self._transaction() as conn:
+            if archived:
+                cursor = conn.execute(
+                    "UPDATE issues SET archived = 1, archived_at = CURRENT_TIMESTAMP WHERE id = ?",
+                    (issue_id,),
+                )
+            else:
+                cursor = conn.execute(
+                    "UPDATE issues SET archived = 0, archived_at = NULL WHERE id = ?",
+                    (issue_id,),
+                )
+
+        updated = cursor.rowcount > 0
+        if updated:
+            action = "archived" if archived else "unarchived"
+            logger.info(
+                "issue_status_changed",
+                issue_id=issue_id,
+                action=action,
+            )
+
+        return updated

roadmap/adapters/persistence/repositories/milestone_repository.py

@@ -0,0 +1,140 @@
+"""Repository for milestone persistence operations."""
+
+from typing import Any
+
+from roadmap.common.errors import OperationType, safe_operation
+from roadmap.common.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class MilestoneRepository:
+    """Handles all milestone-related database operations."""
+
+    def __init__(self, get_connection, transaction):
+        """Initialize repository with database connection methods.
+
+        Args:
+            get_connection: Callable that returns sqlite3 Connection
+            transaction: Context manager for database transactions
+        """
+        self._get_connection = get_connection
+        self._transaction = transaction
+
+    @safe_operation(OperationType.CREATE, "Milestone", include_traceback=True)
+    @safe_operation(OperationType.CREATE, "Milestone", include_traceback=True)
+    def create(self, milestone_data: dict[str, Any]) -> str:
+        """Create a new milestone.
+
+        Args:
+            milestone_data: Dictionary with milestone fields
+
+        Returns:
+            Milestone ID
+        """
+        with self._transaction() as conn:
+            conn.execute(
+                """
+                INSERT INTO milestones (id, project_id, title, description, status, due_date, metadata)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+                (
+                    milestone_data["id"],
+                    milestone_data.get("project_id"),
+                    milestone_data.get("title"),
+                    milestone_data.get("description"),
+                    milestone_data.get("status", "open"),
+                    milestone_data.get("due_date"),
+                    milestone_data.get("metadata"),
+                ),
+            )
+
+        logger.info("Created milestone", milestone_id=milestone_data["id"])
+        return milestone_data["id"]
+
+    def get(self, milestone_id: str) -> dict[str, Any] | None:
+        """Get milestone by ID.
+
+        Args:
+            milestone_id: Milestone identifier
+
+        Returns:
+            Milestone data or None if not found
+        """
+        conn = self._get_connection()
+        row = conn.execute(
+            "SELECT * FROM milestones WHERE id = ?", (milestone_id,)
+        ).fetchone()
+
+        return dict(row) if row else None
+
+    @safe_operation(OperationType.UPDATE, "Milestone")
+    @safe_operation(OperationType.UPDATE, "Milestone")
+    def update(self, milestone_id: str, updates: dict[str, Any]) -> bool:
+        """Update milestone.
+
+        Args:
+            milestone_id: Milestone identifier
+            updates: Dictionary of fields to update
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not updates:
+            return False
+
+        set_clause = ", ".join(f"{key} = ?" for key in updates.keys())
+        values = list(updates.values()) + [milestone_id]
+
+        with self._transaction() as conn:
+            cursor = conn.execute(
+                f"""
+                UPDATE milestones SET {set_clause} WHERE id = ?
+            """,
+                values,
+            )
+
+        updated = cursor.rowcount > 0
+        if updated:
+            logger.info(
+                "Updated milestone",
+                milestone_id=milestone_id,
+                updates=list(updates.keys()),
+            )
+
+        return updated
+
+    @safe_operation(OperationType.UPDATE, "Milestone")
+    @safe_operation(OperationType.UPDATE, "Milestone")
+    def mark_archived(self, milestone_id: str, archived: bool = True) -> bool:
+        """Mark a milestone as archived or unarchived.
+
+        Args:
+            milestone_id: Milestone identifier
+            archived: True to archive, False to unarchive
+
+        Returns:
+            True if successful, False otherwise
+        """
+        with self._transaction() as conn:
+            if archived:
+                cursor = conn.execute(
+                    "UPDATE milestones SET archived = 1, archived_at = CURRENT_TIMESTAMP WHERE id = ?",
+                    (milestone_id,),
+                )
+            else:
+                cursor = conn.execute(
+                    "UPDATE milestones SET archived = 0, archived_at = NULL WHERE id = ?",
+                    (milestone_id,),
+                )
+
+        updated = cursor.rowcount > 0
+        if updated:
+            action = "archived" if archived else "unarchived"
+            logger.info(
+                "milestone_status_changed",
+                milestone_id=milestone_id,
+                action=action,
+            )
+
+        return updated