Backlog Adapter Patterns

from specfact_cli.adapters.backlog_base import BacklogAdapterMixin
from specfact_cli.adapters.base import BridgeAdapter

class MyBacklogAdapter(BridgeAdapter, BacklogAdapterMixin):
    """My backlog adapter implementation."""
    
    # Implement abstract methods from BacklogAdapterMixin
    def map_backlog_status_to_openspec(self, status: str) -> str:
        """Map backlog tool status to OpenSpec status."""
        # Tool-specific mapping logic
        pass
    
    def map_openspec_status_to_backlog(self, status: str) -> list[str]:
        """Map OpenSpec status to backlog tool status."""
        # Tool-specific mapping logic
        pass
    
    def extract_change_proposal_data(self, item_data: dict[str, Any]) -> dict[str, Any]:
        """Extract change proposal data from backlog item."""
        # Tool-specific parsing logic
        pass

def map_backlog_status_to_openspec(self, status: str) -> str:
    """
    Map backlog tool status to OpenSpec change status.
    
    Args:
        status: Backlog tool status (e.g., GitHub label, ADO state, Jira status, Linear state)
    
    Returns:
        OpenSpec change status (proposed, in-progress, applied, deprecated, discarded)
    """
    status_lower = status.lower()
    
    # Tool-specific mapping
    if status_lower in ("new", "todo", "backlog"):
        return "proposed"
    elif status_lower in ("in-progress", "active", "in development"):
        return "in-progress"
    elif status_lower in ("done", "completed", "closed"):
        return "applied"
    # ... more mappings
    
    return "proposed"  # Default

def map_openspec_status_to_backlog(self, status: str) -> list[str]:
    """
    Map OpenSpec change status to backlog tool status.
    
    Args:
        status: OpenSpec change status
    
    Returns:
        List of backlog tool status indicators (labels, states, etc.)
    """
    status_indicators = ["openspec"]  # Common prefix
    
    if status == "in-progress":
        status_indicators.append("in-progress")
    elif status == "applied":
        status_indicators.append("completed")
    # ... more mappings
    
    return status_indicators

def extract_change_proposal_data(self, item_data: dict[str, Any]) -> dict[str, Any]:
    """
    Extract change proposal data from backlog item.
    
    Args:
        item_data: Backlog item data (tool-specific format)
    
    Returns:
        Dict with change proposal fields:
        - title: str
        - description: str (What Changes section)
        - rationale: str (Why section)
        - status: str (mapped to OpenSpec status)
        - Other optional fields
    """
    # Parse tool-specific format
    title = item_data.get("title", "")
    body = item_data.get("body", "") or item_data.get("description", "")
    
    # Extract sections (Why, What Changes)
    rationale = extract_section(body, "Why")
    description = extract_section(body, "What Changes")
    
    # Map status
    status = self.map_backlog_status_to_openspec(item_data.get("status", "open"))
    
    return {
        "change_id": item_data.get("id", "unknown"),
        "title": title,
        "description": description,
        "rationale": rationale,
        "status": status,
        "created_at": item_data.get("created_at", ""),
        # ... other fields
    }

def import_artifact(
    self,
    artifact_key: str,
    artifact_path: Path | dict[str, Any],
    project_bundle: Any,
    bridge_config: BridgeConfig | None = None,
) -> None:
    """
    Import artifact from backlog tool.
    
    Args:
        artifact_key: Artifact key (e.g., "github_issue", "ado_work_item", "jira_issue")
        artifact_path: Backlog item data (dict from API response)
        project_bundle: Project bundle to update
        bridge_config: Bridge configuration
    """
    # Supported artifact keys for backlog adapters:
    # - "change_proposal": Create new backlog item from change proposal
    # - "change_status": Update backlog item status only
    # - "change_proposal_update": Update backlog item body/content
    # - "change_proposal_comment": Add status comment to backlog item
    # - "code_change_progress": Add progress comment based on code changes
    # - "my_backlog_item": Import backlog item as change proposal (tool-specific)
    
    if artifact_key not in ["change_proposal", "change_status", "change_proposal_update", 
                            "change_proposal_comment", "code_change_progress", "my_backlog_item"]:
        raise NotImplementedError(f"Unsupported artifact key: {artifact_key}")
    
    if not isinstance(artifact_path, dict):
        raise ValueError("Backlog item import requires dict (API response)")
    
    # Use reusable pattern from BacklogAdapterMixin
    proposal = self.import_backlog_item_as_proposal(
        artifact_path, "my_backlog_tool", bridge_config
    )
    
    # Add to project bundle
    if hasattr(project_bundle, "change_tracking"):
        if not project_bundle.change_tracking:
            from specfact_cli.models.change import ChangeTracking
            project_bundle.change_tracking = ChangeTracking()
        project_bundle.change_tracking.proposals[proposal.name] = proposal

def sync_status_to_backlog(
    self,
    proposal: dict[str, Any] | ChangeProposal,
    repo_owner: str,
    repo_name: str,
    bridge_config: BridgeConfig | None = None,
) -> dict[str, Any]:
    """
    Sync OpenSpec change status to backlog tool.
    
    Updates backlog item status based on OpenSpec change proposal status.
    """
    # Extract status and source_tracking
    # Map OpenSpec status to backlog status
    # Update backlog item via API
    # Return sync result
    pass

def sync_status_from_backlog(
    self,
    item_data: dict[str, Any],
    proposal: dict[str, Any] | ChangeProposal,
    strategy: str = "prefer_openspec",
) -> str:
    """
    Sync backlog tool status to OpenSpec change proposal.
    
    Maps backlog item status to OpenSpec status and resolves conflicts.
    """
    # Extract backlog status
    # Map to OpenSpec status
    # Resolve conflicts using BacklogAdapterMixin.resolve_status_conflict()
    # Return resolved status
    pass

# Example usage
resolved_status = self.resolve_status_conflict(
    openspec_status="proposed",
    backlog_status="in-progress",
    strategy="merge"  # Results in "in-progress" (more advanced)
)

source_tracking = self.create_source_tracking(item_data, "my_backlog_tool", bridge_config)

# Add tool-specific fields
source_tracking.source_metadata["my_tool_field"] = item_data.get("my_tool_field")
source_tracking.source_metadata["my_tool_id"] = item_data.get("id")

def import_artifact(
    self,
    artifact_key: str,
    artifact_path: Path | dict[str, Any],
    project_bundle: Any,
    bridge_config: BridgeConfig | None = None,
) -> None:
    """Import backlog item with lossless content preservation."""
    # ... import logic ...
    
    # CRITICAL: Store raw content for lossless round-trip sync
    if proposal.source_tracking and isinstance(proposal.source_tracking.source_metadata, dict):
        source_metadata = proposal.source_tracking.source_metadata
        raw_title = item_data.get("title") or ""
        raw_body = item_data.get("body") or item_data.get("description") or ""
        source_metadata["raw_title"] = raw_title
        source_metadata["raw_body"] = raw_body
        source_metadata["raw_format"] = "markdown"  # or "html" if applicable

def export_artifact(
    self,
    artifact_key: str,
    artifact_data: Any,
    bridge_config: BridgeConfig | None = None,
) -> dict[str, Any] | Path:
    """Export with lossless content preservation."""
    # Extract raw content if available
    raw_title, raw_body = self._extract_raw_fields(artifact_data)
    
    # Use raw content if available, otherwise construct from proposal data
    if raw_title:
        title = raw_title
    else:
        title = artifact_data.get("title", "Untitled")
    
    if raw_body:
        body = raw_body
    else:
        # Construct body from proposal sections
        body = self._construct_body_from_proposal(artifact_data)
    
    # ... export logic using title and body ...

def _extract_raw_fields(self, proposal_data: dict[str, Any]) -> tuple[str | None, str | None]:
    """Extract lossless title/body content from proposal data."""
    raw_title = proposal_data.get("raw_title")
    raw_body = proposal_data.get("raw_body")
    if raw_title and raw_body:
        return raw_title, raw_body
    
    # Check source_tracking metadata
    source_tracking = proposal_data.get("source_tracking")
    source_metadata = None
    if isinstance(source_tracking, dict):
        source_metadata = source_tracking.get("source_metadata")
    elif hasattr(source_tracking, "source_metadata"):
        source_metadata = getattr(source_tracking, "source_metadata")
    
    if isinstance(source_metadata, dict):
        raw_title = raw_title or source_metadata.get("raw_title")
        raw_body = raw_body or source_metadata.get("raw_body")
    
    return raw_title, raw_body

class TestMyBacklogAdapter:
    """Test my backlog adapter implementation."""
    
    def test_map_backlog_status_to_openspec(self, adapter):
        """Test status mapping from backlog to OpenSpec."""
        assert adapter.map_backlog_status_to_openspec("new") == "proposed"
        assert adapter.map_backlog_status_to_openspec("in-progress") == "in-progress"
    
    def test_extract_change_proposal_data(self, adapter):
        """Test extracting change proposal data."""
        item_data = {
            "title": "Test Issue",
            "body": "## Why\n\nTest\n\n## What Changes\n\nImplement",
            "status": "new",
        }
        result = adapter.extract_change_proposal_data(item_data)
        assert result["title"] == "Test Issue"
        assert result["status"] == "proposed"
    
    def test_import_artifact(self, adapter, project_bundle):
        """Test importing backlog item."""
        item_data = {...}
        adapter.import_artifact("my_backlog_item", item_data, project_bundle)
        assert "123" in project_bundle.change_tracking.proposals

class TestBidirectionalBacklogSync:
    """Integration tests for bidirectional backlog sync."""
    
    def test_openspec_to_backlog_export(self, adapter):
        """Test OpenSpec → Backlog export."""
        # Test export
        pass
    
    def test_backlog_to_openspec_import(self, adapter):
        """Test Backlog → OpenSpec import."""
        # Test import
        pass
    
    def test_bidirectional_status_sync(self, adapter):
        """Test bidirectional status sync."""
        # Test status sync
        pass