Crate toolpath_dot

Expand description

§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.

§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

§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
toolpath-cli – unified CLI (cargo install toolpath-cli)
RFC – full format specification

Structs§

RenderOptions: Options controlling what information is rendered in the DOT output.

Functions§

actor_color: Return a fill color for a given actor string.
escape_dot: Escape a string for use in DOT label attributes (double-quoted context).
escape_html: Escape a string for use inside HTML-like DOT labels.
render: Render any Toolpath Document variant to a Graphviz DOT string.
render_graph: Render a Graph as a DOT digraph.
render_path: Render a Path as a DOT digraph.
render_step: Render a single Step as a DOT digraph.