toolpath-dot

Generate Graphviz DOT visualizations from Toolpath documents.

Provenance data is only useful if you can see it. This crate renders the step DAG as a Graphviz diagram so you can see at a glance who did what, where the dead ends branched off, and how human/agent/tool contributions interleave — color-coded by actor type.

Overview

Renders any Toolpath Document (Step, Path, or Graph) as a Graphviz DOT string. Steps are colored by actor type, dead ends are highlighted, and the DAG structure is preserved visually.

Depends only on toolpath -- no external rendering libraries. You'll need Graphviz installed to convert DOT output to images (dot -Tpng).

Usage

use toolpath::v1::Document;
use toolpath_dot::{render, RenderOptions};

let json_str = r#"{"Step":{"step":{"id":"s1","actor":"human:alex","timestamp":"T"},"change":{}}}"#;
let doc = Document::from_json(json_str).unwrap();
let dot = render(&doc, &RenderOptions::default());
assert!(dot.contains("digraph"));

Pipe through Graphviz to produce images:

path derive git --repo . --branch main | path render dot | dot -Tpng -o graph.png

Render options

use toolpath_dot::RenderOptions;

let options = RenderOptions {
    show_files: true,           // list changed files in step labels
    show_timestamps: true,      // show timestamps in step labels
    highlight_dead_ends: true,  // dashed red border on dead-end steps (default)
};

API

Function	Description
`render(doc, options)`	Render any `Document` variant
`render_step(step, options)`	Render a single Step
`render_path(path, options)`	Render a Path with its step DAG
`render_graph(graph, options)`	Render a Graph with subgraph clusters per path
`actor_color(actor)`	Get the fill color for an actor type
`escape_dot(s)`	Escape a string for DOT labels
`escape_html(s)`	Escape a string for HTML-like labels

Visual conventions

Actor type	Color
`human:*`	Blue (`#cce5ff`)
`agent:*`	Green (`#d4edda`)
`tool:*`	Yellow (`#fff3cd`)
`ci:*`	Purple (`#e2d5f1`)
Dead ends	Red dashed border (`#ffcccc`)
BASE node	Gray ellipse

Color-coding makes multi-actor provenance scannable at a glance: you can immediately see where human work ends and agent work begins, and the red dashed borders draw your eye to abandoned approaches without cluttering the main path.

Part of Toolpath

This crate is part of the Toolpath workspace. See also:

toolpath -- core types and query API
toolpath-git -- derive from git history
toolpath-claude -- derive from Claude conversations
path-cli -- unified CLI (cargo install path-cli)
RFC -- full format specification