Serdes CLI Tool (#25870)

## Summary & Motivation

Adds a `serdes` subcommand to `dagster-dev` for inspecting registered
serdes types. This is useful for understanding the full shape of the
serdes type registry for a given package — including objects, enums,
unions, and builtin types — without having to manually trace through
code.

The CLI supports three commands:

- **`list`** — lists all registered types, with optional `--detailed`,
`--json`, or `--html` output
- **`show <typename>`** — shows detailed info for a specific type
- **`tree <typename>`** — shows a type and all types it transitively
references, with optional \`--html\` output

The `--html` flag generates a self-contained HTML page with a table of
contents, cross-linked type references, hover tooltips showing full type
strings, and collapsible "Referenced by" backlink sections for each
type.

Type discovery works by scanning a package's source files for
`@whitelist_for_serdes` usage and importing those modules to populate
the whitelist map, then introspecting the registered serializers to
extract field types, base classes, field mappings, old fields, and other
compatibility metadata.

This is heavily claude-coded.

## Test Plan

Manual testing. Attaching screenshots.

`just serdes dagster list --html`

![image.png](https://app.graphite.com/user-attachments/assets/92de4477-34ce-4c16-9d37-b1391ec54a7d.png)

Click into an object:

![image.png](https://app.graphite.com/user-attachments/assets/84bf10a3-0d43-435a-a459-a367ff62801f.png)

Enums and unions listed separately:

![image.png](https://app.graphite.com/user-attachments/assets/b86adb1d-5c6b-4646-8efc-a5340e46e30b.png)

Union details:

![image.png](https://app.graphite.com/user-attachments/assets/2f7e1d58-ae41-487a-8261-f6595986a31c.png)

Console inspection:

```
> just serdes dagster list | grep Asset
  AllAssetCheckSelection
  AndAssetSelection
  AssetBackfillData
  AssetCheckEvaluation
  AssetCheckEvaluationPlanned
  ...
```

Can also target a specific object:

```
> just serdes dagster tree AssetDetails
AssetDetails
  Storage Name: AssetDetails
  Type: dagster._core.assets.AssetDetails
  Serializer: NamedTupleSerializer
  Fields (1):
    - last_wipe_timestamp: float | None
```

---------

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Internal-RevId: 10dc39a0c566abb8db3ac95747906fbf110db483

Author: 2 people

python_modules/automation/automation/dagster_dev/commands/serdes.py

@@ -0,0 +1,142 @@
+"""Inspect registered serdes types."""
+
+import tempfile
+import webbrowser
+
+import click
+from dagster_shared.serdes.serdes import _WHITELIST_MAP
+
+from automation.serdes.format_html import format_html
+from automation.serdes.format_json import format_json
+from automation.serdes.format_text import format_detail, format_details, format_simple_list
+from automation.serdes.registry import list_descendants, scan_registry
+from automation.serdes.scanner import discover_and_import_serdes_modules
+
+
+@click.group(name="serdes")
+@click.option(
+    "--scan",
+    multiple=True,
+    metavar="PACKAGE",
+    help="Scan and import serdes types from package (can be specified multiple times)",
+)
+@click.option("--verbose", "-v", is_flag=True, help="Show verbose output during scanning")
+@click.pass_context
+def serdes(ctx, scan, verbose):
+    """Inspect registered serdes types."""
+    ctx.ensure_object(dict)
+    ctx.obj["scan"] = scan
+    ctx.obj["verbose"] = verbose
+
+
+@serdes.command(name="list")
+@click.option("--detailed", is_flag=True, help="Show detailed information")
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+@click.option("--html", is_flag=True, help="Output as HTML")
+@click.pass_context
+def list_types(ctx, detailed, output_json, html):
+    """List all registered types.
+
+    Examples:
+      dagster-dev serdes --scan dagster list
+      dagster-dev serdes --scan dagster list --detailed
+      dagster-dev serdes --scan dagster list --json
+    """
+    scan_packages = ctx.obj["scan"]
+    verbose = ctx.obj["verbose"]
+
+    for package_name in scan_packages:
+        discover_and_import_serdes_modules(package_name, verbose=verbose)
+
+    registry = scan_registry(_WHITELIST_MAP)
+
+    if output_json:
+        click.echo(format_json(registry))
+    elif html:
+        html_content = format_html(registry)
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".html", delete=False, encoding="utf-8"
+        ) as f:
+            f.write(html_content)
+            html_path = f.name
+        click.echo(f"Opening {html_path} in browser...", err=True)
+        webbrowser.open(f"file://{html_path}")
+    elif detailed:
+        all_items = (
+            list(registry.types.values())
+            + list(registry.enums.values())
+            + list(registry.unions.values())
+        )
+        click.echo(format_details(all_items))
+    else:
+        all_items = (
+            list(registry.types.values())
+            + list(registry.enums.values())
+            + list(registry.unions.values())
+        )
+        click.echo(format_simple_list(all_items))
+
+
+@serdes.command()
+@click.argument("typename")
+@click.pass_context
+def show(ctx, typename):
+    """Show detailed info for a specific type.
+
+    Examples:
+      dagster-dev serdes --scan dagster show AssetKey
+      dagster-dev serdes --scan dagster show DagsterRunStatus
+    """
+    scan_packages = ctx.obj["scan"]
+    verbose = ctx.obj["verbose"]
+
+    for package_name in scan_packages:
+        discover_and_import_serdes_modules(package_name, verbose=verbose)
+
+    registry = scan_registry(_WHITELIST_MAP)
+    defn = registry.get(typename)
+    if defn is None:
+        raise click.ClickException(f"{typename} not found")
+    click.echo(format_detail(defn))
+
+
+@serdes.command()
+@click.argument("typename")
+@click.option("--html", is_flag=True, help="Output as HTML")
+@click.pass_context
+def tree(ctx, typename, html):
+    """Show type and all types it references recursively.
+
+    Examples:
+      dagster-dev serdes --scan dagster tree AssetKey
+      dagster-dev serdes --scan dagster_cloud tree AgentHeartbeat
+    """
+    scan_packages = ctx.obj["scan"]
+    verbose = ctx.obj["verbose"]
+
+    for package_name in scan_packages:
+        discover_and_import_serdes_modules(package_name, verbose=verbose)
+
+    registry = scan_registry(_WHITELIST_MAP)
+    defn = registry.get(typename)
+    if defn is None:
+        raise click.ClickException(f"{typename} not found")
+
+    tree_registry = list_descendants(defn.typename, registry)
+
+    if html:
+        html_content = format_html(tree_registry)
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".html", delete=False, encoding="utf-8"
+        ) as f:
+            f.write(html_content)
+            html_path = f.name
+        click.echo(f"Opening {html_path} in browser...", err=True)
+        webbrowser.open(f"file://{html_path}")
+    else:
+        all_items = (
+            list(tree_registry.types.values())
+            + list(tree_registry.enums.values())
+            + list(tree_registry.unions.values())
+        )
+        click.echo(format_details(all_items))