Implementation:MaterializeInc Materialize Crate Diagram CLI

Overview

The crate diagram CLI tool generates a dependency graph of the internal Rust crates in the Materialize repository. Unlike general-purpose tools such as cargo-graph that visualize the entire dependency tree (which can be overwhelming with hundreds of crates), this tool focuses exclusively on local workspace crates to show how they fit into the Materialize ecosystem.

The tool is located at misc/python/materialize/cli/crate_diagram.py.

Purpose

The Materialize repository contains hundreds of Rust crates. Visualizing the full dependency graph is impractical, so this tool generates a focused SVG diagram showing only the relationships between internal workspace crates. This helps developers understand the crate architecture and identify coupling patterns.

CLI Interface

The tool uses Click for argument parsing:

@click.command(context_settings=dict(help_option_names=["-h", "--help"]))
@click.option("--roots", default="", type=split_list,
    help="Only include these crates and their dependencies.")
@click.option("--show/--no-show", default=True,
    help="Wheather or not to immediatly show the generated diagram")
@click.option("--diagram-file", default=None,
    help="The diagram file to generate. Default is 'crates{roots}.svg'")
def main(show: bool, diagram_file: str | None, roots: list[str]) -> None:

Options

Option	Default	Description
--roots	(empty)	Comma-separated list of crate names to use as roots; only these crates and their transitive dependencies are included
--show / --no-show	--show	Whether to immediately open the generated SVG in a browser
--diagram-file	auto-generated	Output SVG file name; defaults to crates.svg or crates-{root1}-{root2}.svg if roots are specified

Implementation

Workspace Parsing

The tool reads the root Cargo.toml to discover workspace members, then for each member:

1. Parses the member's Cargo.toml using the toml library.
2. Detects whether the crate has a binary target by checking for src/**/main.rs.
3. Collects crate metadata including name, dependencies, and area classification.

root_cargo = MZ_ROOT / "Cargo.toml"
with root_cargo.open() as fh:
    data = toml.load(fh)

for member_path in data["workspace"]["members"]:
    path = MZ_ROOT / member_path / "Cargo.toml"
    with path.open() as fh:
        member = toml.load(fh)
    has_bin = any(MZ_ROOT.joinpath(member_path).glob("src/**/main.rs"))

Output File Naming

The output file name is determined dynamically:

• With no roots: crates.svg
• With roots: crates-{sorted-root-names}.svg (roots joined with hyphens)

Type Aliases

The module defines type aliases for dependency tracking:

Type	Definition	Purpose
DepBuilder	defaultdict[str, list[str]]	Accumulates dependencies during parsing
DepMap	dict[str, list[str]]	Finalized dependency mapping

Helper Functions

The split_list function converts a comma-separated string into a list, used as a Click option callback:

def split_list(items: str) -> list[str]:
    if items:
        return items.split(",")
    return []

Key Source Files

File	Path
Crate diagram CLI	misc/python/materialize/cli/crate_diagram.py