Source code for gitlab_overviewer.rendering.renderer_base

from abc import ABC, abstractmethod
from typing import Any, List, Optional
from datetime import datetime




class Renderer(ABC):
    """
    Abstract base class for all renderers.

    Implements the required interface for all renderers as per:

    * /specs/spec_renderer_markdown.md §6
    * /specs/spec_renderer_quarto.md §6
    * /specs/spec_model_mapping.md (for data model expectations)

    # TODO: Open questions
    #   1. Should future renderers (e.g., HTML, PDF) follow this interface? (TBD)
    #   2. Are there additional common methods that should be included in the base interface? (TBD)
    #      Possible candidates:
    #
    #      * get_supported_formats(cls) -> List[str]
    #      * validate_output(self, output: str) -> bool
    #      * get_default_config(cls) -> dict
    """



    @abstractmethod
    def render(self, *args, **kwargs) -> Any:
        """
        Render the output for the given data.
        See /specs/spec_renderer_markdown.md and /specs/spec_renderer_quarto.md for required output.
        """
        pass




    @abstractmethod
    def write_files(self, *args, **kwargs) -> None:
        """
        Write rendered output to files as specified.
        See /specs/spec_renderer_markdown.md and /specs/spec_renderer_quarto.md for file output requirements.
        """
        pass




    @staticmethod
    def is_placeholder_value(val: Any) -> bool:
        if val is None or val == "":
            return True
        if isinstance(val, str):
            return val.strip() in ("-", "–", "—")
        return False




    @staticmethod
    def star_rating(val: Any, max_val: int = 5) -> str:
        try:
            rating = int(val)
            if rating <= 0:
                return "—"
            if rating > max_val:
                rating = max_val
            return "★" * rating + "☆" * (max_val - rating)
        except Exception:
            return "—"




    @staticmethod
    def safe_str(val: Any) -> str:
        if Renderer.is_placeholder_value(val):
            return "—"
        return str(val)




    @staticmethod
    def format_date(dt: Any) -> str:
        if Renderer.is_placeholder_value(dt):
            return "—"
        if isinstance(dt, str):
            parsed_dt = Renderer.parse_iso_date(dt)
            if parsed_dt:
                return parsed_dt.strftime("%Y-%m-%d")
            return dt
        if isinstance(dt, datetime):
            return dt.strftime("%Y-%m-%d")
        return str(dt)




    @staticmethod
    def parse_iso_date(dt: Any) -> Optional[datetime]:
        if dt is None:
            return None
        if isinstance(dt, datetime):
            return dt
        if isinstance(dt, str):
            try:
                dt = dt.replace("Z", "+00:00")
                return datetime.fromisoformat(dt)
            except Exception:
                return None
        return None




    @staticmethod
    def parse_comma_list(value: Any) -> List[str]:
        if value is None:
            return []
        if isinstance(value, str):
            return [item.strip() for item in value.split(",") if item.strip()]
        if isinstance(value, list):
            return [str(item) for item in value]
        return []




    @staticmethod
    def safe_int(value: Any, default: int = 0) -> int:
        if value is None:
            return default
        try:
            return int(value)
        except (ValueError, TypeError):
            return default




    @staticmethod
    def safe_float(value: Any, default: float = 0.0) -> float:
        if value is None:
            return default
        try:
            return float(value)
        except (ValueError, TypeError):
            return default




    @staticmethod
    def is_numeric_string(value: Any) -> bool:
        if value is None:
            return False
        try:
            str_val = str(value)
            return str_val.replace(".", "", 1).replace("-", "", 1).isdigit()
        except Exception:
            return False




    @staticmethod
    def get_with_fallback(data: dict, key: str, fallback: str = "—") -> str:
        value = data.get(key, fallback)
        if Renderer.is_placeholder_value(value):
            return "—"
        return str(value)




    @staticmethod
    def format_table_row(
        row: dict, keys: List[str], formatters: Optional[dict] = None
    ) -> List[str]:
        if formatters is None:
            formatters = {}
        result = []
        for key in keys:
            if key in formatters:
                result.append(formatters[key](row.get(key)))
            else:
                result.append(Renderer.safe_str(row.get(key, "—")))
        return result




    @staticmethod
    def process_readme_lines(content: str, max_lines: int = 12) -> List[str]:
        if not content:
            return []
        lines = content.splitlines()
        if lines and lines[0].strip() == "---":
            try:
                frontmatter_end = lines[1:].index("---")
                lines = lines[frontmatter_end + 2 :]
            except ValueError:
                pass
        if len(lines) > max_lines:
            lines = lines[:max_lines]
            lines.append("…continues…")
        return lines




    @staticmethod
    def format_priority_urgency(
        row: dict,
        priority_key: str = "priority",
        urgency_key: str = "urgency",
        max_priority: int = 5,
        max_urgency: int = 5,
    ) -> dict:
        result = row.copy()
        if priority_key in result:
            val = result.get(priority_key, "-")
            if val is None:
                val = "-"
            result[priority_key] = Renderer.star_rating(val, max_priority)
        if urgency_key in result:
            val = result.get(urgency_key, "-")
            if val is None:
                val = "-"
            result[urgency_key] = Renderer.star_rating(val, max_urgency)
        return result




    @staticmethod
    def strip_trailing_whitespace(text: str) -> str:
        if not isinstance(text, str):
            return ""
        return "\n".join(line.rstrip() for line in text.splitlines())