metaxy 0.0.1.dev3__py3-none-any.whl

metaxy/cli/graph_diff.py

@@ -0,0 +1,290 @@
+"""Graph diff commands for Metaxy CLI."""
+
+from typing import Annotated, Literal
+
+import cyclopts
+
+from metaxy.cli.console import console, data_console, error_console
+from metaxy.graph import RenderConfig
+
+# Graph-diff subcommand app
+app = cyclopts.App(
+    name="graph-diff",  # pyrefly: ignore[unexpected-keyword]
+    help="Compare and visualize graph snapshots",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+    error_console=error_console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def render(
+    from_snapshot: Annotated[
+        str,
+        cyclopts.Parameter(
+            help='First snapshot to compare (can be "latest", "current", or snapshot hash)',
+        ),
+    ],
+    to_snapshot: Annotated[
+        str,
+        cyclopts.Parameter(
+            help='Second snapshot to compare (can be "latest", "current", or snapshot hash)',
+        ),
+    ] = "current",
+    store: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--store"],
+            help="Metadata store to use (defaults to configured default store)",
+        ),
+    ] = None,
+    format: Annotated[
+        Literal["terminal", "cards", "mermaid", "graphviz", "json", "yaml"],
+        cyclopts.Parameter(
+            name=["--format", "-f"],
+            help="Output format: terminal, cards, mermaid, graphviz, json, or yaml",
+        ),
+    ] = "terminal",
+    output: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--output", "-o"],
+            help="Output file path (default: stdout)",
+        ),
+    ] = None,
+    config: Annotated[
+        RenderConfig | None,
+        cyclopts.Parameter(name="*", help="Render configuration"),
+    ] = None,
+    # Preset modes
+    minimal: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--minimal"],
+            help="Minimal output: only feature keys and dependencies",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose"],
+            help="Verbose output: show all available information",
+        ),
+    ] = False,
+):
+    """Render merged graph visualization comparing two snapshots.
+
+    Shows all features color-coded by status (added/removed/changed/unchanged).
+    Uses the unified rendering system - same renderers as 'metaxy graph render'.
+
+    Special snapshot literals:
+    - "latest": Most recent snapshot in the store
+    - "current": Current graph state from code
+
+    Output formats:
+    - terminal: Hierarchical tree view (default)
+    - cards: Panel/card-based view
+    - mermaid: Mermaid flowchart diagram
+    - graphviz: Graphviz DOT format
+
+    Examples:
+        # Show merged graph with default terminal renderer
+        $ metaxy graph-diff render latest current
+
+        # Cards view
+        $ metaxy graph-diff render latest current --format cards
+
+        # Focus on specific feature with 2 levels up and 1 level down
+        $ metaxy graph-diff render latest current --feature user/profile --up 2 --down 1
+
+        # Show only changed fields (hide unchanged)
+        $ metaxy graph-diff render latest current --show-changed-fields-only
+
+        # Save Mermaid diagram to file
+        $ metaxy graph-diff render latest current --format mermaid --output diff.mmd
+
+        # Graphviz DOT format
+        $ metaxy graph-diff render latest current --format graphviz --output diff.dot
+
+        # Minimal view
+        $ metaxy graph-diff render latest current --minimal
+
+        # Everything
+        $ metaxy graph-diff render latest current --verbose
+    """
+    from metaxy.graph import (
+        CardsRenderer,
+        GraphData,
+        GraphvizRenderer,
+    )
+    from metaxy.graph.diff.differ import GraphDiffer, SnapshotResolver
+
+    # Validate format
+    valid_formats = ["terminal", "cards", "mermaid", "graphviz", "json", "yaml"]
+    if format not in valid_formats:
+        console.print(
+            f"[red]Error:[/red] Invalid format '{format}'. Must be one of: {', '.join(valid_formats)}"
+        )
+        raise SystemExit(1)
+
+    # Resolve configuration from presets
+    if minimal and verbose:
+        console.print("[red]Error:[/red] Cannot specify both --minimal and --verbose")
+        raise SystemExit(1)
+
+    # If config is None, create a default instance
+    if config is None:
+        config = RenderConfig()
+
+    # Apply presets if specified (overrides display settings but preserves filtering)
+    if minimal:
+        preset = RenderConfig.minimal()
+        # Preserve filtering parameters from original config
+        preset.feature = config.feature
+        preset.up = config.up
+        preset.down = config.down
+        config = preset
+    elif verbose:
+        preset = RenderConfig.verbose()
+        # Preserve filtering parameters from original config
+        preset.feature = config.feature
+        preset.up = config.up
+        preset.down = config.down
+        config = preset
+
+    # Validate filtering options
+    if (config.up is not None or config.down is not None) and config.feature is None:
+        console.print(
+            "[red]Error:[/red] --up and --down require --feature to be specified"
+        )
+        raise SystemExit(1)
+
+    from metaxy.cli.context import AppContext
+
+    context = AppContext.get()
+    metadata_store = context.get_store(store)
+    graph = context.graph
+    project = context.get_required_project()  # This command needs a specific project
+
+    with metadata_store:
+        # Resolve snapshot versions
+        resolver = SnapshotResolver()
+        try:
+            from_snapshot_version = resolver.resolve_snapshot(
+                from_snapshot, metadata_store, graph
+            )
+            to_snapshot_version = resolver.resolve_snapshot(
+                to_snapshot, metadata_store, graph
+            )
+        except ValueError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+
+        # Load snapshot data
+        differ = GraphDiffer()
+        try:
+            from_snapshot_data = differ.load_snapshot_data(
+                metadata_store, from_snapshot_version, project
+            )
+            to_snapshot_data = differ.load_snapshot_data(
+                metadata_store, to_snapshot_version, project
+            )
+        except ValueError as e:
+            console.print(f"[red]Error:[/red] {e}")
+            raise SystemExit(1)
+
+        # Compute diff
+        graph_diff = differ.diff(from_snapshot_data, to_snapshot_data)
+
+        # Create merged graph data
+        merged_data = differ.create_merged_graph_data(
+            from_snapshot_data, to_snapshot_data, graph_diff
+        )
+
+        # Apply graph slicing if requested
+        if config.feature is not None:
+            try:
+                merged_data = differ.filter_merged_graph(
+                    merged_data,
+                    focus_feature=config.feature,
+                    up=config.up,
+                    down=config.down,
+                )
+            except ValueError as e:
+                console.print(f"[red]Error:[/red] {e}")
+                raise SystemExit(1)
+
+        # Render the diff
+        # Use DiffFormatter for terminal/json/yaml/mermaid (has proper diff visualization)
+        # Use unified renderers for cards/graphviz (DiffFormatter doesn't support these)
+        if format in ("terminal", "mermaid", "json", "yaml"):
+            from metaxy.graph.diff.rendering.formatter import DiffFormatter
+
+            formatter = DiffFormatter(console)
+
+            # Determine show_all_fields based on config
+            # TODO: add show_changed_fields_only to config
+            show_all_fields = True  # Default: show all fields
+
+            try:
+                rendered = formatter.format(
+                    merged_data=merged_data,
+                    format=format,
+                    verbose=verbose,
+                    diff_only=False,  # Always use merged view for graph-diff render
+                    show_all_fields=show_all_fields,
+                )
+            except Exception as e:
+                from metaxy.cli.utils import print_error
+
+                print_error(console, "Rendering failed", e, prefix="[red]Error:[/red]")
+                import traceback
+
+                traceback.print_exc()
+                raise SystemExit(1)
+        else:
+            # Use unified renderers for cards/graphviz formats
+            from metaxy.graph.diff.rendering.theme import Theme
+
+            theme = Theme.default()
+            graph_data = GraphData.from_merged_diff(merged_data)
+
+            if format == "cards":
+                renderer = CardsRenderer(
+                    graph_data=graph_data, config=config, theme=theme
+                )
+            elif format == "graphviz":
+                renderer = GraphvizRenderer(
+                    graph_data=graph_data, config=config, theme=theme
+                )
+            else:
+                console.print(f"[red]Error:[/red] Unknown format: {format}")
+                raise SystemExit(1)
+
+            try:
+                rendered = renderer.render()
+            except Exception as e:
+                from metaxy.cli.utils import print_error
+
+                print_error(console, "Rendering failed", e, prefix="[red]Error:[/red]")
+                import traceback
+
+                traceback.print_exc()
+                raise SystemExit(1)
+
+        # Output to file or stdout
+        if output:
+            try:
+                with open(output, "w") as f:
+                    f.write(rendered)
+                console.print(f"[green]Success:[/green] Diff rendered to: {output}")
+            except Exception as e:
+                from metaxy.cli.utils import print_error
+
+                print_error(
+                    console, "Failed to write to file", e, prefix="[red]Error:[/red]"
+                )
+                raise SystemExit(1)
+        else:
+            # Print to stdout using data_console
+            # Rendered diff output is data that users might pipe/redirect
+            data_console.print(rendered)

metaxy/cli/list.py

@@ -0,0 +1,46 @@
+import cyclopts
+
+from metaxy.cli.console import console, data_console, error_console
+
+# List subcommand app
+app = cyclopts.App(
+    name="list",  # pyrefly: ignore[unexpected-keyword]
+    help="List Metaxy entities",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+    error_console=error_console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def features():
+    """
+    List Metaxy features.
+    """
+    from metaxy import get_feature_by_key
+    from metaxy.cli.context import AppContext
+    from metaxy.models.plan import FQFieldKey
+
+    context = AppContext.get()
+    graph = context.graph
+
+    for feature_key, feature_spec in graph.feature_specs_by_key.items():
+        if (
+            context.project
+            and get_feature_by_key(feature_key).project != context.project
+        ):
+            continue
+        data_console.print("---")
+        version = graph.get_feature_version(feature_key)
+        data_console.print(f"{feature_key} (version\n{version})")
+        if feature_spec.deps:
+            data_console.print("  Feature Dependencies:")
+            for dep in feature_spec.deps:
+                data_console.print(f"    {dep}")
+        data_console.print("  Fields:")
+        for field_key, field_spec in feature_spec.fields_by_key.items():
+            field_version = graph.get_field_version(
+                FQFieldKey(feature=feature_key, field=field_key)
+            )
+            data_console.print(
+                f"    {field_spec.key.to_string()} (code_version {field_spec.code_version}, version\n{field_version})"
+            )

metaxy/cli/metadata.py

@@ -0,0 +1,317 @@
+"""Metadata management commands for Metaxy CLI."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Annotated, Any
+
+import cyclopts
+from pydantic import TypeAdapter
+
+from metaxy.cli.console import console, data_console, error_console
+from metaxy.cli.utils import (
+    CLIError,
+    FeatureSelector,
+    OutputFormat,
+    exit_with_error,
+    load_graph_for_command,
+)
+from metaxy.graph.status import FullFeatureMetadataRepresentation
+
+if TYPE_CHECKING:
+    pass
+
+# Metadata subcommand app
+app = cyclopts.App(
+    name="metadata",  # pyrefly: ignore[unexpected-keyword]
+    help="Manage Metaxy metadata",  # pyrefly: ignore[unexpected-keyword]
+    console=console,  # pyrefly: ignore[unexpected-keyword]
+    error_console=error_console,  # pyrefly: ignore[unexpected-keyword]
+)
+
+
+@app.command()
+def status(
+    *,
+    selector: FeatureSelector = FeatureSelector(),
+    store: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--store"],
+            help="Metadata store name (defaults to configured default store).",
+        ),
+    ] = None,
+    snapshot_version: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--snapshot-id"],
+            help="Check metadata against a specific snapshot version.",
+        ),
+    ] = None,
+    assert_in_sync: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--assert-in-sync"],
+            help="Exit with error if any feature needs updates or metadata is missing.",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose"],
+            help="Show additional details about samples needing updates.",
+        ),
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        cyclopts.Parameter(
+            name=["--format"],
+        ),
+    ] = "plain",
+) -> None:
+    """Check metadata completeness and freshness for specified features.
+
+    Examples:
+        $ metaxy metadata status --feature user_features
+        $ metaxy metadata status --feature feat1 --feature feat2
+        $ metaxy metadata status --all-features
+        $ metaxy metadata status --store dev --all-features
+    """
+    from metaxy.cli.context import AppContext
+    from metaxy.graph.status import get_feature_metadata_status
+
+    # Validate feature selection
+    selector.validate(format)
+
+    context = AppContext.get()
+    metadata_store = context.get_store(store)
+
+    with metadata_store:
+        # Load graph (from snapshot or current)
+        graph = load_graph_for_command(
+            context, snapshot_version, metadata_store, format
+        )
+
+        # Resolve feature keys
+        valid_keys, missing_keys = selector.resolve_keys(graph, format)
+
+        # Handle empty result for --all-features
+        if selector.all_features and not valid_keys:
+            _output_no_features_warning(format, snapshot_version)
+            return
+
+        # Handle missing features
+        if missing_keys:
+            if assert_in_sync:
+                exit_with_error(
+                    CLIError(
+                        code="FEATURES_NOT_FOUND",
+                        message="Feature(s) not found in graph",
+                        details={"features": [k.to_string() for k in missing_keys]},
+                    ),
+                    format,
+                )
+            elif format == "plain":
+                formatted = ", ".join(k.to_string() for k in missing_keys)
+                data_console.print(
+                    f"[yellow]Warning:[/yellow] Feature(s) not found in graph: {formatted}"
+                )
+
+        # If no valid features remain
+        if not valid_keys:
+            _output_no_features_warning(format, snapshot_version)
+            return
+
+        # Print header for plain format
+        if format == "plain":
+            header = (
+                f"Metadata status (snapshot {snapshot_version})"
+                if snapshot_version
+                else "Metadata status"
+            )
+            data_console.print(f"\n[bold]{header}[/bold]")
+
+        # Collect status for all features
+        needs_update = False
+        feature_reps: dict[str, FullFeatureMetadataRepresentation] = {}
+
+        for feature_key in valid_keys:
+            feature_cls = graph.features_by_key[feature_key]
+            status_with_increment = get_feature_metadata_status(
+                feature_cls, metadata_store
+            )
+
+            if status_with_increment.status.needs_update:
+                needs_update = True
+
+            if format == "json":
+                feature_reps[feature_key.to_string()] = (
+                    status_with_increment.to_representation(
+                        feature_cls=feature_cls, verbose=verbose
+                    )
+                )
+            else:
+                data_console.print(status_with_increment.status.format_status_line())
+                if verbose:
+                    for line in status_with_increment.sample_details(feature_cls):
+                        data_console.print(line)
+
+        # Output JSON result
+        if format == "json":
+            adapter = TypeAdapter(dict[str, FullFeatureMetadataRepresentation])
+            output: dict[str, Any] = {
+                "snapshot_version": snapshot_version,
+                "features": json.loads(
+                    adapter.dump_json(feature_reps, exclude_none=True)
+                ),
+                "needs_update": needs_update,
+            }
+            if missing_keys:
+                output["warnings"] = {
+                    "missing_in_graph": [k.to_string() for k in missing_keys]
+                }
+            print(json.dumps(output, indent=2))
+
+        # Exit with error if assert_in_sync and updates needed
+        if assert_in_sync and needs_update:
+            raise SystemExit(1)
+
+
+def _output_no_features_warning(
+    format: OutputFormat, snapshot_version: str | None
+) -> None:
+    """Output warning when no features are found to check."""
+    if format == "json":
+        print(
+            json.dumps(
+                {
+                    "warning": "No valid features to check",
+                    "features": {},
+                    "snapshot_version": snapshot_version,
+                    "needs_update": False,
+                },
+                indent=2,
+            )
+        )
+    else:
+        data_console.print("[yellow]Warning:[/yellow] No valid features to check.")
+
+
+@app.command()
+def drop(
+    *,
+    selector: FeatureSelector = FeatureSelector(),
+    store: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--store"],
+            help="Store name to drop metadata from (defaults to configured default store).",
+        ),
+    ] = None,
+    confirm: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--confirm"],
+            help="Confirm the drop operation (required to prevent accidental deletion).",
+        ),
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        cyclopts.Parameter(
+            name=["--format"],
+            help="Output format: 'plain' (default) or 'json'.",
+        ),
+    ] = "plain",
+) -> None:
+    """Drop metadata from a store.
+
+    Removes metadata for specified features. This is destructive and requires --confirm.
+
+    Examples:
+        $ metaxy metadata drop --feature user_features --confirm
+        $ metaxy metadata drop --feature feat1 --feature feat2 --confirm
+        $ metaxy metadata drop --store dev --all-features --confirm
+    """
+    from metaxy.cli.context import AppContext
+
+    # Validate feature selection
+    selector.validate(format)
+
+    # Require confirmation
+    if not confirm:
+        exit_with_error(
+            CLIError(
+                code="MISSING_CONFIRMATION",
+                message="This is a destructive operation. Must specify --confirm flag.",
+                details={"required_flag": "--confirm"},
+            ),
+            format,
+        )
+
+    context = AppContext.get()
+    context.raise_command_cannot_override_project()
+    metadata_store = context.get_store(store)
+
+    with metadata_store.open("write"):
+        graph = context.graph
+
+        # Resolve feature keys
+        valid_keys, _ = selector.resolve_keys(graph, format)
+
+        # Handle no features
+        if not valid_keys:
+            if format == "json":
+                print(
+                    json.dumps(
+                        {
+                            "warning": "NO_FEATURES_FOUND",
+                            "message": "No features found in active graph.",
+                            "features_dropped": 0,
+                        }
+                    )
+                )
+            else:
+                console.print(
+                    "[yellow]Warning:[/yellow] No features found in active graph."
+                )
+            return
+
+        if format == "plain":
+            console.print(
+                f"\n[bold]Dropping metadata for {len(valid_keys)} feature(s)...[/bold]\n"
+            )
+
+        # Drop each feature
+        dropped: list[str] = []
+        failed: list[dict[str, str]] = []
+
+        for feature_key in valid_keys:
+            key_str = feature_key.to_string()
+            try:
+                metadata_store.drop_feature_metadata(feature_key)
+                dropped.append(key_str)
+                if format == "plain":
+                    console.print(f"[green]✓[/green] Dropped: {key_str}")
+            except Exception as e:
+                failed.append({"feature": key_str, "error": str(e)})
+                if format == "plain":
+                    from metaxy.cli.utils import print_error_item
+
+                    print_error_item(
+                        console, key_str, e, prefix="[red]✗[/red] Failed to drop"
+                    )
+
+        # Output result
+        if format == "json":
+            result: dict[str, Any] = {
+                "success": True,
+                "features_dropped": len(dropped),
+                "dropped": dropped,
+            }
+            if failed:
+                result["failed"] = failed
+            print(json.dumps(result, indent=2))
+        else:
+            console.print(
+                f"\n[green]✓[/green] Drop complete: {len(dropped)} feature(s) dropped"
+            )