display graph diff in docs

Author: danielgafni

docs/.mkdocs-metaxy/src/mkdocs_metaxy/examples/core.py

@@ -259,4 +259,18 @@ def get_patch_snapshots(
             or empty dict if no execution state exists.
         """
         runbook = self.load_runbook(example_name)
-        return runbook.get_patch_snapshots()
+        patch_snapshots = runbook.get_patch_snapshots()
+
+        # TEMPORARY: Use real snapshots from the store for demonstration if no execution state
+        # Remove this once runbook execution properly captures snapshots
+        if not patch_snapshots and (
+            example_name == "recompute" or example_name == "example-recompute"
+        ):
+            return {
+                "patches/01_update_parent_algorithm.patch": (
+                    "d49e39c7ad7523cd9d25e26f9f350b73c66c979abccf2f0caee84e489035ce82",
+                    "31195f21044a744b4ea70c1ffe6432182e989ede74ed92a8c99e8cd269f14477",
+                )
+            }
+
+        return patch_snapshots

docs/.mkdocs-metaxy/src/mkdocs_metaxy/examples/plugin.py

@@ -56,8 +56,6 @@ def on_config(self, config: Any) -> Any:
         Returns:
             Modified configuration object.
         """
-        print("DEBUG: MetaxyExamplesPlugin.on_config() called")  # DEBUG
-
         # Resolve examples_dir relative to docs_dir
         docs_dir = Path(config["docs_dir"])
         examples_dir = docs_dir / self.config["examples_dir"]
@@ -312,30 +310,50 @@ def _render_patch(self, example_name: str, params: dict[str, Any]) -> str:
         generated_file.write_text(content)
 
         snippets_path = f".generated/{patch_path}"
-        patch_render = self.renderer.render_snippet(
-            path=snippets_path,
-            show_line_numbers=True,
-            hl_lines=None,
-        )
 
         # Check if we have graph diff snapshots and they are different
         if snapshots and snapshots[0] and snapshots[1] and snapshots[0] != snapshots[1]:
             # Create tabbed output with patch and graph diff
+            example_dir = self.loader.get_example_dir(example_name)
             graph_diff = self.renderer.render_graph_diff(
-                snapshots[0], snapshots[1], example_name
+                snapshots[0], snapshots[1], example_name, example_dir
             )
 
             if graph_diff:
+                # For tabs, render the patch without collapsible wrapper
+                patch_render = self.renderer.render_snippet(
+                    path=snippets_path,
+                    show_line_numbers=True,
+                    hl_lines=None,
+                    collapsible=False,  # No collapsible wrapper in tabs
+                )
                 # Use pymdownx.tabbed for tabs
+                # Indent the content for proper tab rendering
+                patch_lines = patch_render.strip().split("\n")
+                patch_indented = "\n".join(
+                    f"    {line}" if line else "" for line in patch_lines
+                )
+
+                graph_lines = graph_diff.strip().split("\n")
+                graph_indented = "\n".join(
+                    f"    {line}" if line else "" for line in graph_lines
+                )
+
                 return f"""
 === "Patch"
 
-{patch_render}
+{patch_indented}
 
 === "Graph Diff"
 
-{graph_diff}
+{graph_indented}
 """
 
-        # No graph diff available, just return the patch
+        # No graph diff available, return the patch with collapsible wrapper
+        patch_render = self.renderer.render_snippet(
+            path=snippets_path,
+            show_line_numbers=True,
+            hl_lines=None,
+            collapsible=True,  # Use collapsible when not in tabs
+        )
         return patch_render

docs/.mkdocs-metaxy/src/mkdocs_metaxy/examples/renderer.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+from pathlib import Path
 from typing import Any
 
 
@@ -236,35 +237,50 @@ def render_error(self, message: str, details: str | None = None) -> str:
         return "\n".join(md_parts)
 
     def render_graph_diff(
-        self, from_snapshot: str, to_snapshot: str, example_name: str
+        self, from_snapshot: str, to_snapshot: str, example_name: str, example_dir: Path
     ) -> str | None:
-        """Render a graph diff as Mermaid diagram.
+        """Render a graph diff as Mermaid diagram using the CLI.
 
         Args:
             from_snapshot: Before snapshot version hash.
             to_snapshot: After snapshot version hash.
             example_name: Name of the example for context.
+            example_dir: Path to the example directory.
 
         Returns:
             Mermaid diagram string or None if rendering fails.
         """
+        import subprocess
+        import sys
+
         try:
-            # We need access to the example's config to get the store
-            # For now, we'll generate a placeholder
-            # In a real implementation, we'd need to:
-            # 1. Load the example's config
-            # 2. Get the metadata store
-            # 3. Use GraphDiffer to generate the diff
-            # 4. Use MermaidRenderer to render it
-
-            # Placeholder that shows the concept
-            return f"""```mermaid
-%%{{init: {{'flowchart': {{'htmlLabels': true, 'curve': 'basis'}}, 'themeVariables': {{'fontSize': '14px'}}}}}}%%
-flowchart TD
-    %% Graph diff from {from_snapshot[:8]} to {to_snapshot[:8]}
-    placeholder[Graph diff visualization would appear here]
-    note[This requires metadata store access to render]
-```"""
-
-        except Exception:
-            return None
+            # Run metaxy graph-diff render command from the example directory
+            # Use the metaxy CLI entry point directly
+            import os
+
+            metaxy_path = os.path.join(os.path.dirname(sys.executable), "metaxy")
+
+            result = subprocess.run(
+                [
+                    metaxy_path,
+                    "graph-diff",
+                    "render",
+                    "--format",
+                    "mermaid",
+                    from_snapshot,
+                    to_snapshot,
+                ],
+                capture_output=True,
+                text=True,
+                cwd=example_dir,
+            )
+
+            if result.returncode != 0:
+                return f"```\nError rendering graph diff: {result.stderr}\n```"
+
+            # Wrap the mermaid output in a code block
+            return f"```mermaid\n{result.stdout}\n```"
+
+        except Exception as e:
+            # Return a simple error message in case of failure
+            return f"```\nError rendering graph diff: {e}\n```"

src/metaxy/graph/diff/differ.py

@@ -625,6 +625,117 @@ def _get_downstream_features(
 
         return downstream
 
+    def _compute_field_version_from_spec(
+        self,
+        feature_key: str,
+        field_key: str,
+        field_code_version: str,
+        field_deps: list[dict[str, Any]],
+        all_specs: dict[str, dict[str, Any]],
+        computed_versions: dict[tuple[str, str], str],
+    ) -> str:
+        """Compute field version from snapshot spec without loading Feature classes.
+
+        Args:
+            feature_key: Feature key string
+            field_key: Field key string
+            field_code_version: Code version of the field
+            field_deps: Field dependencies from spec
+            all_specs: All feature specs in the snapshot
+            computed_versions: Cache of already computed field versions
+
+        Returns:
+            Computed field version hash
+        """
+        import hashlib
+
+        # Check cache
+        cache_key = (feature_key, field_key)
+        if cache_key in computed_versions:
+            return computed_versions[cache_key]
+
+        # Create hasher
+        hasher = hashlib.sha256()
+
+        # Add fully qualified field key
+        fq_key = f"{feature_key}/{field_key}"
+        hasher.update(fq_key.encode())
+
+        # Add field's own code version
+        hasher.update(str(field_code_version).encode())
+
+        # Add dependent field versions
+        for dep in field_deps:
+            dep_feature = dep.get("feature") or dep.get("key", [])
+            if isinstance(dep_feature, list):
+                dep_feature_str = "/".join(dep_feature)
+            else:
+                dep_feature_str = dep_feature
+
+            dep_fields = dep.get("fields", [])
+            if not dep_fields:
+                # If no specific fields, depend on all fields of the upstream feature
+                if dep_feature_str in all_specs:
+                    dep_spec = all_specs[dep_feature_str]["feature_spec"]
+                    for dep_field_dict in dep_spec.get("fields", []):
+                        dep_field_key = dep_field_dict.get("key", [])
+                        if isinstance(dep_field_key, list):
+                            dep_field_str = "/".join(dep_field_key)
+                        else:
+                            dep_field_str = dep_field_key
+
+                        # Recursively compute dependent field version
+                        dep_field_version = self._compute_field_version_from_spec(
+                            dep_feature_str,
+                            dep_field_str,
+                            dep_field_dict.get("code_version", "__metaxy_initial__"),
+                            dep_field_dict.get("deps", []),
+                            all_specs,
+                            computed_versions,
+                        )
+                        hasher.update(dep_field_version.encode())
+            else:
+                # Specific field dependencies
+                for dep_field in dep_fields:
+                    if isinstance(dep_field, list):
+                        dep_field_str = "/".join(dep_field)
+                    else:
+                        dep_field_str = dep_field
+
+                    # Find the field spec in the upstream feature
+                    if dep_feature_str in all_specs:
+                        dep_spec = all_specs[dep_feature_str]["feature_spec"]
+                        for dep_field_dict in dep_spec.get("fields", []):
+                            field_key_from_spec = dep_field_dict.get("key", [])
+                            if isinstance(field_key_from_spec, list):
+                                field_str_from_spec = "/".join(field_key_from_spec)
+                            else:
+                                field_str_from_spec = field_key_from_spec
+
+                            if field_str_from_spec == dep_field_str:
+                                # Found the field, compute its version
+                                dep_field_version = (
+                                    self._compute_field_version_from_spec(
+                                        dep_feature_str,
+                                        dep_field_str,
+                                        dep_field_dict.get(
+                                            "code_version", "__metaxy_initial__"
+                                        ),
+                                        dep_field_dict.get("deps", []),
+                                        all_specs,
+                                        computed_versions,
+                                    )
+                                )
+                                hasher.update(dep_field_version.encode())
+                                break
+
+        # Compute and cache the version
+        from metaxy.utils.hashing import truncate_hash
+
+        version = truncate_hash(hasher.hexdigest())
+        computed_versions[cache_key] = version
+        return version
+
     def load_snapshot_data(
         self, store: MetadataStore, snapshot_version: str, project: str | None = None
     ) -> Mapping[str, Mapping[str, Any]]:
@@ -696,66 +807,34 @@ def load_snapshot_data(
                 ),  # Fallback for backward compatibility
             }
 
-        # Try to reconstruct FeatureGraph from snapshot to compute field versions
-        # This may fail if features have been removed/moved, so we handle that gracefully
-        graph: FeatureGraph | None = None
-        try:
-            graph = FeatureGraph.from_snapshot(snapshot_dict)
-            graph_available = True
-        except ImportError:
-            # Some features can't be imported (likely removed) - proceed without graph
-            # For diff purposes, we can still show feature-level changes
-            # We'll use feature_version as a fallback for all field versions
-            graph_available = False
-            warnings.warn(
-                "Using feature_version as field_version fallback for features that cannot be imported. "
-                "This may occur when features have been removed or moved.",
-                UserWarning,
-                stacklevel=2,
-            )
-
-        # Compute field versions using the reconstructed graph (if available)
-        from metaxy.models.plan import FQFieldKey
-
+        # Compute field versions directly from snapshot specs without loading Feature classes
+        # This ensures we use the actual snapshot's field specs, not the current code
         snapshot_data = {}
+        computed_versions: dict[tuple[str, str], str] = {}
+
         for feature_key_str in snapshot_dict.keys():
             feature_version = snapshot_dict[feature_key_str]["metaxy_feature_version"]
             feature_spec = snapshot_dict[feature_key_str]["feature_spec"]
-            feature_key_obj = FeatureKey(feature_key_str.split("/"))
 
-            # Compute field versions using graph (if available)
+            # Compute field versions from the snapshot's specs
             fields_data = {}
-            if (
-                graph_available
-                and graph is not None
-                and feature_key_obj in graph.features_by_key
-            ):
-                # Feature exists in reconstructed graph - compute precise field versions
-                for field_dict in feature_spec.get("fields", []):
-                    field_key_list = field_dict.get("key")
-                    if isinstance(field_key_list, list):
-                        field_key = FieldKey(field_key_list)
-                        field_key_str_normalized = "/".join(field_key_list)
-                    else:
-                        field_key = FieldKey([field_key_list])
-                        field_key_str_normalized = field_key_list
-
-                    # Compute field version using the graph
-                    fq_key = FQFieldKey(feature=feature_key_obj, field=field_key)
-                    field_version = graph.get_field_version(fq_key)
-                    fields_data[field_key_str_normalized] = field_version
-            else:
-                # Feature doesn't exist in graph (removed/moved) - use feature_version as fallback
-                # All fields get the same version (the feature version)
-                for field_dict in feature_spec.get("fields", []):
-                    field_key_list = field_dict.get("key")
-                    if isinstance(field_key_list, list):
-                        field_key_str_normalized = "/".join(field_key_list)
-                    else:
-                        field_key_str_normalized = field_key_list
-
-                    # Use feature_version directly as fallback
-                    fields_data[field_key_str_normalized] = feature_version
+            for field_dict in feature_spec.get("fields", []):
+                field_key_list = field_dict.get("key")
+                if isinstance(field_key_list, list):
+                    field_key_str_normalized = "/".join(field_key_list)
+                else:
+                    field_key_str_normalized = field_key_list
+
+                # Compute field version using the snapshot's specs
+                field_version = self._compute_field_version_from_spec(
+                    feature_key_str,
+                    field_key_str_normalized,
+                    field_dict.get("code_version", "__metaxy_initial__"),
+                    field_dict.get("deps", []),
+                    snapshot_dict,
+                    computed_versions,
+                )
+                fields_data[field_key_str_normalized] = field_version
 
             snapshot_data[feature_key_str] = {
                 "metaxy_feature_version": feature_version,