metaxy 0.0.0__py3-none-any.whl

metaxy/graph/diff/models.py

@@ -0,0 +1,418 @@
+"""Core data models for graph rendering."""
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field
+from typing_extensions import Self
+
+from metaxy.models.bases import FrozenBaseModel
+from metaxy.models.types import FeatureKey, FieldKey
+
+if TYPE_CHECKING:
+    from metaxy.models.feature import FeatureGraph
+
+
+class NodeStatus(str, Enum):
+    """Status of a node in a diff view."""
+
+    NORMAL = "normal"  # Normal node (not in diff mode)
+    UNCHANGED = "unchanged"  # Unchanged in diff
+    ADDED = "added"  # Added in diff
+    REMOVED = "removed"  # Removed in diff
+    CHANGED = "changed"  # Changed in diff
+
+
+class FieldNode(FrozenBaseModel):
+    """Represents a field within a feature node.
+
+    Attributes:
+        key: Field key
+        version: Current field version hash
+        old_version: Previous field version hash (for diffs)
+        code_version: Code version (if available)
+        status: Field status (for diff rendering)
+    """
+
+    key: FieldKey
+    version: str | None = None  # None if field was removed
+    old_version: str | None = None  # For diff mode
+    code_version: int | None = None
+    status: NodeStatus = NodeStatus.NORMAL
+
+
+class GraphNode(FrozenBaseModel):
+    """Represents a feature node in the graph.
+
+    Attributes:
+        key: Feature key
+        version: Current feature version hash
+        old_version: Previous feature version hash (for diffs)
+        code_version: Code version (if available)
+        fields: List of field nodes
+        dependencies: List of feature keys this node depends on
+        status: Node status (for diff rendering)
+        metadata: Additional custom metadata
+    """
+
+    key: FeatureKey
+    version: str | None = None  # None if feature was removed
+    old_version: str | None = None  # For diff mode
+    code_version: int | None = None
+    fields: list[FieldNode] = Field(default_factory=list)
+    dependencies: list[FeatureKey] = Field(default_factory=list)
+    status: NodeStatus = NodeStatus.NORMAL
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class EdgeData(FrozenBaseModel):
+    """Represents an edge between two nodes.
+
+    Attributes:
+        from_key: Source feature key (dependency)
+        to_key: Target feature key (dependent)
+    """
+
+    from_key: FeatureKey
+    to_key: FeatureKey
+
+
+class GraphData(FrozenBaseModel):
+    """Container for complete graph structure.
+
+    This is the unified data model used by all renderers.
+
+    Attributes:
+        nodes: Map from feature key string to GraphNode
+        edges: List of edges
+        snapshot_version: Optional snapshot version
+        old_snapshot_version: Optional old snapshot version (for diffs)
+    """
+
+    nodes: dict[str, GraphNode]  # Key is feature_key.to_string()
+    edges: list[EdgeData] = Field(default_factory=list)
+    snapshot_version: str | None = None
+    old_snapshot_version: str | None = None  # For diff mode
+
+    def get_node(self, key: FeatureKey) -> GraphNode | None:
+        """Get node by feature key.
+
+        Args:
+            key: Feature key to lookup
+
+        Returns:
+            GraphNode if found, None otherwise
+        """
+        return self.nodes.get(key.to_string())
+
+    def get_nodes_by_status(self, status: NodeStatus) -> list[GraphNode]:
+        """Get all nodes with a specific status.
+
+        Args:
+            status: Status to filter by
+
+        Returns:
+            List of nodes with matching status
+        """
+        return [node for node in self.nodes.values() if node.status == status]
+
+    def to_struct(self) -> dict[str, Any]:
+        """Serialize to struct (native Python types for storage).
+
+        Note: This uses custom serialization instead of Pydantic's model_dump() because:
+        1. Polars struct columns require specific type conversions (e.g., None → "" for strings, None → 0 for ints)
+        2. Custom types (FeatureKey, FieldKey) need explicit string conversion for storage
+        3. The storage schema is a separate concern from the domain model's Python representation
+        4. Different storage backends may need different serialization formats in the future
+
+        Returns:
+            Dict with structure compatible with Polars struct type
+        """
+        nodes_list = []
+        for node in self.nodes.values():
+            fields_list = []
+            for field in node.fields:
+                fields_list.append(
+                    {
+                        "key": field.key.to_string(),
+                        "version": field.version if field.version is not None else "",
+                        "code_version": field.code_version
+                        if field.code_version is not None
+                        else 0,
+                    }
+                )
+
+            nodes_list.append(
+                {
+                    "key": node.key.to_string(),
+                    "version": node.version if node.version is not None else "",
+                    "code_version": node.code_version
+                    if node.code_version is not None
+                    else 0,
+                    "fields": fields_list,
+                    "dependencies": [dep.to_string() for dep in node.dependencies],
+                }
+            )
+
+        edges_list = []
+        for edge in self.edges:
+            edges_list.append(
+                {
+                    "from_key": edge.from_key.to_string(),
+                    "to_key": edge.to_key.to_string(),
+                }
+            )
+
+        result: dict[str, Any] = {
+            "nodes": nodes_list,
+            "edges": edges_list,
+        }
+
+        # Include snapshot_version if present
+        if self.snapshot_version is not None:
+            result["snapshot_version"] = self.snapshot_version
+
+        # Include old_snapshot_version if present (for diffs)
+        if self.old_snapshot_version is not None:
+            result["old_snapshot_version"] = self.old_snapshot_version
+
+        return result
+
+    @classmethod
+    def from_struct(cls, struct_data: dict[str, Any]) -> Self:
+        """Deserialize from struct.
+
+        Args:
+            struct_data: Dict with structure from to_struct()
+
+        Returns:
+            GraphData instance
+        """
+        nodes = {}
+        for node_data in struct_data["nodes"]:
+            fields = []
+            for field_data in node_data["fields"]:
+                fields.append(
+                    FieldNode(
+                        key=FieldKey(field_data["key"].split("/")),
+                        version=field_data["version"]
+                        if field_data["version"]
+                        else None,
+                        code_version=field_data["code_version"]
+                        if field_data["code_version"] != 0
+                        else None,
+                    )
+                )
+
+            node = GraphNode(
+                key=FeatureKey(node_data["key"].split("/")),
+                version=node_data["version"] if node_data["version"] else None,
+                code_version=node_data["code_version"]
+                if node_data["code_version"] != 0
+                else None,
+                fields=fields,
+                dependencies=[
+                    FeatureKey(dep.split("/")) for dep in node_data["dependencies"]
+                ],
+            )
+            nodes[node_data["key"]] = node
+
+        edges = []
+        for edge_data in struct_data["edges"]:
+            edges.append(
+                EdgeData(
+                    from_key=FeatureKey(edge_data["from_key"].split("/")),
+                    to_key=FeatureKey(edge_data["to_key"].split("/")),
+                )
+            )
+
+        # Extract snapshot_version if present
+        snapshot_version = struct_data.get("snapshot_version")
+
+        # Extract old_snapshot_version if present (for diffs)
+        old_snapshot_version = struct_data.get("old_snapshot_version")
+
+        return cls(
+            nodes=nodes,
+            edges=edges,
+            snapshot_version=snapshot_version,
+            old_snapshot_version=old_snapshot_version,
+        )
+
+    @classmethod
+    def from_feature_graph(cls, graph: "FeatureGraph") -> "GraphData":
+        """Convert a FeatureGraph to GraphData.
+
+        Args:
+            graph: FeatureGraph instance
+
+        Returns:
+            GraphData with all nodes and edges
+        """
+        from metaxy.models.plan import FQFieldKey
+
+        nodes: dict[str, GraphNode] = {}
+        edges: list[EdgeData] = []
+
+        # Convert each feature to a GraphNode
+        for feature_key, feature_cls in graph.features_by_key.items():
+            feature_key_str = feature_key.to_string()
+            spec = feature_cls.spec
+
+            # Get feature version
+            feature_version = graph.get_feature_version(feature_key)
+
+            # Convert fields
+            field_nodes: list[FieldNode] = []
+            if spec.fields:
+                for field_spec in spec.fields:
+                    # Compute field version
+                    fq_field_key = FQFieldKey(feature=feature_key, field=field_spec.key)
+                    field_version = graph.get_field_version(fq_field_key)
+
+                    field_node = FieldNode(
+                        key=field_spec.key,
+                        version=field_version,
+                        code_version=field_spec.code_version,
+                        status=NodeStatus.NORMAL,
+                    )
+                    field_nodes.append(field_node)
+
+            # Extract dependencies
+            dependencies: list[FeatureKey] = []
+            if spec.deps:
+                dependencies = [dep.key for dep in spec.deps]
+
+            # Create node
+            node = GraphNode(
+                key=feature_key,
+                version=feature_version,
+                code_version=spec.code_version,
+                fields=field_nodes,
+                dependencies=dependencies,
+                status=NodeStatus.NORMAL,
+            )
+            nodes[feature_key_str] = node
+
+            # Create edges
+            for dep_key in dependencies:
+                edges.append(EdgeData(from_key=dep_key, to_key=feature_key))
+
+        return cls(
+            nodes=nodes,
+            edges=edges,
+            snapshot_version=graph.snapshot_version,
+        )
+
+    @classmethod
+    def from_merged_diff(cls, merged_data: dict[str, Any]) -> "GraphData":
+        """Convert merged diff data to GraphData.
+
+        Args:
+            merged_data: Merged diff data from GraphDiffer.create_merged_graph_data()
+
+        Returns:
+            GraphData with status annotations
+        """
+        from metaxy.graph.diff.diff_models import FieldChange
+
+        nodes: dict[str, GraphNode] = {}
+        edges: list[EdgeData] = []
+
+        # Convert nodes
+        for feature_key_str, node_data in merged_data["nodes"].items():
+            # Parse feature key
+            feature_key = FeatureKey(feature_key_str.split("/"))
+
+            # Map status strings to NodeStatus enum
+            status_str = node_data["status"]
+            if status_str == "added":
+                status = NodeStatus.ADDED
+            elif status_str == "removed":
+                status = NodeStatus.REMOVED
+            elif status_str == "changed":
+                status = NodeStatus.CHANGED
+            elif status_str == "unchanged":
+                status = NodeStatus.UNCHANGED
+            else:
+                status = NodeStatus.NORMAL
+
+            # Convert fields
+            fields_dict = node_data.get("fields", {})
+            field_changes_list = node_data.get("field_changes", [])
+
+            # Build field change map for quick lookup
+            field_change_map: dict[str, FieldChange] = {}
+            for fc in field_changes_list:
+                if isinstance(fc, FieldChange):
+                    field_change_map[fc.field_key.to_string()] = fc
+
+            # Get all field keys (from both current fields and removed fields in changes)
+            all_field_keys = set(fields_dict.keys())
+            all_field_keys.update(field_change_map.keys())
+
+            field_nodes: list[FieldNode] = []
+            for field_key_str in all_field_keys:
+                # Parse field key
+                field_key = FieldKey(field_key_str.split("/"))
+
+                # Determine field status and versions
+                if field_key_str in field_change_map:
+                    fc = field_change_map[field_key_str]
+                    if fc.is_added:
+                        field_status = NodeStatus.ADDED
+                        field_version = fc.new_version
+                        old_field_version = None
+                    elif fc.is_removed:
+                        field_status = NodeStatus.REMOVED
+                        field_version = None
+                        old_field_version = fc.old_version
+                    elif fc.is_changed:
+                        field_status = NodeStatus.CHANGED
+                        field_version = fc.new_version
+                        old_field_version = fc.old_version
+                    else:
+                        field_status = NodeStatus.UNCHANGED
+                        field_version = fc.new_version or fc.old_version
+                        old_field_version = None
+                else:
+                    # Unchanged field
+                    field_status = NodeStatus.UNCHANGED
+                    field_version = fields_dict.get(field_key_str)
+                    old_field_version = None
+
+                field_node = FieldNode(
+                    key=field_key,
+                    version=field_version,
+                    old_version=old_field_version,
+                    status=field_status,
+                )
+                field_nodes.append(field_node)
+
+            # Parse dependencies
+            dependencies = [
+                FeatureKey(dep_str.split("/"))
+                for dep_str in node_data.get("dependencies", [])
+            ]
+
+            # Create node
+            node = GraphNode(
+                key=feature_key,
+                version=node_data.get("new_version"),
+                old_version=node_data.get("old_version"),
+                fields=field_nodes,
+                dependencies=dependencies,
+                status=status,
+            )
+            nodes[feature_key_str] = node
+
+        # Convert edges
+        for edge_dict in merged_data["edges"]:
+            from_key = FeatureKey(edge_dict["from"].split("/"))
+            to_key = FeatureKey(edge_dict["to"].split("/"))
+            edges.append(EdgeData(from_key=from_key, to_key=to_key))
+
+        return cls(
+            nodes=nodes,
+            edges=edges,
+        )

metaxy/graph/diff/rendering/__init__.py

@@ -0,0 +1,18 @@
+"""Graph rendering - visualization backends for graphs and diffs."""
+
+from metaxy.graph.diff.rendering.base import BaseRenderer, RenderConfig
+from metaxy.graph.diff.rendering.cards import CardsRenderer
+from metaxy.graph.diff.rendering.graphviz import GraphvizRenderer
+from metaxy.graph.diff.rendering.mermaid import MermaidRenderer
+from metaxy.graph.diff.rendering.rich import TerminalRenderer
+from metaxy.graph.diff.rendering.theme import Theme
+
+__all__ = [
+    "BaseRenderer",
+    "RenderConfig",
+    "TerminalRenderer",
+    "CardsRenderer",
+    "MermaidRenderer",
+    "GraphvizRenderer",
+    "Theme",
+]

metaxy/graph/diff/rendering/base.py

@@ -0,0 +1,274 @@
+"""Base classes and configuration for graph rendering."""
+
+from dataclasses import dataclass, field
+
+from metaxy.graph.diff.models import GraphData, NodeStatus
+from metaxy.graph.diff.rendering.theme import Theme
+from metaxy.graph.diff.traversal import GraphWalker
+from metaxy.graph.utils import format_feature_key, format_field_key, format_hash
+from metaxy.models.feature import FeatureGraph
+from metaxy.models.types import FeatureKey, FieldKey
+
+
+@dataclass
+class RenderConfig:
+    """Configuration for graph rendering.
+
+    Controls what information is displayed and how it's formatted.
+    """
+
+    # What to show
+    show_fields: bool = field(
+        default=True,
+        metadata={"help": "Show field-level details within features"},
+    )
+
+    show_feature_versions: bool = field(
+        default=True,
+        metadata={"help": "Show feature version hashes"},
+    )
+
+    show_field_versions: bool = field(
+        default=True,
+        metadata={"help": "Show field version hashes (requires --show-fields)"},
+    )
+
+    show_code_versions: bool = field(
+        default=False,
+        metadata={"help": "Show feature and field code versions"},
+    )
+
+    show_snapshot_version: bool = field(
+        default=True,
+        metadata={"help": "Show graph snapshot version in output"},
+    )
+
+    # Display options
+    hash_length: int = field(
+        default=8,
+        metadata={
+            "help": "Number of characters to show for version hashes (0 for full)"
+        },
+    )
+
+    direction: str = field(
+        default="TB",
+        metadata={"help": "Graph layout direction: TB (top-bottom) or LR (left-right)"},
+    )
+
+    # Filtering options
+    feature: str | None = field(
+        default=None,
+        metadata={
+            "help": "Focus on a specific feature (e.g., 'video/files' or 'video__files')"
+        },
+    )
+
+    up: int | None = field(
+        default=None,
+        metadata={
+            "help": "Number of dependency levels to render upstream (default: all)"
+        },
+    )
+
+    down: int | None = field(
+        default=None,
+        metadata={
+            "help": "Number of dependency levels to render downstream (default: all)"
+        },
+    )
+
+    def get_feature_key(self) -> FeatureKey | None:
+        """Parse feature string into FeatureKey.
+
+        Returns:
+            FeatureKey if feature is set, None otherwise
+        """
+        if self.feature is None:
+            return None
+
+        # Support both formats: "video__files" or "video/files"
+        if "/" in self.feature:
+            return FeatureKey(self.feature.split("/"))
+        else:
+            return FeatureKey(self.feature.split("__"))
+
+    @classmethod
+    def minimal(cls) -> "RenderConfig":
+        """Preset: minimal information (structure only)."""
+        return cls(
+            show_fields=False,
+            show_feature_versions=False,
+            show_field_versions=False,
+            show_code_versions=False,
+            show_snapshot_version=False,
+        )
+
+    @classmethod
+    def default(cls) -> "RenderConfig":
+        """Preset: default information level (balanced)."""
+        return cls(
+            show_fields=True,
+            show_feature_versions=True,
+            show_field_versions=True,
+            show_code_versions=False,
+            show_snapshot_version=True,
+            hash_length=8,
+        )
+
+    @classmethod
+    def verbose(cls) -> "RenderConfig":
+        """Preset: maximum information (everything)."""
+        return cls(
+            show_fields=True,
+            show_feature_versions=True,
+            show_field_versions=True,
+            show_code_versions=True,
+            show_snapshot_version=True,
+            hash_length=0,  # Full hashes
+        )
+
+
+class BaseRenderer:
+    """Base class for graph renderers.
+
+    Provides common utilities for formatting keys and hashes.
+    Uses unified GraphData model and Theme system.
+    """
+
+    def __init__(
+        self,
+        graph: FeatureGraph | None = None,
+        config: RenderConfig | None = None,
+        graph_data: GraphData | None = None,
+        theme: Theme | None = None,
+    ):
+        """Initialize renderer.
+
+        Args:
+            graph: FeatureGraph (converted to GraphData automatically)
+            config: Render configuration
+            graph_data: GraphData (alternative to feature graph)
+            theme: Color theme (uses default if None)
+
+        Note:
+            Either graph or graph_data must be provided.
+            If both are provided, an error is raised.
+        """
+        if graph_data is None and graph is None:
+            raise ValueError("Either graph or graph_data must be provided")
+
+        # Prefer graph_data if provided, otherwise convert from graph
+        if graph_data is not None:
+            self.graph_data: GraphData = graph_data
+        else:
+            # graph is not None (validated above)
+            assert graph is not None
+            self.graph_data = GraphData.from_feature_graph(graph)
+
+        self.config = config or RenderConfig()
+        self.theme = theme or Theme.default()
+        self.walker = GraphWalker(self.graph_data)
+
+    def _format_hash(self, hash_str: str | None) -> str:
+        """Format hash according to config.
+
+        Args:
+            hash_str: Full hash string (or None for removed nodes)
+
+        Returns:
+            Truncated hash if hash_length > 0, otherwise full hash
+        """
+        if hash_str is None:
+            return "none"
+        return format_hash(hash_str, length=self.config.hash_length)
+
+    def _get_status_color(self, status: NodeStatus) -> str:
+        """Get color for a given status.
+
+        Args:
+            status: Node or field status
+
+        Returns:
+            Color string for Rich markup
+        """
+        if status == NodeStatus.ADDED:
+            return self.theme.added_color
+        elif status == NodeStatus.REMOVED:
+            return self.theme.removed_color
+        elif status == NodeStatus.CHANGED:
+            return self.theme.changed_color
+        elif status == NodeStatus.UNCHANGED:
+            return self.theme.unchanged_color
+        else:
+            return self.theme.feature_color
+
+    def _format_version_transition(
+        self, old_version: str | None, new_version: str | None
+    ) -> str:
+        """Format version transition for diff display.
+
+        Args:
+            old_version: Old version hash
+            new_version: New version hash
+
+        Returns:
+            Formatted string like "old... → new..."
+        """
+        old_str = self._format_hash(old_version)
+        new_str = self._format_hash(new_version)
+        return (
+            f"[{self.theme.old_version_color}]{old_str}[/{self.theme.old_version_color}]... → "
+            f"[{self.theme.new_version_color}]{new_str}[/{self.theme.new_version_color}]..."
+        )
+
+    def _format_feature_key(self, key: FeatureKey) -> str:
+        """Format feature key for display.
+
+        Uses / separator instead of __ for better readability.
+
+        Args:
+            key: Feature key
+
+        Returns:
+            Formatted string like "my/feature/key"
+        """
+        return format_feature_key(key)
+
+    def _format_field_key(self, key: FieldKey) -> str:
+        """Format field key for display.
+
+        Args:
+            key: Field key
+
+        Returns:
+            Formatted string like "field_name"
+        """
+        return format_field_key(key)
+
+    def _get_filtered_graph_data(self) -> GraphData:
+        """Get filtered graph data based on config filters.
+
+        Returns:
+            GraphData with only filtered nodes and edges
+        """
+        focus_key = self.config.get_feature_key()
+
+        # If no focus feature specified, return full graph
+        if focus_key is None:
+            return self.graph_data
+
+        # Use walker to extract subgraph
+        return self.walker.extract_subgraph(
+            focus_key=focus_key,
+            up=self.config.up,
+            down=self.config.down,
+        )
+
+    def render(self) -> str:
+        """Render the graph and return string output.
+
+        Returns:
+            Rendered graph as string
+        """
+        raise NotImplementedError